Apache Beam 및 SpannerIO를 사용하여 Spanner Omni에 연결

Apache Beam은 일괄 및 스트리밍 데이터 병렬 처리 파이프라인을 모두 정의할 수 있는 오픈소스 통합 모델입니다. 이 문서에서는 Apache Beam 파이프라인 내에서 SpannerIO 커넥터를 사용하여 Spanner Omni 데이터베이스에서 읽거나 쓰는 방법을 설명합니다.

시작하기 전에

SpannerIO를 Spanner Omni에 연결하려면 다음 요구사항을 충족해야 합니다.

  • Spanner Omni 환경 내에서 데이터베이스를 초기화합니다.

  • 암호화를 사용하는 경우 호환되는 Apache Beam 버전을 사용해야 합니다.

    • TLS 암호화의 경우 버전 2.69.0 이상
    • 상호 TLS (mTLS) 암호화의 경우 버전 2.75.0 이상

  • 환경의 인증 사용자 인증 정보를 설정합니다.

Spanner Omni에 연결하도록 SpannerIO 구성

SpannerIO를 Spanner Omni에 연결하려면 데이터베이스 세부정보와 연결 매개변수를 사용하여 SpannerConfig를 구성하세요.

연결을 구성하려면 다음 연결 모드 중 하나를 선택합니다.

일반 텍스트 통신을 사용하여 연결

일반 텍스트 연결을 설정하려면 Spanner Omni 엔드포인트를 지정하고 withExperimentalHost() 메서드로 실험적 호스트 지원을 사용 설정하고 withUsingPlainTextChannel() 메서드로 파이프라인을 구성합니다.

다음 예시에서는 일반 텍스트 연결을 구성하는 방법을 보여줍니다.

SpannerConfig spannerConfig =
    SpannerConfig.create()
        .withDatabaseId("DATABASE_ID")
        // Define the Spanner Omni endpoint
        .withExperimentalHost("http://ENDPOINT")
        // Use a plain-text connection
        .withUsingPlainTextChannel(true);

다음을 바꿉니다.

  • DATABASE_ID: Spanner Omni 데이터베이스의 ID입니다(예: test-db).

  • ENDPOINT: Spanner Omni 인스턴스의 엔드포인트입니다(예: localhost:15000).

암호화를 사용하여 연결

데이터베이스 트래픽을 보호하고 Apache Beam과 Spanner Omni 간의 보안 통신을 보장하려면 TLS 또는 mTLS 암호화를 사용하여 연결하면 됩니다. 암호화를 사용하면 사용자 인증 정보와 데이터를 기밀로 유지할 수 있습니다.

TLS 암호화 사용

TLS 암호화를 사용하여 Apache Beam과 Spanner Omni 간의 데이터베이스 트래픽을 보호하려면 SpannerConfig에서 사용자 인증 정보 속성을 지정하지 않아도 됩니다. 대신 Spanner Omni CA 인증서로 Java 신뢰 저장소를 구성한 다음 보안 TLS 엔드포인트를 사용하도록 SpannerConfig를 구성합니다.

1단계: Java 신뢰 저장소 구성

통신을 보호하려면 Spanner Omni에서 생성한 CA 인증서를 Java 공인스토어로 가져와야 합니다. 다음 옵션 중 하나를 사용합니다.

기본 Java 신뢰 저장소

다음 명령어를 실행하여 Spanner Omni에서 생성된 CA 인증서를 표준 Java 신뢰 저장소에 추가합니다.

sudo keytool -import -trustcacerts \
  -file ~/.spanner/certs/ca.crt \
  -alias spanner-ca \
  -keystore $JAVA_HOME/lib/security/cacerts

맞춤 트러스트 저장소

파이프라인이 표준 인증 기관 (CA)을 사용하는 다른 데이터베이스 또는 서비스에 계속 연결할 수 있도록 하려면 커스텀 신뢰 저장소를 만드세요.

  1. 기존 Java 트러스트 저장소를 복사하여 맞춤 트러스트 저장소를 만듭니다.

    cp $JAVA_HOME/lib/security/cacerts PATH_TO_CUSTOM_CA_CERTIFICATE

  2. CA 인증서를 맞춤 신뢰 저장소로 가져옵니다.

    keytool -import -trustcacerts \
  -file ~/.spanner/certs/ca.crt \
  -alias spanner-ca \
  -keystore PATH_TO_CUSTOM_CA_CERTIFICATE

  3. 파이프라인을 실행할 때 맞춤 CA 인증서 저장소를 전달합니다.

    java -Djavax.net.ssl.trustStore=PATH_TO_CUSTOM_CA_CERTIFICATE \
  -Djavax.net.ssl.trustStorePassword=changeit \
  -jar PIPELINE_NAME.jar

다음을 바꿉니다.

  • PATH_TO_CUSTOM_CA_CERTIFICATE: 맞춤 CA 인증서 저장소의 경로입니다.

  • PIPELINE_NAME: Apache Beam 파이프라인의 이름입니다.

2단계: SpannerConfig 구성

보안 TLS 연결을 사용하도록 SpannerConfig를 구성하려면 파이프라인에 다음 코드를 추가하세요.

SpannerConfig spannerConfig =
    SpannerConfig.create()
        .withDatabaseId("DATABASE_ID")
        // Define the secure Spanner Omni endpoint
        .withExperimentalHost("https://ENDPOINT");

다음을 바꿉니다.

  • DATABASE_ID: Spanner Omni 데이터베이스의 ID입니다(예: test-db).

  • ENDPOINT: Spanner Omni 인스턴스의 엔드포인트입니다(예: localhost:15000).

mTLS 암호화 사용

Apache Beam을 사용하여 상호 TLS (mTLS) 연결을 설정하려면 CA 인증서로 Java truststore를 구성하고, 클라이언트 비공개 키를 PKCS#8 형식으로 생성하거나 변환한 후 클라이언트 인증서 및 키 경로로 SpannerConfig를 구성해야 합니다.

1단계: Java 신뢰 저장소 구성

이 문서의 앞부분에 나오는 1단계: Java 트러스트 저장소 구성에 설명된 대로 Spanner Omni CA 인증서로 Java 트러스트 저장소를 구성합니다.

2단계: 클라이언트 비공개 키 변환 또는 생성

mTLS를 사용하여 연결하려면 클라이언트 비공개 키가 PKCS#8 형식이어야 합니다. 다음 옵션 중 하나를 사용합니다.

openssl

Spanner Omni에서 생성된 클라이언트 키를 Java와 호환되는 형식으로 변환하려면 다음 명령어를 실행합니다.

openssl pkcs8 -topk8 \
  -in ~/.spanner/certs/client.key \
  -out ~/.spanner/certs/java-client.key \
  -nocrypt

Spanner Omni CLI

--generate-pkcs8-key 플래그와 함께 Spanner Omni CLI를 사용하여 클라이언트 인증서를 만들 때 PKCS#8 형식으로 직접 키를 생성합니다.

PKCS#8 형식으로 클라이언트 인증서와 클라이언트 비공개 키를 생성하려면 다음 명령어를 실행하세요.

spanner certificates create-client CLIENT_NAME \
  --ca-certificate-directory=PATH_TO_CA_CERTIFICATES \
  --ca-private-key-directory=PATH_TO_PRIVATE_KEYS \
  --output-directory=PATH_TO_CERTIFICATES \
  --generate-pkcs8-key

다음을 바꿉니다.

  • CLIENT_NAME: 인증서와 비공개 키를 생성할 클라이언트의 이름입니다.

  • PATH_TO_CA_CERTIFICATES: CA 인증서가 포함된 디렉터리의 경로입니다.

  • PATH_TO_PRIVATE_KEYS: CA 비공개 키가 포함된 디렉터리의 경로입니다.

  • PATH_TO_CERTIFICATES: 클라이언트 인증서와 비공개 키가 저장된 디렉터리의 경로입니다.

3단계: SpannerConfig 구성

클라이언트 인증서와 클라이언트 비공개 키를 사용하여 파이프라인 코드에서 SpannerConfig을 구성합니다.

SpannerConfig spannerConfig =
    SpannerConfig.create()
        .withDatabaseId("DATABASE_ID")
        // Define the secure Spanner Omni endpoint
        .withExperimentalHost("https://ENDPOINT")
        // Specify the paths to the client certificate and private key
        .withClientCert(
            "PATH_TO_CLIENT_CERT",
            "PATH_TO_CLIENT_CERT_KEY");

다음을 바꿉니다.

  • DATABASE_ID: Spanner Omni 데이터베이스의 ID입니다(예: test-db).

  • ENDPOINT: Spanner Omni 인스턴스의 엔드포인트입니다(예: localhost:15000).

  • PATH_TO_CLIENT_CERT: 클라이언트 인증서 파일의 경로입니다.

  • PATH_TO_CLIENT_CERT_KEY: 클라이언트 비공개 키 파일의 경로입니다.

인증 토큰 구성

인증 토큰은 Spanner Omni에서 생성된 토큰이 만료되고 Spanner Omni CLI를 사용하여 수동으로 갱신해야 하므로 클라이언트용으로 권장되지 않습니다. Spanner Omni 엔드포인트의 TLS 또는 mTLS 설정과 함께 인증 토큰을 사용하려면 SPANNER_EXPERIMENTAL_HOST_AUTH_TOKEN 환경 변수를 Spanner Omni CLI에서 생성된 인증 토큰의 값으로 설정하세요. 사용자 인증 정보가 필요하지 않은 연결의 경우 이 변수를 설정하지 않은 상태로 둡니다.

다음 단계