docs(tutorials/aws): document AWS SDK credential provider chain (#6444)

alekc · web-flow · commit 31efa3df3686 · 2026-06-01T04:34:48.000+05:30
* docs(tutorials/aws): document AWS SDK credential provider chain ExternalDNS resolves AWS credentials via the aws-sdk-go-v2 default credential provider chain (provider/aws/config.go uses config.LoadDefaultConfig), so any credential source the SDK supports works — including AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY env vars, AWS_SHARED_CREDENTIALS_FILE / AWS_CONFIG_FILE, EC2 instance profile, ECS container credentials, and EKS Pod Identity. The tutorial previously documented only three deployment patterns (Node IAM Role, mounted credentials file, IRSA), leaving users to guess that env vars work or dig through Helm chart values. Add a note pointing at the AWS SDK reference for the full chain plus a tip showing the env-var pattern via the Helm chart's env: block, which is the concrete recipe users have been reconstructing from scratch. Refs #5265 * docs(tutorials/aws): clarify which Helm chart the env example targets Be explicit that the env-var example targets the in-tree external-dns Helm chart under charts/external-dns/, since multiple community charts named "external-dns" exist with different value schemas. * docs(aws): streamline AWS credential provider chain documentation following feedback Signed-off-by: Alexander Chernov <alexander@chernov.it> * docs(aws): enhance security guidance for AWS credential methods in documentation Signed-off-by: Alexander Chernov <alexander@chernov.it> * docs(tutorials/aws): fix markdownlint errors in static credentials section The Lint workflow rejected the previous commits with MD004/MD030/MD032/ MD028/MD031/MD022 violations against the static-credentials blockquote. Convert bullet markers from `*` to `-` (MD004) and trim the spacing after markers to one space (MD030). Add the blank-blockquote separator lines before each list inside a blockquote (MD032). Add a non-blockquote separator between the two consecutive `[!TIP]` callouts (MD028). Add the blank line between the closing fence and the next heading (MD031, MD022). Refs: #5265 Signed-off-by: Alexander Chernov <alexander@chernov.it> --------- Signed-off-by: Alexander Chernov <alexander@chernov.it>
diff --git a/docs/tutorials/aws.md b/docs/tutorials/aws.md
@@ -123,6 +123,13 @@ You will need to use the above policy (represented by the `POLICY_ARN` environme
 - [Static credentials](#static-credentials)
 - [IAM Roles for Service Accounts](#iam-roles-for-service-accounts)
 
+> [!NOTE]
+> ExternalDNS resolves AWS credentials through the
+> [AWS SDK for Go v2 default credential provider chain](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html#specifying-credentials).
+> Any source supported by the SDK works without additional configuration in ExternalDNS — including environment
+> variables, shared config and credentials files, EC2 instance profile / ECS container credentials, and EKS Pod
+> Identity. See the AWS SDK reference for the full list and precedence order.
+
 For this tutorial, ExternalDNS will use the environment variable `EXTERNALDNS_NS` to represent the namespace, defaulted to `default`.
 Feel free to change this to something else, such `externaldns` or `kube-addons`.
 Make sure to edit the `subjects[0].namespace` for the `ClusterRoleBinding` resource when deploying ExternalDNS with RBAC enabled.
@@ -249,9 +256,32 @@ If ExternalDNS is not yet deployed, follow the steps under [Deploy ExternalDNS](
 
 In this method, the policy is attached to an IAM user, and the credentials secrets for the IAM user are then made available using a Kubernetes secret.
 
-This method is not the preferred method as the secrets in the credential file could be copied and used by an unauthorized threat actor.
+> [!WARNING]
+> **Security Risks with Static Credentials**
+>
+> - `kubectl describe pod` could expose secrets.
+> - Anyone who can `exec` into the container and run `env` can see them.
+> - Env vars can leak into logs, crash dumps, or child processes.
+> - There is no way to make them visible to a specific user only.
+> - They are long-lived, easy to leak, hard to rotate, and easy to accidentally commit or log.
+>
+> **When to use:**
+>
+> - Limit usage to non-AWS clusters.
+> - Always apply minimal privileges.
+> - Acknowledges reality (sometimes it is the only viable option).
+>
+> **For AWS specifically, the best practice and recommended hierarchy is:**
+>
+> 1. **IRSA (preferred):** Map an AWS IAM role to a Kubernetes service account; no static credentials in the pod.
+> 2. **EKS Pod Identity:** Native EKS alternative to IRSA; associates IAM role with a service account via the Pod Identity Agent.
+> 3. **Node IAM Role:** Attach policy to the node instance profile; not recommended beyond tests because all pods on the node inherit the permissions. Tolerated, but not recommended.
+> 4. **Mount credentials file:** Minimize privileges and avoid long-lived keys where possible.
+> 5. **Environment variables:** Minimize privileges and avoid long-lived keys where possible.
+
+This method is not the preferred method as the secrets in the credential file or environment variables could be copied and used by an unauthorized threat actor.
 However, if the Kubernetes cluster is not hosted on AWS, it may be the only method available.
-Given this situation, it is important to limit the associated privileges to just minimal required privileges, i.e. read-write access to Route53, and not used a credentials file that has extra privileges beyond what is required.
+Given this situation, it is important to limit the associated privileges to just minimal required privileges, i.e. read-write access to Route53, and not use a credentials file that has extra privileges beyond what is required.
 
 #### Create IAM user and attach the policy
 
@@ -296,6 +326,30 @@ Follow the steps under [Deploy ExternalDNS](#deploy-externaldns) using either RB
 > ExternalDNS looks for the hosted zones in all profiles and keeps maintaining a mapping table between zone and profile
 > in order to be able to modify the zones in the correct profile.
 
+<!-- markdownlint-disable-line MD028 -->
+
+> [!TIP]
+> To pass static credentials as environment variables (e.g. when running outside AWS and
+> mounting the credentials file is not convenient), source them from a Kubernetes `Secret`
+> and project them into the pod. With the
+> [in-tree `external-dns` Helm chart](https://github.com/kubernetes-sigs/external-dns/tree/master/charts/external-dns),
+> set the top-level `env` value:
+>
+> ```yaml
+> # values.yaml
+> env:
+>   - name: AWS_ACCESS_KEY_ID
+>     valueFrom:
+>       secretKeyRef:
+>         name: aws-route53-credentials
+>         key: aws-access-key-id
+>   - name: AWS_SECRET_ACCESS_KEY
+>     valueFrom:
+>       secretKeyRef:
+>         name: aws-route53-credentials
+>         key: aws-secret-access-key
+> ```
+
 ### IAM Roles for Service Accounts
 
 [IRSA](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) ([IAM roles for Service Accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)) allows cluster operators to map AWS IAM Roles to Kubernetes Service Accounts.
