Snowpipe Streaming 고성능 아키텍처 설정

Snowpipe Streaming 고성능 아키텍처 설정

이 가이드는 Java, Python, Node.js SDK에서 사용할 수 있는 고성능 Snowpipe Streaming 클라이언트의 구성 설정을 설명합니다. 두 가지 종류의 구성이 있습니다.

• 프로세스 전역 환경 변수(Process-wide environment variables): 실행 중인 전체 애플리케이션의 로깅과 지표를 제어하며 클라이언트를 초기화하기 전에 설정해야 합니다.
• 클라이언트 측 속성(Client-side properties): 보안 연결과 수집 대상을 정의하는 속성 — 예: url, user, private_key — 으로, 보통 인라인 맵이나 profile.json 파일을 통해 특정 클라이언트 객체에 대해 구성합니다.

단일 애플리케이션이 여러 클라이언트 객체를 실행할 수 있습니다. 각 객체는 자체 클라이언트 측 속성을 가지지만, 로깅과 지표를 위한 프로세스 전역 환경 변수 설정은 모두 공유합니다.

고성능 아키텍처는 클라이언트가 특정 PIPE 객체에 명시적으로 바인딩되도록 요구합니다. PIPE가 스키마, 변환, 대상 테이블로의 수집을 관리합니다.

출처: Snowflake 문서

본문

환경 변수

이 구성 설정은 로깅과 지표 수집 같은 프로세스 전역 동작을 제어하며, 클라이언트 객체가 초기화되기 전에 환경 변수로 구성해야 합니다. 다음 표는 같은 프로세스 안의 모든 Snowpipe Streaming 클라이언트 객체에 적용되는 환경 변수를 보여줍니다.

필수 속성

고성능 SDK는 보안 연결과 특정 수집 대상(PIPE)을 모두 설정하기 위해 몇 가지 속성을 요구합니다. 다음 표는 필수 연결 및 사용자 인증 속성을 보여줍니다.

authorization_type가 기본값인 JWT로 설정된 경우, 다음 표와 같이 키 내용 또는 키 파일 경로 중 하나를 제공해야 합니다.

authorization_type가 OAUTH로 설정된 경우, 다음 표와 같이 OAuth 클라이언트 자격 증명과 refresh token을 제공해야 합니다.

authorization_type가 PAT로 설정된 경우, 다음 표와 같이 personal access token을 제공해야 합니다.

선택 속성

다음 표는 고성능 SDK의 선택 속성을 보여줍니다.

시크릿 외부화(Externalizing secrets)

Snowflake는 private_key 및 OAuth 자격 증명 같은 시크릿을 외부화해 예를 들어 AWS KMS 같은 키 관리 서비스에 저장할 것을 강력히 권장합니다.

FIPS 140-3 준수

SDK 버전 1.5.0부터 Snowpipe Streaming SDK는 TLS 연결과 데이터 암호화에 FIPS 140-3 검증 암호화 제공자를 사용합니다. 이 변경은 Java, Python, Node.js SDK에 적용되며 자동으로 활성화됩니다. 애플리케이션을 업데이트하거나 구성을 변경할 필요가 없습니다.

이것이 애플리케이션에 의미하는 바는 다음과 같습니다.

• Snowflake 및 클라우드 스토리지 제공자에 대한 TLS 연결이 FIPS 140-3 검증 알고리즘을 사용합니다.
• SDK가 HTTPS 전용 연결을 강제합니다. 비-TLS 엔드포인트는 거부됩니다.
• SDK가 시작 시 암호화 셀프 테스트를 실행합니다. 셀프 테스트가 실패하면 명확한 오류와 함께 클라이언트 생성이 실패하고 프로세스는 계속되지 않습니다.

고객 영향:

• 이미 HTTPS로 Snowflake에 연결하는 기존 애플리케이션은 변경 없이 계속 작동합니다.
• 프록시를 통해 SDK 트래픽을 라우팅하는 애플리케이션은 TLS 종료 프록시(TLS-terminating proxy)를 사용해야 합니다. 일반 HTTP 프록시와 http:// URL은 거부됩니다.
• SnowGov 리전 및 공식 FIPS 140-2 또는 140-3 요구 사항이 있는 다른 배포에 대해서는 지원되는 클라우드 리전 을 참고하세요.

구성 예시

다음 예시는 클라이언트 측 및 환경 변수 구성을 보여줍니다.

profile.json 파일을 통한 클라이언트 측 구성

다음 예시는 클라이언트 측 속성을 정의하는 방법을 보여줍니다.

// profile.json
{
  "authorization_type": "JWT",
  "url": "https://.snowflakecomputing.com",
  "user": "MY_SNOWFLAKE_USER",
  "account": "XY12345",
  "private_key_file": "/path/to/rsa_key.p8",
  "role": "MY_INGEST_ROLE"
}

인라인으로 제공되는 클라이언트 측 구성

다음 예시는 코드에서 직접 클라이언트 측 속성을 정의하는 방법을 보여줍니다.

Map config = new HashMap<>();
config.put("authorization_type", "JWT");
config.put("url", "https://.snowflakecomputing.com");
config.put("user", "MY_SNOWFLAKE_USER");
config.put("account", "XY12345");
config.put("private_key_file", "/path/to/rsa_key.p8");
config.put("role", "MY_INGEST_ROLE");
// ... code to initialize client with 'config'

config = {
    "authorization_type": "JWT",
    "url": "https://.snowflakecomputing.com",
    "user": "MY_SNOWFLAKE_USER",
    "account": "XY12345",
    "private_key": "[REDACTED PRIVATE KEY]",
}
# ... code to initialize client with 'config'

const { createClient } = require("snowpipe-streaming");

const client = await createClient({
  clientName: "my-client",
  dbName: "MY_DATABASE",
  schemaName: "MY_SCHEMA",
  pipeName: "MY_PIPE",
  properties: {
    authorization_type: "JWT",
    url: "https://.snowflakecomputing.com",
    user: "MY_SNOWFLAKE_USER",
    account: "XY12345",
    private_key: "[REDACTED PRIVATE KEY]",
  },
});

환경 변수 구성

다음 예시는 애플리케이션을 실행하기 전에 셸에서 프로세스 전역 환경 변수를 정의하는 방법을 보여줍니다.

Linux 또는 macOS (Bash 또는 Zsh)

# Set the log level for the entire application process to 'warn'
export SS_LOG_LEVEL=warn

# Change the IP for metrics to a specific loopback address
export SS_METRICS_IP=127.0.0.5

# Now run your application

Windows (command prompt)

# Set the log level for the entire application process to 'warn'
set SS_LOG_LEVEL=warn

# Change the metrics port
set SS_METRICS_PORT=55000

# Now run your application

더 알아보기 (Learn more)

• Snowpipe Streaming 고성능 아키텍처: 모범 사례
• Snowpipe Streaming 고성능 아키텍처: 제한 사항
• Named Channel과 클래식 SDK 비교