PGAdapter 시작

이 페이지에서는 Spanner에서 PGAdapter를 시작하는 방법을 설명합니다. PGAdapter에 대한 자세한 내용은 PGAdapter 정보를 참조하세요. PGAdapter 바이너리를 가져오려면 PGAdapter 가져오기를 참조하세요.

다음과 같은 방법으로 PGAdapter를 시작할 수 있습니다.

• 독립형 프로세스로
• Docker 컨테이너 내부에서
• Cloud Run에서
• PGAdapter를 사이드카 프록시로 사용(예: Kubernetes 클러스터에서)
• Java 애플리케이션으로 처리 중

시작하기 전에

PGAdapter를 시작하기 전에 PGAdapter를 실행할 머신에서 사용자 계정이나 서비스 계정으로 인증했는지 확인합니다. 서비스 계정을 사용하는 경우 JSON 키 파일(사용자 인증 정보 파일)의 위치를 알아야 합니다. 그런 다음 PGAdapter -c 옵션을 사용하거나 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 설정하여 사용자 인증 정보 경로를 지정할 수 있습니다.

자세한 내용은 다음을 참고하세요.

• 인증 개요
• gcloud CLI 승인

PGAdapter 실행 메서드 선택

PGAdapter를 Docker 컨테이너 내 또는 Cloud Run에서 독립형 프로세스로 또는 Java 애플리케이션에서 진행 중인 프로세스로 시작할 수 있습니다. PGAdapter를 시작할 때 연결할 프로젝트, Spanner 인스턴스, 데이터베이스를 지정합니다. JSON 형식의 사용자 인증 정보 파일(키 파일)의 경로도 지정할 수 있습니다.

독립형

다음 명령어를 사용하여 PGAdapter를 다운로드합니다.

wget https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz \
  && tar -xzvf pgadapter.tar.gz

다음 명령어를 사용하여 PGAdapter를 시작합니다.

java -jar pgadapter.jar -p PROJECT_NAME -i INSTANCE_NAME -d DATABASE_NAME \
  -c CREDENTIALS_FILE_PATH \
  ADDITIONAL_OPTIONS

다음 옵션은 필수사항입니다.

-p project_name

Spanner 데이터베이스가 실행 중인 프로젝트의 이름입니다.

-i instance_name

Spanner 인스턴스 이름입니다.

-d database_name

연결할 데이터베이스의 이름입니다.

다음 옵션은 선택사항입니다.

-r databaseRole=database_role

세션에서 사용할 데이터베이스 역할입니다. 자세한 내용은 PGAdapter에 인증을 참조하세요.

-c credentials_file_path

JSON 형식의 서비스 계정 사용자 인증 정보가 포함된 키 파일의 전체 경로입니다. 이 옵션을 설정하지 않으면 GOOGLE_APPLICATION_CREDENTIALS 환경 변수로 지정된 경로에서 사용자 인증 정보를 읽습니다.

서비스 계정을 만들고 JSON 형식의 키 파일을 다운로드하는 방법은 서비스 계정 만들기를 참조하세요.

서비스 계정에 데이터베이스에 액세스할 수 있는 충분한 사용자 인증 정보를 부여했는지 확인합니다.

다음 명령어를 사용하여 Google Cloud CLI로 처음 인증하는 경우 이 옵션을 생략할 수 있습니다.

gcloud auth application-default login

자세한 내용은 인증 및 승인 설정을 참조하세요.

-s port

PGAdapter에서 리슨하는 포트입니다. 기본값은 5432(기본 PostgreSQL 포트)입니다.

-v version_number

연결 중에 클라이언트에 노출할 PostgreSQL의 버전 번호입니다. 기본값은 14.1입니다.

일부 PostgreSQL 애플리케이션과 드라이버는 이 버전 번호에 따라 추가 기능을 사용 설정합니다. Spanner에서 이러한 기능을 지원하지 않을 수 있습니다. 지원되는 전체 클라이언트 목록은 드라이버 및 클라이언트를 참조하세요.

-x

localhost 이외의 호스트에서 연결을 사용 설정합니다. 독립형 모드에서 PGAdapter를 시작할 때는 사용하지 마세요. Docker 컨테이너 내에서 시작할 경우에만 사용합니다.

기본적으로 보안 조치로 PGAdapter는 localhost의 연결만 허용합니다.

다음은 기본 애플리케이션 사용자 인증 정보를 사용하여 포트 5432에서 독립형 모드로 PGAdapter를 시작하는 간단한 예시입니다.

java -jar pgadapter.jar \
  -p my-project \
  -i my-instance \
  -d my-database \
  -s 5432
            

Docker

다음 명령어를 사용하여 PGAdapter를 시작합니다.

docker run -d -p HOST-PORT:DOCKER-PORT \
    -v CREDENTIALS_FILE_PATH:/acct_credentials.json \
    gcr.io/cloud-spanner-pg-adapter/pgadapter:latest \
    -p PROJECT_NAME -i INSTANCE_NAME -d DATABASE_NAME  \
    -c /acct_credentials.json -x OTHER_PGAdapter_OPTIONS

프로젝트, 인스턴스, 데이터베이스, 사용자 인증 정보를 지정하는 PGAdapter 옵션 외에 다음 옵션도 필요합니다.

-p 127.0.0.1:HOST-PORT:DOCKER-PORT

이 Docker 옵션은 Docker 컨테이너 내 DOCKER-PORT 포트를 컨테이너 외부의 HOST-PORT 포트에 매핑합니다. DOCKER-PORT는 PGAdapter가 컨테이너 내에서 구성된 방식과 일치해야 합니다. 기본값은 5432입니다. HOST-PORT는 연결 요청을 위해 Docker가 컨테이너 외부에서 리슨해야 하는 포트입니다. 항상 localhost에서 사용할 수 있는 포트여야 합니다.

자세한 내용은 Docker 문서의 포트(-p, --expose) 게시 또는 노출을 참조하세요.

-v CREDENTIALS_FILE_PATH:in_container_mount_point

이 Docker 옵션 결합은 공유 볼륨 마운트를 바인딩합니다. 컨테이너 외부의 호스트 경로를 컨테이너 내부의 볼륨(마운트 지점)에 매핑합니다. 호스트 경로와 컨테이너 경로는 콜론(:)으로 구분됩니다.

이 옵션을 사용하면 PGAdapter에서 컨테이너 외부에 있는 JSON 사용자 인증 정보 파일에 액세스할 수 있습니다. 앞의 예시에서 -c 옵션은 컨테이너 내 마운트 지점을 참조합니다. 이 예시에서는 컨테이너 내 마운트 지점 /acct_credentials.json의 이름을 지정합니다. 원하는 이름을 지정할 수 있습니다.

자세한 내용은 Docker 문서의 볼륨(공유 파일 시스템)을 참조하세요.

-x

localhost 이외의 호스트에서 연결을 사용 설정합니다. 이는 호스트 포트에 매핑된 컨테이너 내부 포트가 PGAdapter에 localhost로 표시되지 않기 때문에 필요한 절차입니다.

다음 옵션은 선택사항입니다.

-r databaseRole=database_role

세션에서 사용할 데이터베이스 역할입니다. 자세한 내용은 PGAdapter에 인증을 참조하세요.

다음 예시에서 Docker 포트와 호스트 포트 모두 PostgreSQL 데이터베이스 서비스 기본 포트 5432로 설정됩니다.

docker run -d -p 127.0.0.1:5432:5432 \
    -v /tmp/credentials.json:/acct_credentials.json \
    gcr.io/cloud-spanner-pg-adapter/pgadapter:latest \
    -p my_project -i my_instance -d my_database \
    -c /acct_credentials.json -x

Cloud Run

PGAdapter를 Cloud Run에서 독립형 서비스로 배포할 수 없지만 사이드카 프록시로 배포할 수 있습니다.

사이드카 패턴으로 PGAdapter를 실행하는 것은 다음과 같은 이유로 별도의 서비스로 실행되는 것이 좋습니다.

• 단일 장애점을 방지합니다. 데이터베이스에 대한 각 애플리케이션의 액세스는 다른 애플리케이션에 대해 독립적이므로 복원력이 더 우수합니다.
• PGAdapter 인스턴스 수는 애플리케이션 인스턴스 수에 따라 선형적으로 자동 확장됩니다.

PGAdapter GitHub 저장소에는 다양한 프로그래밍 언어를 위한 Cloud Run 및 PGAdapter를 사이드카 프록시로 사용하는 여러 작동 샘플 애플리케이션이 포함되어 있습니다.

다음 구성 파일에서는 PGAdapter를 Cloud Run에 사이드카 프록시로 추가하는 방법을 보여줍니다.

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
    # This example uses an in-memory volume for Unix domain sockets.
    # This is a Cloud Run beta feature.
    run.googleapis.com/launch-stage: BETA
  name: pgadapter-sidecar-example
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen1
        # This registers 'pgadapter' as a dependency of 'app' and ensures that pgadapter starts
        # before the app container.
        run.googleapis.com/container-dependencies: '{"app":["pgadapter"]}'
    spec:
      # Create an in-memory volume that can be used for Unix domain sockets.
      volumes:
        - name: sockets-dir
          emptyDir:
            # This directory contains the virtual socket files that are used to
            # communicate between your application and PGAdapter.
            sizeLimit: 50Mi
            medium: Memory
      containers:
        # This is the main application container.
        - name: app
          # Example: europe-north1-docker.pkg.dev/my-test-project/cloud-run-source-deploy/pgadapter-sidecar-example
          image: MY-REGION.pkg.dev/MY-PROJECT/cloud-run-source-deploy/pgadapter-sidecar-example
          # The PGADAPTER_HOST variable is set to point to /sockets, which is the shared in-memory
          # volume that is used for Unix domain sockets.
          env:
            - name: SPANNER_PROJECT
              value: my-project
            - name: SPANNER_INSTANCE
              value: my-instance
            - name: SPANNER_DATABASE
              value: my-database
            - name: PGADAPTER_HOST
              value: /sockets
            - name: PGADAPTER_PORT
              value: "5432"
          ports:
            - containerPort: 8080
          volumeMounts:
            - mountPath: /sockets
              name: sockets-dir
        # This is the PGAdapter sidecar container.
        - name: pgadapter
          image: gcr.io/cloud-spanner-pg-adapter/pgadapter
          volumeMounts:
            - mountPath: /sockets
              name: sockets-dir
          args:
            - -dir /sockets
            - -x
          # Add a startup probe that checks that PGAdapter is listening on port 5432.
          startupProbe:
            initialDelaySeconds: 10
            timeoutSeconds: 10
            periodSeconds: 10
            failureThreshold: 3
            tcpSocket:
              port: 5432
          

사이드카 프록시

예를 들어 PGAdapter를 Kubernetes 클러스터에서 사이드카 프록시로 사용할 수 있습니다. Kubernetes 사이드카 컨테이너는 포드의 기본 컨테이너와 동시에 실행됩니다.

사이드카 패턴으로 PGAdapter를 실행하는 것은 별도의 서비스로 실행되는 것이 좋은데 그 이유는 다음과 같습니다.

• 단일 장애점을 방지합니다. 데이터베이스에 대한 각 애플리케이션의 액세스는 다른 애플리케이션에 대해 독립적이므로 복원력이 더 우수합니다.
• PGAdapter는 사용량과 선형적으로 관련하여 리소스를 소비하므로 이 패턴을 사용하면 확장되는 애플리케이션에 맞게 리소스 범위를 보다 정확하게 지정하고 리소스를 요청할 수 있습니다.

다음 구성 파일은 PGAdapter를 Kubernetes 클러스터에 사이드카 프록시로 추가하는 방법을 보여줍니다.

containers:
- name: pgadapter
  image: gcr.io/cloud-spanner-pg-adapter/pgadapter
  ports:
    - containerPort: 5432
  args:
    - "-p my-project"
    - "-i my-instance"
    - "-d my-database"
    - "-x"
  resources:
    requests:
      # PGAdapter's memory use scales linearly with the number of active
      # connections. Fewer open connections will use less memory. Adjust
      # this value based on your application's requirements.
      memory: "512Mi"
      # PGAdapter's CPU use scales linearly with the amount of IO between
      # the database and the application. Adjust this value based on your
      # application's requirements.
      cpu: "1"

PGAdapter GitHub 저장소에는 단계별 안내와 샘플 애플리케이션이 포함되어 있습니다. 이 샘플에는 PGAdapter에서 GKE용 워크로드 아이덴티티 제휴를 사용하기 위한 안내가 포함되어 있습니다.

프로세스 내 자바

자바 코드로 PGAdapter 인스턴스를 만들고 시작합니다. 이는 Java 애플리케이션의 권장 설정입니다.

서비스 계정을 인증에 사용하는 경우 GOOGLE_APPLICATION_CREDENTIALS 환경 변수가 사용자 인증 정보 파일의 경로로 설정되었는지 확인합니다.

1. 프로젝트에 종속 항목으로 google-cloud-spanner-pgadapter를 추가합니다. 자세한 내용은 PGAdapter 가져오기를 참조하세요.

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner-pgadapter</artifactId>
  <version>0.40.0</version>
</dependency>

com.google.cloud.spanner.pgadapter.ProxyServer 클래스를 사용하여 서버를 빌드합니다.

/**
  * Starts PGAdapter in-process and returns a reference to the server. Use this reference to
  * gracefully shut down the server when your application shuts down.
  *
  * @param project the Google Cloud project that PGAdapter should connect to
  * @param instance the Spanner instance that PGAdapter should connect to
  * @param credentialsFile the full path of a credentials file that PGAdapter should use, or 
  *     null if PGAdapter should use the application default credentials
  */
static Server startPGAdapter(String project, String instance, String credentialsFile) {
  OptionsMetadata.Builder builder =
      OptionsMetadata.newBuilder()
          .setProject(project)
          .setInstance(instance)
          // Start PGAdapter on any available port.
          .setPort(0);
  if (credentialsFile != null) {
    builder.setCredentialsFile(credentialsFile);
  }
  ProxyServer server = new ProxyServer(builder.build());
  server.startServer();
  server.awaitRunning();

  return new PGAdapter(server);
}
              

PGAdapter GitHub 저장소에는 전체 샘플 애플리케이션이 포함되어 있습니다.

다음 단계

• psql을 PostgreSQL 데이터베이스에 연결
• JDBC을 PostgreSQL 데이터베이스에 연결
• pgx을 PostgreSQL 데이터베이스에 연결
• psycopg2을 PostgreSQL 데이터베이스에 연결
• psycopg3을 PostgreSQL 데이터베이스에 연결
• node-postgres을 PostgreSQL 데이터베이스에 연결