DNS01 Challenge with Route53 and Cert Manager

Introduction This document will guide you through the process of setting up a DNS01 challenge in route53 with cert manager. The DNS01 challenge is a method of proving domain ownership by adding a specific TXT record to the domain’s DNS zone. This guide also covers the steps for cross-account access, where we will be issuing a certificate for a subdomain hosted in AWS Account-B from Account-A.

Prerequisites

• An existing Route53 hosted zone in Account-B
• Cert-manager installed in your cluster
• An OpenID Connect (OIDC) provider for your EKS cluster

Step 1: IAM Roles in Account-A

• Follow this guide to enable IAM roles for service accounts in your EKS cluster: https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html
• Create an IAM role called cert-manager in account-A with the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Resource": "*",
            "Action": "sts:AssumeRole"
        }
    ]
}

• Create a trust relationship for the cert-manager role with the following policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::<account-A>:oidc-provider/oidc.eks.<region>.amazonaws.com/id/<eks-hash>"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "oidc.eks.<region>.amazonaws.com/id/<eks-hash>:sub": "system:serviceaccount:<namespace>:<service-account-name>"
                }
            }
        }
    ]
}

This role will allow our service account for cert-manager to grant access to the Route53 hosted zone in Account-B.

Step 2: Upgrading Cert-Manager

• Create a file called values.yaml with the following contents:

installCRDs: true
serviceAccount:
  name: scrut-cert-manager
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::<account-id>:role/cert-manager
extraArgs:
  - --issuer-ambient-credentials

• Run the following command to upgrade cert-manager using the values.yaml file:

helm upgrade -f values.yaml cert-manager jetstack/cert-manager -n cert-manager --set extraArgs='{--dns01-recursive-nameservers-only}'

Note: The --dns01-recursive-nameservers-only flag is used to prevent cert-manager from making changes to the domain's DNS zone. More information can be found here: https://cert-manager.io/docs/configuration/acme/dns01/route53/

Step 3: IAM Roles in Account-B

• Create an IAM role called dns-manager in account-B with the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "route53:GetChange",
            "Resource": "arn:aws:route53:::change/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "route53:ChangeResourceRecordSets",
                "route53:ListResourceRecordSets"
            ],
            "Resource": "arn:aws:route53:::hostedzone/*"
        },
        {
            "Effect": "Allow",
            "Action": "route53:ListHostedZonesByName",
            "Resource": "*"
        }
    ]
}

• Create a trust relationship for the dns-manager role with the following policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<account-A>:role/cert-manager"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

This role will allow the cert-manager role in account-A to assume temporary credentials in account-B, in order to add the necessary TXT record for domain verification.

Step 4: Cluster Issuer for DNS01

• Create a file called letsencrypt-dns01-clusterIssuer.yaml with the following contents:

apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
  name: letsencrypt-dns01
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: <your email>
    privateKeySecretRef:
      name: letsencrypt-dns01
    solvers:
    - dns01:
        route53:
          accessKeyID: <access key for account-B>
          secretAccessKeySecretRef:
            name: route53-secret
            key: secretAccessKey

This file will configure cert-manager to use the DNS01 challenge with Let’s Encrypt’s v2 API. Replace the placeholders with the appropriate values.

Step 5: Apply the Cluster Issuer

• Apply the ClusterIssuer to your cluster with the following command:

kubectl apply -f letsencrypt-dns01-clusterIssuer.yaml

Your cert-manager is now configured to issue certificates using the DNS01 challenge with Route53. You can now proceed to create a certificate and apply it to your workloads.

Conclusion 🎉

This documentation provided a comprehensive guide on how to set up DNS01 challenge in route53 with cert manager, including the steps for cross-account access and the necessary configurations for IAM roles, cert manager, and the cluster issuer. With this setup, you can easily issue and manage SSL/TLS certificates for your domains hosted in AWS route53.