Cassandra Java 클라이언트를 사용하여 Spanner Omni에 연결

Spanner용 Cassandra Java 클라이언트는 Apache Cassandra 데이터베이스용으로 작성된 애플리케이션을 Spanner에 연결합니다. 클라이언트는 Spanner와 동일한 방식으로 Spanner Omni와 상호작용합니다.

Spanner는 Cassandra v4 유선 프로토콜을 기본적으로 지원하므로 Spanner Cassandra Java 클라이언트는 Cassandra 유선 프로토콜을 Spanner gRPC API로 변환합니다. 이를 통해 최소한의 코드 변경으로 Cassandra 애플리케이션을 Spanner로 마이그레이션할 수 있습니다.

이 문서에서는 다음 방법 중 하나를 사용하여 클라이언트를 Spanner Omni와 통합하는 방법을 보여줍니다.

  • 인프로세스 종속 항목: 이미 cassandra-java-driver를 사용하는 Java 애플리케이션에 이 방법을 사용합니다. 이 접근 방식은 최소한의 코드 수정으로 애플리케이션 프로세스 내에 클라이언트를 삽입합니다.

  • 사이드카 프록시: Java가 아닌 애플리케이션에 사용하거나 cqlsh와 같은 외부 Cassandra 도구를 사용하는 경우 이 방법을 사용합니다. 이 접근 방식은 클라이언트를 독립형 프로세스로 실행합니다.

자세한 내용은 Spanner 문서의 Cassandra 인터페이스를 참고하세요.

Spanner Cassandra Java 클라이언트를 사용해야 하는 경우

이 클라이언트는 다음과 같은 시나리오에서 유용합니다.

  • 최소한의 리팩터링으로 Spanner 사용 Java 애플리케이션의 백엔드로 Spanner를 사용하고 싶지만 데이터 액세스에는 익숙한 cassandra-java-driver API를 계속 사용하고 싶습니다.

  • Java가 아닌 Cassandra 도구를 사용합니다. cqlsh와 같은 표준 Cassandra 도구나 Cassandra 드라이버를 사용하는 다른 언어로 작성된 애플리케이션을 사용하여 Spanner에 연결하려고 합니다.

클라이언트를 인프로세스 종속 항목으로 사용

Spanner Cassandra Java 클라이언트를 처리 중 종속 항목으로 통합하는 것이 Java 애플리케이션이 Spanner Omni에 연결하는 권장 방법입니다. 사이드카 프록시 메서드와 비교할 때 인프로세스 구성은 추가 네트워크 홉과 관련 데이터 직렬화 및 역직렬화를 방지하여 더 나은 성능을 제공합니다. 또한 별도의 독립형 프로세스를 관리할 필요가 없어 배포 아키텍처가 간소화됩니다.

클라이언트를 인프로세스 종속 항목으로 사용하려면 다음을 실행하세요.

  1. CqlSession 생성 코드를 수정하고 Spanner Omni 통신 관련 옵션을 추가합니다.

  2. Spanner Cassandra Java 클라이언트를 프로젝트의 종속 항목으로 추가합니다.

    일반 텍스트 통신

    다음 예시에서는 Spanner Omni에 일반 텍스트 연결을 설정하는 방법을 보여줍니다.

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(true)
        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

session.close();

    TLS 연결

    TLS 연결을 사용하려면 Java SDK TLS 안내에 설명된 대로 CA 인증서가 애플리케이션에서 사용하는 트러스트 저장소에 추가되어 있는지 확인하세요.

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(false)
        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

session.close();

    mTLS 연결

    mTLS 연결을 사용하려면 Java SDK mTLS 안내에 설명된 대로 CA 인증서가 애플리케이션에서 사용하는 트러스트 저장소에 추가되어 있고 클라이언트 키가 PKCS#8 형식인지 확인하세요.

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(false)
  .useClientCert("PATH_TO_CLIENT_CERT",
          "PATH_TO_CLIENT_KEY_PKCS8")

        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

session.close();

사이드카 프록시 또는 독립형 프로세스

Spanner Cassandra Java 클라이언트를 사이드카 프록시로 배포하는 것은 Java가 아닌 애플리케이션과 도구(예: cqlsh)가 표준 Cassandra 드라이버를 사용하여 Spanner Omni에 연결하는 효과적인 옵션입니다. 이 메서드는 Cassandra 유선 프로토콜 트래픽을 가로채고 이를 gRPC로 변환하여 Spanner Omni와 통신하는 독립형 TCP 프록시로 클라이언트를 실행합니다.

YAML 구성 파일을 사용하거나 시스템 속성을 지정하여 사이드카 프록시를 실행할 수 있습니다.

YAML 구성 파일 사용

프로덕션 설정의 경우 YAML 파일을 사용하여 어댑터를 구성하는 것이 좋습니다. 이 메서드는 여러 리스너와 전역 설정을 지원합니다.

java -DconfigFilePath=PATH_TO_CONFIG_YAML -jar PATH_TO_ADAPTER_JAR

config.yaml 예시:

globalClientConfigs:
  enableBuiltInMetrics: false
  healthCheckEndpoint: "127.0.0.1:8080"
  experimentalHostEndpoint: "ENDPOINT"
  clientCertPath: "PATH_TO_CLIENT_CERT"
  clientKeyPath: "PATH_TO_CLIENT_KEY_PKCS8"
  usePlainText: "false"

listeners:
  - name: "listener_1"
    host: "127.0.0.1"
    port: 9042
    spanner:
      databaseUri: "DATABASE_ID"
      numGrpcChannels: 4
      maxCommitDelayMillis: 5
  - name: "listener_2"
    host: "127.0.0.2"
    port: 9043
    spanner:
      databaseUri: "DATABASE_ID_2"
      numGrpcChannels: 8

시스템 속성 사용

단일 리스너 또는 간단한 배포의 경우 사이드카 프록시를 독립형 프로세스로 실행하고 Java 시스템 속성을 사용하여 설정을 구성할 수 있습니다.

단일 리스너의 경우 시스템 속성을 사용할 수 있습니다. 다음 예시는 지원되는 각 보안 모드에 대해 사이드카 프록시를 독립형 프로세스로 실행하는 방법을 보여줍니다.

일반 텍스트 통신

일반 텍스트 통신의 경우 다음을 실행합니다.

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DexperimentalHostEndpoint=ENDPOINT \
-DusePlainText=true \
-jar PATH_TO_ADAPTER_JAR

TLS 연결

TLS 연결의 경우 다음을 실행합니다.

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DexperimentalHostEndpoint=ENDPOINT \
-jar PATH_TO_ADAPTER_JAR

mTLS 연결

mTLS 연결의 경우 다음을 실행합니다.

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DexperimentalHostEndpoint=ENDPOINT \
-DclientCertPath=PATH_TO_CLIENT_CERT \
-DclientKeyPath=PATH_TO_CLIENT_KEY_PKCS8 \
-jar PATH_TO_ADAPTER_JAR