Snowflake Connector for PostgreSQL Agent 컨테이너 설정하기¶

컨테이너 오케스트레이션 시스템 선택하기¶

에이전트는 표준 Docker 컨테이너 이미지로 패키징되며 표준을 지원하는 모든 오케스트레이션 시스템에서 실행될 수 있습니다. 이는 독립 실행형 Docker 인스턴스, Kubernetes, RedHat OpenShift, 클라우드 관리형 솔루션(예: AWS Fargate) 등이 될 수 있습니다. 조직마다 선호하고 지금까지 사용해온 기존 시스템이 있는 경우가 많습니다.

다양한 오케스트레이션 시스템마다 제약 조건이 제각기 다르므로 이 문서의 에이전트 구성 섹션에 주의하십시오. 사용자 시스템이나 특정 설정에 따라 쓰기 가능한 볼륨(에이전트의 기본 구성 옵션에 필수 사항)을 탑재하지 못할 수도 있습니다.

이후의 예에서는 가장 인기 있는 오케스트레이션 시스템인 Kubernetes에 초점을 맞추겠습니다. 다른 시스템에서도 접근 방식이 비슷한 경우가 많으며, 자신의 설정에 맞게 예시의 내용을 조정해야 합니다.

필요한 시스템 리소스 확인하기¶

• 에이전트는 메모리를 많이 사용하는 애플리케이션으로, 올바르게 작동하려면 최소 6GB 이상의 RAM이 필요합니다.

• CPU의 최적 개수는 4개입니다. CPU 수가 적으면 성능이 저하될 수 있습니다. CPU 수가 많아도 성능이 향상되지 않습니다.

연결 설정하기¶

에이전트는 데이터를 읽을 모든 원본 데이터베이스에 연결해야 합니다. 직접 연결이 가능하고 PostgreSQL의 클라이언트 포트에 접근할 수 있도록 네트워크와 방화벽을 구성합니다. 일반적으로 포트 5432 입니다. 자세한 내용은 PostgreSQL의 연결 설정 설명서 섹션을 참조하십시오.

원본 데이터베이스가 격리된 네트워크에 있고 단일 에이전트에서 연결할 수 없는 경우 각각 자체 에이전트가 있는 커넥터의 네이티브 애플리케이션 인스턴스를 추가로 설치해야 합니다. 이 기능은 현재 비공개 미리 보기로 제공됩니다. 액세스를 요청하려면 Snowflake 지원팀 에 문의하십시오.

에이전트는 Snowflake 배포에 직접 연결하기도 합니다. 사용 가능해야 하는 호스트 이름에 대한 정보는 호스트 이름 허용하기 를 참조하십시오.

에이전트의 연결 중 하나가 프록시를 통과하는 경우 에이전트에 추가 구성을 전달해야 합니다. 선택적 구성 환경 변수 검토하기 섹션을 참조하십시오.

[선택 사항] 원본 데이터베이스에 대한 SSL 인증서 획득 및 준비하기¶

에이전트와 원본 데이터베이스 간에 SSL 연결을 사용하려면 PostgreSQL 인스턴스에 대한 루트 인증서를 획득해 /home/agent/.postgresql/root.crt 아래에 있는 에이전트 컨테이너에 탑재해야 합니다.

에이전트 구성 준비하기¶

에이전트는 컨테이너에 탑재된 JSON 파일이나 환경 변수, 또는 두 가지를 혼합하여 구성할 수 있습니다. Snowflake에 연결하는 데 필요한 액세스 키는 호스트의 파일 시스템에서 탑재하거나 컨테이너 시크릿 또는 환경 변수로 제공할 수 있습니다.

다음 섹션에서는 가장 간단한 것부터 가장 포괄적인 것까지 다양한 구성 옵션을 설명합니다. 해당 인프라의 특성에 따라 접근 방식을 선택하십시오.

 {
   "<data_source_name_1>": {
       "url": "jdbc:postgresql://<host>:<port>/<databaseName>[?<key1>=<value1>[&<key2>=<value2>]]",
       "username": "<postgresql_db_username>",
       "password": "<postgresql_db_password>",
       "publication": "<postgresql_db_publication>",
       "ssl": false
   },
   "<data_source_name_2>": {
       "url": "jdbc:postgresql://<host>:<port>/<databaseName>[?<key1>=<value1>[&<key2>=<value2>]]",
       "username": "<postgresql_db_username>",
       "password": "<postgresql_db_password>",
       "publication": "<postgresql_db_publication>",
       "ssl": false
   }
}

docker run -d \
   --restart unless-stopped \
   --name database-connector-agent \
   --volume </path/to/ssh/keys/directory>:/home/agent/.ssh \
   --volume </path/to/snowflake.json>:/home/agent/snowflake.json \
   --volume </path/to/datasources.json>:/home/agent/datasources.json \
   --volume </path/to/root.crt>:/home/agent/.postgresql/root.crt \
   -m 6g \
   snowflakedb/database-connector-agent:latest

docker run \
  -e SNOWFLAKE_USERNAME="POSTGRESQL_AGENT_USER" \
  -e SNOWFLAKE_APPLICATION_NAME="SNOWFLAKE_CONNECTOR_FOR_POSTGRESQL" \
  -e SNOWFLAKE_ALLOWLIST_0_HOST="example_account.us-west-2.aws.snowflakecomputing.com" \
  -e SNOWFLAKE_ALLOWLIST_0_PORT=443 \
  -e SNOWFLAKE_ALLOWLIST_0_TYPE="SNOWFLAKE_DEPLOYMENT" \
  ...

{
  "userName": "POSTGRESQL_AGENT_USER",
  "applicationName": "SNOWFLAKE_CONNECTOR_FOR_POSTGRESQL",
  "allowlist": [
    {
      "host": "example_account.us-west-2.aws.snowflakecomputing.com",
      "port": 443,
      "type": "SNOWFLAKE_DEPLOYMENT"
    }
  ]
}

docker run \
    -e SNOWFLAKE_USERNAME="POSTGRESQL_AGENT_USER" \
    -e SNOWFLAKE_APPLICATION_NAME="SNOWFLAKE_CONNECTOR_FOR_POSTGRESQL" \
    -e SNOWFLAKE_ENFORCEDURL="example_account.us-west-2.aws.snowflakecomputing.com:443" \
    ...

docker run \
  -e SNOWFLAKE_DATASOURCES_POSTGRESQLDS1_URL="jdbc:postgresql://example.internal:5432/", \
  -e SNOWFLAKE_DATASOURCES_POSTGRESQLDS1_USERNAME="example_user" \
  -e SNOWFLAKE_DATASOURCES_POSTGRESQLDS1_PASSWORD="example_password" \
  -e SNOWFLAKE_DATASOURCES_POSTGRESQLDS1_PUBLICATION="example_publication" \
  -e SNOWFLAKE_DATASOURCES_POSTGRESQLDS1_SSL="false" \
  ...

{
    "POSTGRESQLDS1": {
        "url": "jdbc:postgresql://example.internal:5432/",
        "username": "example_user",
        "password": "example_password",
        "publication": "example_publication",
        "ssl": false
    }
}

선택적 구성 환경 변수 검토하기¶

에이전트는 컨테이너에 추가 환경 변수를 설정하여 사용할 수 있는 다음과 같은 선택적 설정을 지원합니다.

SNOWFLAKE_PRIVATEKEYPATH

에이전트 사용자의 개인 키가 있는 파일의 절대 경로를 지정합니다. 이는 보통 오케스트레이션 시스템의 시크릿을 통해 컨테이너에 자신의 개인 키를 탑재할 때 사용됩니다.

SNOWFLAKE_PRIVATEKEYPASSWORD

에이전트 사용자의 개인 키에 대한 비밀번호를 지정합니다. 에이전트가 키를 생성하도록 하는 경우 이 비밀번호는 개인 키에 설정됩니다. 기존 키를 재사용하는 경우 이 비밀번호는 기존 개인 키에 액세스하는 데 사용됩니다.

SNOWFLAKE_PRIVATEKEY

에이전트 사용자의 개인 키 내용을 지정합니다. 개인 키를 컨테이너에 파일로 탑재할 수 없는 경우 설정할 수 있습니다.

SNOWFLAKE_ENFORCEDURL

Snowflake에 연결할 URL을 지정하여 에이전트의 자체 검색 메커니즘을 재정의합니다. 이는 주로 PrivateLink 배포에 연결하는 데 사용됩니다.

JAVA_OPTS

에이전트 프로세스에 전달할 추가적인 Java 설정이나 속성을 지정합니다.

가장 일반적으로 사용되는 것은 다음과 같습니다.

• 최대 Java 힙 크기를 설정하는 -Xmx 옵션입니다. Snowflake에서는 이 값을 컨테이너에서 사용 가능한 메모리 양에서 1GB를 뺀 값으로 설정할 것을 권장합니다.

  예를 들어, 컨테이너에 6GB의 RAM을 사용할 수 있는 경우 다음을 설정합니다.

  JAVA_OPTS=-Xmx5g
  

  Copy

• 에이전트에서 Snowflake로의 연결에 프록시가 필요한 경우 다음을 설정합니다.

  JAVA_OPTS=-Dhttp.useProxy=true -Dhttp.proxyHost=<proxy-host> -Dhttp.proxyPort=<proxy-port>
  

  Copy

• 예를 들어 원본 데이터베이스와 같이 일부 호스트나 IP 주소에 대한 프록시를 우회하려면 추가적인 http.nonProxyHosts 속성을 설정합니다. 여러 개의 호스트 이름은 파이프 기호(|)를 사용하여 구분합니다. 별표(*)를 와일드카드 문자로 사용합니다.

  JAVA_OPTS=-Dhttp.useProxy=true -Dhttp.proxyHost=<proxy-host> -Dhttp.proxyPort=<proxy-port>
    -Dhttp.nonProxyHosts='*.my_company.com|localhost|myorganization-myaccount.snowflakecomputing.com|192.168.91.*'
  

  Copy

• 프록시에 대한 자격 증명을 전달하려면 http.proxyUser 및 http.proxyPassword 시스템 속성을 설정합니다.

  JAVA_OPTS=-Dhttp.useProxy=true -Dhttp.proxyHost=<proxy-host> -Dhttp.proxyPort=<proxy-port>
    -Dhttp.proxyUser=<proxy-user> -Dhttp.proxyPassword=<proxy-pass>
  

  Copy

PrivateLink 연결 설정하기¶

PrivateLink 배포에 연결하는 경우 SNOWFLAKE_ENFORCEDURL 환경 변수를 설정하여 에이전트가 연결할 URL을 명시적으로 제공해야 합니다.

다음 중 하나를 수행하면 계정의 PrivateLink URL을 확인할 수 있습니다.

• 구성 과정에서 얻은 snowflake.json 파일을 엽니다. allowlistPrivatelink 라는 배열을 찾은 다음, SNOWFLAKE_DEPLOYMENT 의 type 이 있는 항목을 찾습니다.

• SYSTEM$GET_PRIVATELINK_CONFIG 함수를 사용합니다.

Snowflake 액세스 키 이해하기¶

에이전트는 Snowsight에서 커넥터 설정 마법사를 통해 생성된 서비스 계정과 액세스 키 세트를 사용하여 Snowflake에 인증합니다. 설치 마법사는 임시 액세스 키를 생성하고 temporaryPrivateKey 라는 필드에서 개인 키를 snowflake.json 파일에 추가합니다.

에이전트는 초기 시작 중에 다음 방법으로 임시 키를 교체합니다.

1. 새로운 액세스 키 세트를 생성하여 컨테이너 내부의 /home/agent/.ssh 아래에 database-connector-agent-app-private-key.p8 과 database-connector-agent-app-public-key.pub 로 저장합니다. 이 디렉터리는 외부에서 컨테이너에 데이터를 쓸 수 있는 볼륨으로 탑재해야 하므로, 컨테이너가 종료되어도 키가 유지됩니다.

2. 새로운 키를 사용하도록 서비스 계정을 변경합니다.

3. snowflake.json 파일에서 temporaryPrivateKey 필드를 제거합니다.

최초 키 교체 후, 에이전트는 액세스 키를 교체하지 않습니다.

에이전트가 생성한 키를 사용할 수 있습니다. 또는 자체 세트를 만들고 서비스 계정을 변경한 후 에이전트에 개인 키를 제공할 수도 있습니다.

에이전트의 개인 키 검색 순서는 다음과 같습니다.

1. SNOWFLAKE_PRIVATEKEY 환경 변수를 사용하여 전달된 모든 키. 커넥터가 이 값을 찾으면 snowflake.json 의 임시 키를 무시합니다.

2. /home/agent/.ssh/database-connector-agent-app-private-key.p8 에 탑재된 볼륨에서 찾은 키. 커넥터가 이 파일을 찾으면 snowflake.json 의 임시 키를 무시합니다.

3. snowflake.json 파일의 temporaryPrivateKey 필드 값.

상태 점검 엔드포인트에 액세스하기¶

에이전트는 상태 정보가 포함된 HTTP 엔드포인트를 노출합니다. 오케스트레이션 시스템에서 에이전트를 실행할 때 이 엔드포인트를 사용하면 에이전트가 완전히 시작되었는지, 정상적인 상태인지 확인할 수 있습니다. 엔드포인트는 포트 8080 및 경로 /actuator/health 에서 제공됩니다.

Kubernetes에서 엔드포인트를 활성 프로브로 사용하려면 Pod 구성에 다음을 추가합니다.

apiVersion: v1
kind: Pod
spec:
  containers:
  - ...
    livenessProbe:
      httpGet:
        path: /actuator/health
        port: 8080
      initialDelaySeconds: 5
      periodSeconds: 10