최종 수정: 2026년 10월 16일에

S3

이 문서에서는 AWS S3에 액세스하는 데 필요한 매개변수를 설명합니다. 이 매개변수는 다음 항목에 적용됩니다:

Catalog 속성.
Table Valued Function 속성.
Broker Load 속성.
Export 속성.
Outfile 속성.

HTTPS용 BE CA 인증서 구성

Doris 2.1부터 Doris BE가 HTTPS를 통해 S3에 액세스할 때 ca_cert_file_paths를 be.conf에 명시적으로 구성할 수 있습니다.

기본적으로 ca_cert_file_paths가 구성되지 않으면 Doris는 운영 체제의 기본 CA 인증서를 사용합니다. 대부분의 환경에서는 이 매개변수를 수동으로 설정할 필요가 없습니다. 다음과 같은 경우에 구성하세요:

BE 노드에 시스템 CA 인증서가 없거나 설치된 CA 번들이 너무 오래된 경우.
BE 노드가 ca-certificates 패키지가 포함되지 않은 최소 구성의 컨테이너나 이미지에서 실행되는 경우.
BE 노드의 기본 CA 파일 경로가 유효하지 않거나 Doris 프로세스에 CA 파일 읽기 권한이 없는 경우.
자체 서명 인증서, 사설 CA 또는 TLS 트래픽에 다시 서명하는 기업 프록시나 게이트웨이를 사용하는 환경인 경우.
S3에 액세스할 때 Problem with the SSL CA cert 또는 curl 77: Problem with the SSL CA cert (path? access rights?)와 같은 오류가 발생하는 경우.

ca_cert_file_paths가 없는 버전: ca_cert_file_paths 매개변수는 Doris 2.1부터 사용할 수 있습니다. Doris 2.0.x 이하를 사용하면서 SSL CA 인증서 오류가 발생하면 시스템 CA 인증서가 올바르게 설치되어 있고 CA 번들이 /etc/ssl/certs/ca-certificates.crt에 있는지 확인해야 합니다:
RHEL / CentOS / RockyLinux:
yum install -y ca-certificates
update-ca-trust
ln -s /etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt /etc/ssl/certs/ca-certificates.crt
Debian / Ubuntu: apt-get install -y ca-certificates
그런 다음 모든 BE 노드를 다시 시작하세요. 인증서 문제에 대한 자세한 내용은 Lakehouse FAQ - 인증서 문제를 참조하세요.

예시:

# be.conf
ca_cert_file_paths = /etc/ssl/certs/ca-certificates.crt

일반적인 CA 번들 경로:

Debian / Ubuntu: /etc/ssl/certs/ca-certificates.crt
CentOS / RockyLinux: /etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt

S3에 액세스할 수 있는 모든 BE 노드에 이 항목을 구성하고, 인증서 파일이 존재하며 Doris 프로세스가 해당 파일을 읽을 수 있는지 확인하세요. be.conf를 업데이트한 후 변경 사항을 적용하려면 해당 BE 노드를 다시 시작하세요.

매개변수 개요

속성 이름	설명	기본값	필수 여부
s3.endpoint	S3 서비스 액세스 엔드포인트. 예: `s3.us-east-1.amazonaws.com`	없음	아니요
s3.access_key	인증에 사용하는 AWS Access Key	없음	아니요
s3.secret_key	인증에 사용하는 AWS Secret Key	없음	아니요
s3.region	S3 리전. 예: `us-east-1`. 설정을 강력히 권장합니다	없음	예
s3.use_path_style	경로 스타일 액세스 사용 여부	FALSE	아니요
s3.connection.maximum	동시성이 높은 시나리오의 최대 연결 수	50	아니요
s3.connection.request.timeout	요청 시간 초과(밀리초). 연결 획득 시간 초과를 제어합니다	3000	아니요
s3.connection.timeout	연결 설정 시간 초과(밀리초)	1000	아니요
s3.role_arn	Assume Role 모드를 사용할 때 지정하는 Role ARN	없음	아니요
s3.external_id	`s3.role_arn`과 함께 사용하는 외부 ID	없음	아니요
s3.credentials_provider_type	AWS 인증에 사용하는 자격 증명 공급자 유형(AK/SK 없이 사용하며, IAM Role 모드에서는 STS 소스 자격 증명으로 사용)	DEFAULT	아니요

버전 참고: s3.credentials_provider_type은 3.1.4 및 4.0.3부터 지원됩니다.

인증 구성

Doris는 S3에 액세스하는 다음 세 가지 방법을 지원합니다:

1. Access Key 및 Secret Key(AK/SK)를 통한 직접 액세스

"s3.access_key"="your-access-key",
"s3.secret_key"="your-secret-key",
"s3.endpoint"="https://s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

2. IAM Role(Assume Role) 모드

교차 계정 액세스와 임시 권한 부여를 통한 액세스에 적합합니다. Doris는 역할 권한 부여를 통해 임시 자격 증명을 자동으로 가져옵니다.

"s3.role_arn"="arn:aws:iam::123456789012:role/demo-role",
"s3.external_id"="external-identifier",
"s3.endpoint"="https://s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

IAM Role 모드에서 `s3.credentials_provider_type` 구성

s3.role_arn이 구성된 경우 s3.credentials_provider_type은 STS AssumeRole에 사용할 소스 자격 증명 공급자를 결정합니다:

s3.credentials_provider_type에서 소스 자격 증명을 가져옵니다.
소스 자격 증명으로 STS AssumeRole을 호출합니다.
반환된 임시 자격 증명으로 S3에 액세스합니다.

IAM Role + `s3.credentials_provider_type` 예시

예시 1: EC2 Instance Profile을 STS 소스 자격 증명으로 사용

"s3.role_arn"="arn:aws:iam::123456789012:role/demo-role",
"s3.external_id"="external-identifier",
"s3.credentials_provider_type"="INSTANCE_PROFILE",
"s3.endpoint"="https://s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

예시 2: Web Identity(예: IRSA)를 STS 소스 자격 증명으로 사용

"s3.role_arn"="arn:aws:iam::123456789012:role/demo-role",
"s3.credentials_provider_type"="WEB_IDENTITY",
"s3.endpoint"="https://s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

예시 3: 컨테이너 메타데이터를 STS 소스 자격 증명으로 사용

"s3.role_arn"="arn:aws:iam::123456789012:role/demo-role",
"s3.credentials_provider_type"="CONTAINER",
"s3.endpoint"="https://s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

예시 4: 기본 공급자 체인을 STS 소스 자격 증명으로 사용

"s3.role_arn"="arn:aws:iam::123456789012:role/demo-role",
"s3.credentials_provider_type"="DEFAULT",
"s3.endpoint"="https://s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

3. `s3.credentials_provider_type`으로 자격 증명 소스 지정

EC2 Instance Profile, 컨테이너 메타데이터 또는 Web Identity와 같이 AK/SK를 명시적으로 지정하지 않는 시나리오에 적합합니다.

"s3.credentials_provider_type"="INSTANCE_PROFILE",
"s3.endpoint"="https://s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

`s3.credentials_provider_type`의 지원 값

값	설명
DEFAULT	기본 공급자 체인 사용
ENV	환경 변수에서 자격 증명 읽기
SYSTEM_PROPERTIES	시스템 속성에서 자격 증명 읽기
WEB_IDENTITY	Web Identity Token 자격 증명 사용
CONTAINER	컨테이너 메타데이터 자격 증명 사용
INSTANCE_PROFILE	EC2 Instance Profile 자격 증명 사용
ANONYMOUS	익명 액세스(공개 버킷용)

함께 구성할 때의 적용 규칙

s3.access_key와 s3.secret_key가 모두 구성된 경우 AK/SK가 우선 사용됩니다.
AK/SK가 구성되지 않고 s3.role_arn이 구성된 경우 IAM Role이 사용됩니다. 이때 s3.credentials_provider_type은 STS 소스 자격 증명을 선택하는 데 사용됩니다.
AK/SK와 s3.role_arn이 모두 구성되지 않은 경우 s3.credentials_provider_type이 S3 클라이언트에서 사용할 자격 증명 공급자를 직접 결정합니다.

참고: s3.access_key와 s3.secret_key는 함께 구성해야 합니다.

AWS 인증 및 권한 부여 구성 방법은 AWS 인증 및 권한 부여 문서를 참조하세요.

EKS Pod Identity(4.1.5부터 지원)

4.1.5부터 BE 및 관련 C++ 스토리지 액세스 경로는 EKS Pod Identity의 컨테이너 자격 증명 엔드포인트와 인증 토큰 파일을 지원합니다. EKS는 AWS_CONTAINER_CREDENTIALS_FULL_URI와 AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE을 Pod에 주입해야 하며, Doris 프로세스는 해당 엔드포인트에 연결하고 토큰 파일을 읽을 수 있어야 합니다. 컨테이너 자격 증명 공급자(s3.credentials_provider_type=CONTAINER 또는 이 공급자를 선택하는 기본 체인)를 사용할 때는 우선순위가 더 높은 AK/SK 자격 증명을 함께 구성하지 마세요.

이 공급자는 토큰 교체를 지원하기 위해 자격 증명을 가져올 때 토큰 파일을 다시 읽습니다. ECS와 호환되는 AWS_CONTAINER_CREDENTIALS_RELATIVE_URI와 AWS_CONTAINER_AUTHORIZATION_TOKEN도 계속 지원됩니다. 상대 URI와 전체 URI가 모두 있으면 상대 URI가 우선합니다. 이 변경 사항은 FE의 별도 Java 자격 증명 구성을 대체하지 않습니다. FE와 BE의 액세스를 각각 확인하세요.

S3 Directory Bucket 액세스

이 기능은 버전 3.1.0부터 지원됩니다.

Amazon S3 Express One Zone(Directory Bucket이라고도 함)은 더 높은 성능을 제공하지만 엔드포인트 형식이 다릅니다.

일반 버킷: s3.us-east-1.amazonaws.com
Directory Bucket: s3express-usw2-az1.us-west-2.amazonaws.com

사용 가능한 다른 리전은 AWS 공식 문서를 참조하세요.

예시:

"s3.access_key"="ak",
"s3.secret_key"="sk",
"s3.endpoint"="https://s3express-usw2-az1.us-west-2.amazonaws.com",
"s3.region"="us-west-2"

권한 정책

사용 사례에 따라 권한 정책은 읽기 전용과 읽기/쓰기로 나눌 수 있습니다.

1. 읽기 전용 권한

S3의 객체 읽기만 허용합니다. LOAD, TVF, EXTERNAL CATALOG 쿼리 등의 시나리오에 적합합니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
              "s3:GetObject",
              "s3:GetObjectVersion",
            ],
            "Resource": "arn:aws:s3:::<your-bucket>/your-prefix/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": "arn:aws:s3:::<your-bucket>"
        }    
    ]
}

2. 읽기/쓰기 권한

읽기 전용 권한에 더해 객체의 삭제, 생성, 수정도 허용합니다. EXPORT, OUTFILE 및 EXTERNAL CATALOG에 데이터를 다시 쓰는 시나리오에 적합합니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
              "s3:PutObject",
              "s3:GetObject",
              "s3:GetObjectVersion",
              "s3:DeleteObject",
              "s3:DeleteObjectVersion",
              "s3:AbortMultipartUpload",      
              "s3:ListMultipartUploadParts"
            ],
            "Resource": "arn:aws:s3:::<your-bucket>/<your-prefix>/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation",
                "s3:GetBucketVersioning",
                "s3:GetLifecycleConfiguration"
            ],
            "Resource": "arn:aws:s3:::<your-bucket>"
        }    
    ]
}

참고 사항

플레이스홀더 치환
- <bucket> → S3 버킷 이름.
- <account-id> → AWS 계정 ID(12자리 숫자).
최소 권한 원칙
- 쿼리만 수행하는 경우 쓰기 권한을 부여하지 마세요.

HTTPS용 BE CA 인증서 구성​

매개변수 개요​

인증 구성​

1. Access Key 및 Secret Key(AK/SK)를 통한 직접 액세스​

2. IAM Role(Assume Role) 모드​

IAM Role 모드에서 s3.credentials_provider_type 구성​

IAM Role + s3.credentials_provider_type 예시​

3. s3.credentials_provider_type으로 자격 증명 소스 지정​

s3.credentials_provider_type의 지원 값​

함께 구성할 때의 적용 규칙​

EKS Pod Identity(4.1.5부터 지원)​

S3 Directory Bucket 액세스​

권한 정책​

1. 읽기 전용 권한​

2. 읽기/쓰기 권한​

참고 사항​