AWS 확장

AWS 확장

aws 확장은 AWS SDK를 사용해 httpfs 확장의 S3 기능 위에 인증 같은 기능을 추가해요.

출처: 문서

본문

aws 확장은 AWS SDK를 사용해 httpfs 확장의 S3 기능 위에 인증 같은 기능을 추가해요.

설치 및 로드

aws 확장은 첫 사용 시 공식 확장 저장소에서 투명하게 자동 로드돼요. 직접 설치하고 로드하려면 다음을 실행해요.

INSTALL aws;
LOAD aws;

대부분의 경우 aws 확장은 httpfs 확장과 함께 동작해요.

구성 및 인증

AWS S3 엔드포인트를 구성하고 인증하는 권장 방법은 secrets를 사용하는 것이에요. 두 가지 S3 secret 제공자가 있어요.

• config 제공자: 접근 키와 secret을 직접 제공해요. httpfs 확장의 일부이며 S3 API 페이지에 문서화되어 있어요. 이미 정적 자격 증명이 있을 때 사용해요.
• credential_chain 제공자: 아래에 설명되며, AWS SDK를 사용해 자격 증명을 자동으로 가져와요. aws 확장이 제공하며 프로필, SSO, 가정된 역할, 웹 ID(IRSA), 인스턴스 메타데이터를 지원해요.

두 제공자 모두에 적용되는 S3 secret 파라미터의 전체 목록(ENDPOINT, REGION, URL_STYLE, USE_SSL, KMS_KEY_ID, REQUESTER_PAYS, …)은 S3 API 페이지에 문서화되어 있어요.

credential_chain 제공자

credential_chain 제공자는 AWS SDK가 제공하는 메커니즘으로 자격 증명을 자동으로 가져오는 것을 허용해요. 예를 들어 AWS SDK 기본 제공자를 사용하려면:

CREATE OR REPLACE SECRET secret (
    TYPE s3,
    PROVIDER credential_chain
);

위 secret으로 파일을 쿼리하려면 s3:// 접두사가 있는 파일을 쿼리하면 돼요.

DuckDB는 CHAIN 키워드로 특정 체인을 지정하는 것도 허용해요. 이는 순서대로 시도될 제공자의 세미콜론으로 구분된 목록(a;b;c)을 받아요. 예를 들어:

CREATE OR REPLACE SECRET secret (
    TYPE s3,
    PROVIDER credential_chain,
    CHAIN 'env;config'
);

CHAIN의 가능한 값은 다음과 같아요.

• config
• sts
• sso
• env
• instance
• process
• web_identity (서비스 계정용 IAM 역할 (IRSA); Web Identity (IRSA) 참고)

credential_chain 제공자는 자동으로 가져온 구성을 재정의하는 것도 허용해요. 예를 들어 자격 증명을 자동으로 로드한 다음 리전을 재정의하려면:

CREATE OR REPLACE SECRET secret (
    TYPE s3,
    PROVIDER credential_chain,
    CHAIN config,
    REGION '⟨eu-west-1⟩'
);

프로필 선택

기본이 아닌 명명된 프로필(AWS_PROFILE 환경 변수 또는 AWS SDK 우선순위에 기반한 기본 프로필)로 자격 증명을 로드하려면 PROFILE 파라미터를 사용해요.

CREATE OR REPLACE SECRET secret (
    TYPE s3,
    PROVIDER credential_chain,
    CHAIN config,
    PROFILE '⟨my_profile⟩'
);

이 접근 방식은 폐기된 S3 API의 load_aws_credentials('⟨my_profile⟩') 메서드와 동일해요.

역할 가정 (STS)

IAM 역할을 가정하려면 ASSUME_ROLE_ARN으로 ARN을 전달해요. 역할 신뢰 정책을 위해 EXTERNAL_ID를 제공할 수 있어요.

CREATE OR REPLACE SECRET secret (
    TYPE s3,
    PROVIDER credential_chain,
    CHAIN 'sts',
    ASSUME_ROLE_ARN 'arn:aws:iam::⟨account_id⟩:role/⟨role⟩',
    EXTERNAL_ID '⟨external_id⟩',
    REGION '⟨us-east-1⟩'
);

sts 체인 값은 ASSUME_ROLE_ARN 값이 필요해요. 선택한 프로필 자체가 STS를 사용한다면 CHAIN 'config'를 대신 사용해요.

웹 ID (IRSA)

Amazon EKS에서 흔히 사용되는 서비스 계정용 IAM 역할 (IRSA)의 경우 역할 ARN과 토큰 파일과 함께 web_identity 체인을 사용해요. SESSION_NAME은 선택적으로 설정할 수 있어요.

CREATE OR REPLACE SECRET secret (
    TYPE s3,
    PROVIDER credential_chain,
    CHAIN 'web_identity',
    ASSUME_ROLE_ARN 'arn:aws:iam::⟨account_id⟩:role/⟨role⟩',
    WEB_IDENTITY_TOKEN_FILE '⟨/var/run/secrets/eks.amazonaws.com/serviceaccount/token⟩'
);

싱글 사인온 (SSO)

DuckDB는 AWS IAM Identity Center (SSO)를 통해 얻은 자격 증명을 사용할 수 있어요. 먼저 명령줄에서 인증한 다음(aws sso login --profile ⟨my-sso-profile⟩), sso 체인으로 secret을 만들어요.

CREATE OR REPLACE SECRET secret (
    TYPE s3,
    PROVIDER credential_chain,
    CHAIN 'sso',
    PROFILE '⟨my-sso-profile⟩'
);

HTTP 프록시

자격 증명을 HTTP 프록시를 통해 가져와야 한다면 secret에 그것을 구성해요.

CREATE OR REPLACE SECRET secret (
    TYPE s3,
    PROVIDER credential_chain,
    HTTP_PROXY '⟨proxy.example.com:8080⟩',
    HTTP_PROXY_USERNAME '⟨username⟩',
    HTTP_PROXY_PASSWORD '⟨password⟩'
);

리전 해석

리전이 명시적으로 제공되지 않으면 DuckDB는 다음 소스에서 순서대로 해석해요.

1. REGION secret 파라미터.
2. s3_region 설정 (SET s3_region = '⟨region⟩').
3. AWS_REGION 환경 변수.
4. AWS_DEFAULT_REGION 환경 변수.
5. ~/.aws/config의 프로필 region.

이 중 어떤 것도 해석되지 않으면 CREATE SECRET는 여전히 성공하지만 DuckDB가 경고를 기록해요.

Set region explicitly using REGION 'us-east-1' in your CREATE SECRET statement, adding a region to your profile in ~/.aws/config or configure the AWS_REGION or AWS_DEFAULT_REGION environment variables.

검증

AWS credential_chain 제공자는 CREATE SECRET 시점에 필요한 어떤 자격 증명이든 찾고, 없거나 사용할 수 없으면 실패해요.

이 동작은 VALIDATION 옵션으로 다음과 같이 구성할 수 있어요.

CREATE OR REPLACE SECRET secret (
    TYPE s3,
    PROVIDER credential_chain,
    VALIDATION 'exists'
);

두 가지 검증 모드가 지원돼요.

• exists(기본값)는 자격 증명이 존재해야 해요.
• none은 사용 가능한 자격 증명이 없는 credential_chains에서 CREATE SECRET이 성공하도록 허용해요.

VALIDATION 'exists'는 자격 증명의 __존재__만 검증하지 __운영 준비 상태__는 검증하지 않아요. 따라서 액세스 토큰으로 변환하거나 읽기, 쓰기 등을 수행하려는 시도는 없어요.

자동 갱신

일부 AWS 엔드포인트는 자격 증명의 주기적 갱신이 필요해요. 이는 REFRESH auto 옵션으로 지정할 수 있어요.

CREATE SECRET env_test (
    TYPE s3,
    PROVIDER credential_chain,
    REFRESH auto
);

CHAIN이 sts 또는 web_identity일 때는 이 자격 증명이 수명이 짧기 때문에 REFRESH auto가 자동으로 활성화돼요.

Amazon RDS (IAM 인증)

aws 확장은 Amazon RDS 및 Aurora 데이터베이스에 연결하기 위한 수명이 짧은 IAM 인증 토큰을 생성할 수 있어요. rds 타입의 secret으로 노출돼요. s3 secret과 동일한 credential_chain 옵션과 필수 RDS_USER, RDS_HOST, RDS_PORT, REGION 파라미터를 받아들여요. s3 secret과 달리 rds secret은 명시적 CHAIN도 요구해요.

CREATE SECRET aws_rds_secret (
    TYPE rds,
    PROVIDER credential_chain,
    REGION '⟨eu-west-1⟩',
    RDS_USER '⟨db_user⟩',
    RDS_HOST '⟨instance⟩.⟨identifier⟩.⟨region⟩.rds.amazonaws.com',
    RDS_PORT '5432'
);

rds secret 타입은 aws가 아니라 postgres 확장이 등록해요. 따라서 위 문장이 실행되기 전에 postgres 확장이 설치되고 로드되어야 해요. AWS_RDS_SECRET로 커넥션에 secret을 전달하고, 부착하고, 쿼리하는 전체 종단 간 설정은 Amazon RDS with IAM authentication 가이드 또는 Postgres secrets 문서를 참고해요.

레거시 기능

폐기 예정 load_aws_credentials 함수는 폐기되었으며 이후 릴리스에서 제거돼요. 대신 credential_chain 제공자와 secret을 사용해요.

버전 0.10.0 이전에는 DuckDB에 Secrets manager가 없었어요. 자격 증명을 자동으로 로드하기 위해 AWS 확장은 레거시 인증 방법에서 AWS 자격 증명을 로드하는 특수 함수를 제공했어요.

함수	타입	설명
load_aws_credentials	PRAGMA 함수	AWS Default Credentials Provider Chain을 통해 AWS 자격 증명을 로드

Load AWS Credentials (레거시)

AWS 자격 증명을 로드하려면 다음을 실행해요.

CALL load_aws_credentials();

loaded_access_key_id	loaded_secret_access_key	loaded_session_token	loaded_region
«redacted:AKIA…»	<redacted>	NULL	us-east-2

이 함수는 특정 프로필을 지정하는 문자열 파라미터를 받아요.

CALL load_aws_credentials('minio-testing-2');

loaded_access_key_id	loaded_secret_access_key	loaded_session_token	loaded_region
minio_duckdb_user_2	<redacted>	NULL	NULL

호출의 동작을 조정하는 몇 가지 파라미터가 있어요.

CALL load_aws_credentials('minio-testing-2', set_region = false, redact_secret = false);

loaded_access_key_id	loaded_secret_access_key	loaded_session_token	loaded_region
minio_duckdb_user_2	minio_duckdb_user_password_2	NULL	NULL

더 알아보기 (Learn more)

• httpfs 확장 S3 API 문서에서 S3 secret 파라미터를 확인해요.
• CREATE SECRET 문에서 secret 생성 방법을 살펴볼 수 있어요.