diff --git a/content/docs/configuration/acme/dns01/route53.md b/content/docs/configuration/acme/dns01/route53.md index 296ac1f197..a118f2d9bd 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,30 +48,96 @@ 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 in order of best practice. + +### IAM Roles for Service Accounts (IRSA) with dedicated ServiceAccount + +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 Role and RoleBinding required | +| No key rotation necessary | Additional ServiceAccount required | +| No Kubernetes Secrets | Requires an AWS Identity Provider | +| Works with any Kubernetes cluster | Kubernetes cluster requires public OIDC discovery document | +| **Good isolation of Issuer permissions** | | + +#### Mechanism + +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. + +#### Configuration + +TODO + +### IAM Roles for Service Accounts (IRSA) with mounted ServiceAccount token + +cert-manager authenticates to Route53 using temporary credentials obtained from STS, +by exchanging a temporary Kubernetes ServiceAccount token for a temporary AWS access key. +The Kubernetes ServiceAccount token is mounted into the Pod of the cert-manager controller. + +| ✔ī¸ Advantages | ✖ī¸ Disadvantages | +|----------------------------------|---------------------------------------------------| +| uses short-lived credentials | Requires an AWS Identity Provider | +| No key rotation necessary | **Poor isolation of Issuer permissions** | +| No Kubernetes Secrets | | +| **Works best with EKS clusters** | Requires a projected service account token volume | +| | (unless you use the EKS Pod Identity Webhook) | + + +#### Mechanism + +1. Kubernetes API server regularly generates a signed JWT which is mounted into the cert-manager controller Pod, + at file path which is stored in the environment variable: `AWS_WEB_IDENTITY_TOKEN_FILE`. +1. cert-manager reads the signed JWT from the file system. +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. + + +#### Configuration + +TODO + +### Load credentials from EC2 Instance metadata service + +TODO -cert-manager supports two ways of specifying credentials: +### Load User access key from dedicated Secret -- 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). +TODO -cert-manager also supports specifying a `role` to enable cross-account access -and/or limit the access of cert-manager. Integration with -[`kiam`](https://github.com/uswitch/kiam) and -[`kube2iam`](https://github.com/jtblin/kube2iam) should work out of the box. +### Load User access key from mounted Secret +TODO ## Cross Account Access