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

미리보기

이 제품 또는 기능은 서비스별 약관의 일반 서비스 약관 섹션에 있는 "GA 이전 제공 서비스 약관"이 적용되는 미리보기 제공 서비스이며, 소프트웨어 프로그램 개발, 테스트, 프로토타입 제작, 데모 목적으로만 사용할 수 있습니다. 데이터 처리 또는 상업적 목적으로는 사용할 수 없습니다. GA 이전 제품 및 기능은 '현재 상태 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

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를 구성합니다.

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

• 일반 텍스트 통신을 사용하여 연결
• TLS 암호화를 사용하여 연결
• mTLS 암호화를 사용하여 연결

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

일반 텍스트 연결을 설정하려면 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 트러스트 저장소를 구성하고 클라이언트 비공개 키를 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에서 생성한 인증 토큰의 값으로 설정합니다. 사용자 인증 정보가 필요하지 않은 연결의 경우 이 변수를 설정하지 않은 상태로 둡니다.

다음 단계

• Spanner Omni에서 클라이언트 라이브러리를 사용합니다.

• Java 클라이언트 라이브러리를 사용하여 Spanner Omni에 연결합니다.

• Spanner Omni 인증 및 승인을 이해합니다.