Snowpipe Streaming Classic 아키텍처 설정과 예제

Snowpipe Streaming Classic 아키텍처 설정과 예제

Snowpipe Streaming Classic 아키텍처의 API 연결 설정과 인증·권한 부여 방법, 예제를 알려드릴게요. 이 문서를 따라 profile.json 파일을 구성하면 스트리밍 클라이언트를 Snowflake에 연결할 수 있습니다.

출처: Snowflake 문서

본문

Snowpipe Streaming 속성: Classic 아키텍처

profile.json 파일에서 API 연결 설정을 구성하세요. 이 속성들은 이 주제에서 설명합니다. Java 예제(GitHub)에서 보여 주듯, 파일 경로를 변수 PROFILE_PATH의 입력으로 지정해 profile.json에서 설정을 로드할 수 있어요.

필수 속성

authorization_type

사용자의 인증·권한 부여 방법을 구성합니다. 다음 방법 중 하나를 사용할 수 있어요:

  • JWT: JSON Web Token(JWT)을 사용한 키 페어 인증. 기본 방법입니다. authorization_type이 구성되지 않으면 기본 방법 JWT가 사용됩니다. 키 페어 인증을 위해 다음 private_key를 구성하세요:
    • private_key: 사용자를 인증할 개인 키. 헤더나 푸터를 제외한 키만 포함하세요. 키가 여러 줄로 나뉘어 있으면 줄 바꿈을 제거하세요.
    • 암호화되지 않은 키를 제공하거나, 암호화된 키를 제공하면서 Snowflake가 키를 복호화할 수 있도록 snowflake.private.key.passphrase 매개변수를 제공할 수 있어요. 이 매개변수는 snowflake.private.key 매개변수 값이 암호화된 경우에만 사용하세요.
  • OAuth: Snowflake OAuth. 이 옵션은 Java Snowflake Ingest SDK(버전 2.0.3 이상)에서만 사용할 수 있어요. profile.json 파일에서 Snowflake OAuth용 다음 매개변수를 구성하세요:
    • oauth_client_id: OAuth 통합의 클라이언트 ID.
    • oauth_client_secret: OAuth 통합의 클라이언트 시크릿.
    • oauth_refresh_token: OAuth 통합의 유효한 리프레시 토큰.

Snowflake/OKTA OAuth에서 토큰 리프레시를 지원하려면 oauth_client_id, oauth_client_secret, oauth_refresh_token 세 매개변수를 모두 구성해야 합니다. 단, 토큰 리프레시 요청에 이 값들이 필요하지 않은 커스텀 OAuth API 엔드포인트를 사용한다면 이 매개변수들의 필드를 아무 자리표시자로 채워 넣을 수 있어요.

url

Snowflake 계정에 접근하기 위한 URL. 이 URL은 계정 식별자를 포함해야 합니다. 프로토콜(https://)과 포트 번호는 선택 사항이에요. 이미 Snowflake Ingest SDK를 사용하고 profile.json 파일에 host, scheme, port 속성을 설정했다면 url은 필요하지 않습니다.

user

Snowflake 계정의 사용자 로그인 이름.

선택 속성

enable_iceberg_streaming

Snowflake 관리 Apache Iceberg™ 테이블과 함께 Snowpipe Streaming을 활성화하려면 속성을 true로 설정하세요. 자세한 내용은 Apache Iceberg™ 테이블과 함께하는 Snowpipe Streaming Classic을 참고하세요.

max_client_lag

이 속성으로 데이터 플러시 지연 시간을 구성하세요. 기본적으로 Snowpipe Streaming은 표준 Snowflake 테이블(비-Apache Iceberg)에 대해 매 1초마다 데이터를 플러시합니다. max_client_lag 구성을 사용하면 이를 덮어써 1초에서 10분 사이의 원하는 플러시 지연 시간으로 설정할 수 있어요. 자세한 내용은 Snowpipe Streaming 지연 시간 권장 사항을 참고하세요.

snowflake.private.key.passphrase

키가 암호화됐을 때 개인 키를 복호화하는 패스프레이즈. 자세한 내용은 (이 주제의) 키 페어 인증과 키 회전 사용을 참고하세요.

role

Snowflake에 연결한 후 세션에 사용할 액세스 제어 역할. role 속성은 Snowflake Ingest SDK 버전 2.0.3 이상에서는 선택 사항이고, 그 이전 Ingest SDK 버전에서는 필수입니다.

인증과 권한 부여

Snowflake OAuth 사용하기

Java Snowflake Ingest SDK(버전 2.0.3 이상) 또는 Snowflake Connector for Kafka(버전 2.1.2 이상)에서는 Snowflake OAuth를 권한 부여 방법으로 사용할 수 있어요.

이 워크플로우를 따라 Snowflake OAuth 통합을 만들고 OAuth 엔드포인트를 호출해 인증 코드를 요청하고 액세스 토큰을 리프레시하세요. 토큰 요청 응답에는 oauth_refresh_token이 포함됩니다. Snowflake OAuth 통합을 만든 뒤 SYSTEM$SHOW_OAUTH_CLIENT_SECRETS 함수를 실행해 oauth_client_id와 oauth_client_secret을 얻으세요.

Snowflake OAuth를 활성화하려면 profile.json 파일에서 authorization_type을 OAuth로 설정하고, oauth_refresh_token, oauth_client_id, oauth_client_secret 필드를 위에서 얻은 매개변수로 채우세요.

키 페어 인증과 키 회전 사용하기

API 호출은 JSON Web Token(JWT)을 사용한 키 페어 인증에 의존합니다. JWT는 RSA 암호화를 사용하는 공개/개인 키 페어로 서명됩니다. 이 인증 방법은 최소 2048비트 RSA 키 페어가 필요합니다. OpenSSL로 공개-개인 키 페어를 생성하세요. 공개 키는 속성 파일에 정의된 Snowflake 사용자에게 할당됩니다.

key pair rotation에 설명된 키 페어 인증 지침을 완료하세요. 속성 파일의 snowflake.private.key 필드에 개인 키 전체를 복사·붙여넣고 파일을 저장하세요. 지문 생성과 JWT 토큰 생성 예는 Java 예제를 참고하세요. 다음으로 (이 주제의) 시크릿 외부화 권장 사항을 평가하세요.

시크릿 외부화

Snowflake는 개인 키 같은 시크릿을 외부화하고 AWS Key Management Service(KMS), Microsoft Azure Key Vault, HashiCorp Vault 같은 키 관리 서비스나 암호화된 형태로 저장할 것을 강력히 권장합니다. 자세한 내용은 Confluent의 이 서비스 설명을 참고하세요.

예제

더 알아보기 (Learn more)