AWS-Erweiterung

Die Erweiterung aws ergänzt Funktionalität, z. B. Authentifizierung, auf den S3-Fähigkeiten der Erweiterung httpfs, und zwar über das AWS SDK.

Installation und Laden

Die Erweiterung aws wird beim ersten Einsatz transparent aus dem offiziellen Erweiterungs-Repository automatisch geladen. Wenn Sie sie manuell installieren und laden möchten, führen Sie aus:

INSTALL aws;
LOAD aws;

In den meisten Fällen arbeitet die Erweiterung aws zusammen mit der Erweiterung httpfs.

Konfiguration und Authentifizierung

Der bevorzugte Weg, AWS-S3-Endpunkte zu konfigurieren und sich dort zu authentifizieren, sind Secrets. Es gibt zwei S3-Secret-Provider:

Den Provider config, bei dem Sie Access Key und Secret manuell angeben. Er gehört zur Erweiterung httpfs und ist auf der S3-API-Seite dokumentiert. Nutzen Sie ihn, wenn Sie bereits statische Zugangsdaten haben.
Den Provider credential_chain, der unten beschrieben wird und Zugangsdaten automatisch über das AWS SDK holt. Er wird von der Erweiterung aws bereitgestellt und unterstützt Profile, SSO, angenommene Rollen, Web Identities (IRSA) und Instance Metadata.

Die vollständige Liste der S3-Secret-Parameter, die für beide Provider gelten (ENDPOINT, REGION, URL_STYLE, USE_SSL, KMS_KEY_ID, REQUESTER_PAYS, …), steht auf der S3-API-Seite.

Provider `credential_chain`

Der Provider credential_chain holt Zugangsdaten automatisch über Mechanismen des AWS SDK. Um beispielsweise den Standard-Provider des AWS SDK zu nutzen:

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

Um eine Datei mit dem obigen Secret abzufragen, fragen Sie einfach eine mit s3:// beginnende Datei ab.

DuckDB erlaubt außerdem, mit dem Schlüsselwort CHAIN eine bestimmte Kette anzugeben. Das ist eine durch Semikolon getrennte Liste (a;b;c) von Providern, die der Reihe nach versucht werden. Beispiel:

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

Mögliche Werte für CHAIN sind:

config
sts
sso
env
instance
process
web_identity (für IAM Roles for Service Accounts (IRSA); siehe Web Identity (IRSA))

Der Provider credential_chain erlaubt auch, die automatisch geholte Konfiguration zu überschreiben. Um beispielsweise Zugangsdaten automatisch zu laden und dann die Region zu überschreiben:

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

Profil auswählen

Um Zugangsdaten anhand eines benannten Profils zu laden, das nicht das Standardprofil ist (aus der Umgebungsvariable AWS_PROFILE oder dem Standardprofil gemäß AWS-SDK-Rangfolge), verwenden Sie den Parameter PROFILE:

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

Dieser Ansatz entspricht der Methode load_aws_credentials('⟨my_profile⟩') der veralteten S3-API.

Rolle annehmen (STS)

Um eine IAM-Rolle anzunehmen, übergeben Sie ihren ARN über ASSUME_ROLE_ARN. Für die Trust Policy der Rolle kann eine EXTERNAL_ID angegeben werden:

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⟩'
);

Der Kettenwert sts erfordert einen Wert für ASSUME_ROLE_ARN. Wenn das gewählte Profil selbst STS verwendet, nutzen Sie stattdessen CHAIN 'config'.

Web Identity (IRSA)

Für IAM Roles for Service Accounts (IRSA) — üblich auf Amazon EKS — verwenden Sie die Kette web_identity zusammen mit einem Rollen-ARN und einer Token-Datei. Optional kann ein SESSION_NAME gesetzt werden:

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⟩'
);

Single Sign-On (SSO)

DuckDB kann Zugangsdaten nutzen, die über das AWS IAM Identity Center (SSO) bezogen wurden. Authentifizieren Sie sich zuerst auf der Kommandozeile (aws sso login --profile ⟨my-sso-profile⟩) und legen Sie dann ein Secret mit der Kette sso an:

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

HTTP-Proxy

Wenn Zugangsdaten über einen HTTP-Proxy geholt werden müssen, konfigurieren Sie ihn am 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⟩'
);

Regionsauflösung

Wenn keine Region explizit angegeben wird, ermittelt DuckDB sie in dieser Reihenfolge aus den folgenden Quellen:

Dem Secret-Parameter REGION.
Der Einstellung s3_region (SET s3_region = '⟨region⟩').
Der Umgebungsvariable AWS_REGION.
Der Umgebungsvariable AWS_DEFAULT_REGION.
Der region des Profils in ~/.aws/config.

Wenn keine davon greift, gelingt CREATE SECRET trotzdem, DuckDB protokolliert aber eine Warnung:

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.

Validierung

Der AWS-Provider credential_chain sucht zur Zeit von CREATE SECRET nach allen erforderlichen Zugangsdaten und schlägt fehl, wenn sie fehlen oder nicht verfügbar sind.

Dieses Verhalten lässt sich über die Option VALIDATION steuern:

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

Zwei Validierungsmodi werden unterstützt:

exists (Standard) verlangt vorhandene Zugangsdaten.
none erlaubt, dass CREATE SECRET für credential_chains ohne verfügbare Zugangsdaten gelingt.

VALIDATION 'exists' prüft nur das Vorhandensein einer Zugangsdate, nicht ihre Einsatzbereitschaft. Es wird also nicht versucht, sie in ein Access Token umzuwandeln oder einen Lese- oder Schreibvorgang auszuführen.

Auto-Refresh

Manche AWS-Endpunkte erfordern ein periodisches Auffrischen der Zugangsdaten. Das können Sie mit der Option REFRESH auto angeben:

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

Wenn CHAIN den Wert sts oder web_identity hat, ist REFRESH auto automatisch aktiv, weil diese Zugangsdaten nur kurz leben.

Amazon RDS (IAM-Authentifizierung)

Die Erweiterung aws kann kurzlebige IAM-Authentifizierungstoken für die Verbindung zu Amazon-RDS- und Aurora-Datenbanken erzeugen, bereitgestellt über ein Secret vom Typ rds. Es akzeptiert dieselben Optionen von credential_chain wie ein s3-Secret sowie die erforderlichen Parameter RDS_USER, RDS_HOST, RDS_PORT und REGION. Anders als ein s3-Secret braucht ein rds-Secret außerdem eine explizite 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'
);

Der Secret-Typ rds wird von der Erweiterung postgres registriert, nicht von aws. Die Erweiterung postgres muss daher installiert und geladen sein, bevor die obige Anweisung läuft. Für den vollständigen End-to-End-Aufbau — Übergabe des Secrets an eine Verbindung über AWS_RDS_SECRET, Anhängen und Abfragen — siehe die Anleitung zu Amazon RDS mit IAM-Authentifizierung oder die Dokumentation zu Postgres-Secrets.

Veraltete Funktionen

Veraltet Die Funktion load_aws_credentials ist veraltet und entfällt in späteren Versionen. Verwenden Sie stattdessen ein Secret mit dem Provider credential_chain.

Vor Version 0.10.0 hatte DuckDB keinen Secrets Manager. Um Zugangsdaten automatisch zu laden, bot die AWS-Erweiterung eine spezielle Funktion, die die AWS-Zugangsdaten in der veralteten Authentifizierungsmethode lud.

Funktion	Typ	Beschreibung
`load_aws_credentials`	`PRAGMA`-Funktion	Lädt die AWS-Zugangsdaten über die AWS Default Credentials Provider Chain

AWS-Zugangsdaten laden (veraltet)

Um die AWS-Zugangsdaten zu laden, führen Sie aus:

CALL load_aws_credentials();

loaded_access_key_id	loaded_secret_access_key	loaded_session_token	loaded_region
AKIAIOSFODNN7EXAMPLE	`<redacted>`	NULL	us-east-2

Die Funktion nimmt einen String-Parameter, um ein bestimmtes Profil anzugeben:

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

Mehrere Parameter steuern das Verhalten des Aufrufs:

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