Let's Encrypt DNS01 Challenge with Route53 Feature on Convox

Hello Convox community! We're excited to announce the integration of Let's Encrypt DNS01 challenge support using AWS Route53. This new feature gives you more flexibility with your SSL certificates and the ability to issue wildcard certificates. In this post, we'll walk you through the setup process and explain why this feature might be useful for your applications.

What is the Let's Encrypt DNS01 Challenge?

The DNS01 challenge allows you to prove domain ownership by creating a specific DNS TXT record. Once verified, Let's Encrypt will issue the SSL certificate. This is an alternative to the HTTP-01 challenge, which requires placing a specific file at a known path on your website.

How Does This Differ from the Default HTTP-01 Challenge?

While the HTTP-01 challenge validates domain ownership through an HTTP endpoint, the DNS01 challenge does so through a DNS TXT record. This method is beneficial for those who prefer not to expose an HTTP endpoint, especially in secure or complex network environments.

What Are the Advantages of the DNS01 Challenge?

The DNS01 challenge offers several advantages:

• Wildcard Certificates: You can secure multiple subdomains with a single wildcard certificate (e.g., *.yourdomain.com).
• Enhanced Security: There's no need to expose an HTTP endpoint.
• Complex Infrastructure Compatibility: Ideal for networks with stringent security requirements.

Pre-Check

Before starting, ensure there are no outdated certificate management objects. Set your kubeconfig to the rack’s context by running:

convox rack kubeconfig > ~/.kube/config

Then, execute the following script to check for outdated objects:

#!/bin/bash
for kind in challenges certificaterequests certificates clusterissuers orders issuers; do
   kubectl explain $kind | grep -e "KIND:" -e "VERSION:"
done
  

All your objects should show v1. If not, please contact Convox support before enabling the DNS01 challenge.

Setting Up Let's Encrypt DNS01 Challenge with Route53

1. Retrieve the IAM Role Used by the Service:

Start by retrieving the IAM role used by the service:

convox letsencrypt dns route53 role

This will return something like:

arn:aws:iam::XXXXXXXXXX:role/convox/rackName-cert-manager

2. Create a Route53 DNS Zone Access Role:

Create a new role in AWS IAM with specific permissions. Use the following policy, replacing <zone-id> with your actual Route53 zone ID:

{
   "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/<zone-id>"
           ]
       }
   ]
}
  

3. Update the Route53 DNS Access Role’s Trust Policy:

Update the role’s Trust Policy in AWS IAM to allow the rackName-cert-manager role to assume it:

{
   "Version": "2012-10-17",
   "Statement": [
       {
           "Effect": "Allow",
           "Principal": {
               "AWS": [
                   "arn:aws:iam::XXXXXXXXXX:role/convox/rackName-cert-manager"
               ]
           },
           "Action": "sts:AssumeRole"
       }
   ]
}
  

4. Add Assume Permission Policy to cert-manager Role:

Add the following permission policy to your rackName-cert-manager role:

{
   "Version": "2012-10-17",
   "Statement": [
       {
           "Effect": "Allow",
           "Action": "sts:AssumeRole",
           "Resource": [
               "arn:aws:iam::XXXXXXXXXX:role/dns-access"
           ]
       }
   ]
}
  

5. Configure DNS Solver for Let's Encrypt:

Use the following command, replacing placeholders with your specific values:

convox letsencrypt dns route53 add --id 1 --dns-zones <your.zone> --role arn:aws:iam::XXXXXX:role/dns-access --hosted-zone-id <hosted-zone-id> --region <hosted-zone-region>

Check the Configuration:

Verify that everything is configured correctly:

convox letsencrypt dns route53 list

You should see something like this:

ID   DNS-ZONES   HOSTED-ZONE-ID    REGION       ROLE
1    your.zone   XXXXXXXXXXXXX     us-east-1    arn:aws:iam::XXXXXXXXXXXXXXX:role/dns-access
  

With these steps completed, Let's Encrypt will leverage the DNS01 challenge to issue a certificate for your domain using the specified Route53 hosted zone.

In Summary

The DNS01 challenge offers a robust alternative for domain validation, especially useful for issuing wildcard certificates. While the HTTP-01 challenge remains the default for its simplicity, this new addition provides an excellent option for specific use cases and network configurations.

We appreciate your continuous engagement with Convox and look forward to supporting your diverse application requirements. Happy coding!