diff --git a/content/docs/configuration/acme/dns01/route53.md b/content/docs/configuration/acme/dns01/route53.md index 296ac1f197..ad44a49fe6 100644 --- a/content/docs/configuration/acme/dns01/route53.md +++ b/content/docs/configuration/acme/dns01/route53.md @@ -12,14 +12,15 @@ how cert-manager handles DNS01 challenges. > (AWS) and that you already have a hosted zone in Route53. > > 📖 Read -> [Tutorial: Deploy cert-manager on Amazon Elastic Kubernetes (EKS) and use Let's Encrypt to sign a certificate for an HTTPS website](../../../tutorials/getting-started-aws-letsencrypt/README.md), -> which contains end-to-end instructions for those who are new to cert-manager and AWS. +> [Deploy cert-manager on AWS Elastic Kubernetes Service (EKS) and use Let's Encrypt to sign a certificate for an HTTPS website](../../../tutorials/getting-started-aws-letsencrypt/README.md), +> a tutorial which explains how to create an EKS cluster, install cert-manager, and configuring ACME ClusterIssuer using Route53 for DNS-01 challenges.. -## Set up an IAM Role +## Set up an IAM Policy -cert-manager needs to be able to add records to Route53 in order to solve the -DNS01 challenge. To enable this, create a IAM policy with the following -permissions: +cert-manager needs permission to add TXT records to your Route53 zone in order to solve the DNS01 challenge. +It needs permission to delete the TXT records, after the challenge succeeds or fails. +It also needs permission to list the hosted zones, unless you use the `hostedZoneID` field. +To enable this, create an IAM policy with the following permissions in the AWS account of the Route53 zone: ```json { @@ -47,24 +48,54 @@ permissions: } ``` -> Note: The `route53:ListHostedZonesByName` statement can be removed if you +> ℹī¸ The `route53:ListHostedZonesByName` statement can be removed if you > specify the (optional) `hostedZoneID`. You can further tighten the policy by > limiting the hosted zone that cert-manager has access to (e.g. > `arn:aws:route53:::hostedzone/DIKER8JEXAMPLE`). +> +> 📖 Read about [actions supported by Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/APIReference/API_Operations_Amazon_Route_53.html), +> in the [Amazon Route 53 API Reference](https://docs.aws.amazon.com/Route53/latest/APIReference/Welcome.html). ## Credentials -You have two options for the set up - either create a user or a role and attach -that policy from above. Using a role is considered best practice because you do -not have to store permanent credentials in a secret. +[Requests to the Route53 API must be signed using an access key ID and a secret access key](https://docs.aws.amazon.com/Route53/latest/APIReference/requests-authentication.html), +and there are several mechanisms for cert-manager to get the access key ID and secret access key, +some of which are now considered legacy. + +The various mechanisms are described below: + +### IAM Roles for Service Accounts (IRSA) with dedicated Kubernetes ServiceAccount resources + +cert-manager authenticates to Route53 using temporary credentials obtained from STS, +by exchanging a temporary Kubernetes ServiceAccount token for a temporary AWS access key. + +| ✔ī¸ Advantages | ✖ī¸ Disadvantages | +|----------------------------------------|------------------------------------------------------------| +| uses short-lived credentials | Additional RBAC required | +| No key rotation necessary | Additional ServiceAccount required | +| No Kubernetes Secrets | AWS Identity Provider | +| Works best with cloud managed clusters | Kubernetes cluster requires public OIDC discovery document | + +This mechanism works as follows: + +1. cert-manager connects to the Kubernetes API server and requests a [Kubernetes service account token](https://kubernetes.io/docs/concepts/security/service-accounts/#authenticating-credentials) +1. Kubernetes API server returns a [signed JWT](). +1. cert-manager connects to [AWS Security Token Service (STS)](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html) + invoking the [AssumeRoleWithWebIdentity Action](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html), + supplying the Kubernetes signed JWT and the Role ARN specified in the ClusterIssuer (or Issuer). +1. STS returns a [Temporary security credential](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) + (a short lived AWS access key). +1. cert-manager connects to [AWS Route53](https://docs.aws.amazon.com/Route53/latest/APIReference/API_Operations.html) + invoking various actions to create TXT records to satisfy the ACME challenge. + It [signs the requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) using the short lived access key. -cert-manager supports two ways of specifying credentials: +1. IAM Roles for Service Accounts (IRSA). +1. (Legacy) IAM User with Access Key +1. explicit by providing an `accessKeyID` or an `accessKeyIDSecretRef`, and a `secretAccessKeySecretRef` +- or implicit (using [metadata service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) + or [environment variables or credentials file](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials). -- explicit by providing an `accessKeyID` or an `accessKeyIDSecretRef`, and a `secretAccessKeySecretRef` -- or implicit (using [metadata - service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) - or [environment variables or credentials - file](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials). +### IAM Roles for Service Accounts (IRSA) with mounted cert-manager also supports specifying a `role` to enable cross-account access and/or limit the access of cert-manager. Integration with