Automatically obtaining SSL certificates by Let’s Encrypt using DNS-01 challenge, and AWS

This post describes the steps needed for setting up automatic SSL certificates creation and renewal, using Let's Encrypt as the automated Certificate Authority, which provides a well-maintained API.

acme-dns-route53 is the tool to obtain SSL certificates from Let’s Encrypt using DNS-01 challenge with Route53 and Amazon Certificate Manager by AWS. acme-dns-route53 also has the built-in functionality for using this tool inside AWS Lambda, and this is what we are going to do.

This post is broken down into 4 sections:

• build a self-contained, deployable zip-file
• creating an IAM role for lambda function that gives it the necessary permissions to execute
• creating a lambda function which executes acme-dns-route53
• creating a CloudWatch timer that triggers a lambda function twice a day

Note: before starting, make sure that GoLang 1.9+ and AWS CLI already installed.

Built a self-contained, deployable zip-file

acme-dns-route53 is written in GoLang and supporting version not less than 1.9. We need to create a self-contained, deployable zip-file which contains executable of acme-dns-route53 tool inside.

The first step is to build an executable from remote GitHub repo of acme-dns-route53 tool using go install command:

$ env GOOS=linux GOARCH=amd64 go install github.com/begmaroman/acme-dns-route53

The executable will be installed in $GOPATH/bin directory. Important: as part of this command we're using env to temporarily set two environment variables for the duration for the command (GOOS=linux and GOARCH=amd64). These instruct the Go compiler to create an executable suitable for use with a Linux OS and amd64 architecture — which is what it will be running on when we deploy it to AWS.
AWS requires us to upload our lambda functions in a zip file, so let's make an acme-dns-route53.zip file containing the executable we just made:

$ zip -j ~/acme-dns-route53.zip $GOPATH/bin/acme-dns-route53

Note that the executable must be in the root of the zip file — not in a folder within the zip file. To ensure this I've used the -j flag in the snippet above to junk directory names.

Now the zip-file can be deployed, but it still needs permissions to run.

Creating an IAM role for lambda function that gives it the necessary permissions to execute

We need to set up an IAM role which defines the permission that our lambda function will have when it is running.
For now, let's set up a lambda-acme-dns-route53-executor role with a trust relationship for lambda.amazonaws.com (this is the principal that lambda functions assume when they execute) and attach the AWSLambdaBasicExecutionRole managed policy to it. This will give our lambda function the basic permissions it needs to run and log to the AWS CloudWatch service.

First, we have to create a trust policy JSON file. This will essentially instruct AWS to allow lambda services to assume the lambda-acme-dns-route53-executor role:

$ touch ~/lambda-acme-dns-route53-executor-policy.json

Then attach the inline policy below — it boils down to 4 categories:

• CloudWatch permissions that all lambda functions need to log and emit metrics
• Route53 permissions for acme-dns-route53 to list and update your DNS settings
• ACM permissions for the glue code to list and import certificates
• SNS publish permission to send notifications when a new certificate is imported

Then use the aws iam create-role command to create the role with this trust policy:

$ aws iam create-role --role-name lambda-acme-dns-route53-executor \
 --assume-role-policy-document ~/lambda-acme-dns-route53-executor-policy.json

Note: the returned ARN (Amazon Resource Name) — you'll need this in the next step.

Now the lambda-acme-dns-route53-executor role has been created we need to specify the permissions that the role has. The easiest way to do this is to use the aws iam attach-role-policy command, passing in the ARN of AWSLambdaBasicExecutionRole permission policy like so:

$ aws iam attach-role-policy --role-name lambda-acme-dns-route53-executor \
--policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

Note: you can find a list of other permission policies that might be useful here.

Creating a lambda function which executes acme-dns-route53

Now we’re ready to actually deploy the lambda function to AWS, which we can do using the aws lambda create-function command. The lambda function needs to be configured with the following options:

• AWS_LAMBDA is the environment variable with the value 1 which adjusts the tool for using inside Lambda function.
• DOMAINS is the environment variable which contains comma-separated domains list.
• LETSENCRYPT_EMAIL is the environment variable which contains Let’s Encrypt expiration email.
• NOTIFICATION_TOPIC is the environment variable which contains SNS Notification Topic ARN.
• STAGING is the environment variable which must contain 1 value for using staging Let’s Encrypt environment or 0 for production environment.
• 1024 MB is the memory limit (can be changed if needed).
• 900 secs (15 min) is the maximum timeout.
• acme-dns-route53 is the handler name of the lambda function.
• fileb://~/acme-dns-route53.zip is the created .zip file above.

Go ahead and try to deploy it:

$ aws lambda create-function \
 --function-name acme-dns-route53 \
 --runtime go1.x \
 --role arn:aws:iam::<AWS_ACCOUNT_ID>:role/lambda-acme-dns-route53-executor \
 --environment Variables="{AWS_LAMBDA=1,DOMAINS=\"example1.com,example2.com\",LETSENCRYPT_EMAIL=begmaroman@gmail.com,STAGING=0,NOTIFICATION_TOPIC=acme-dns-route53-obtained}" \
 --memory-size 1024 \
 --timeout 900 \
 --handler acme-dns-route53 \
 --zip-file fileb://~/acme-dns-route53.zip

Creating a CloudWatch timer that triggers a lambda function once a day

The last step is to create a daily trigger for the function. To do this we can:

• create a CloudWatch rule with the desired schedule_expression (when should it run).
• create a rule target (what should run) specifying the lambda function’s ARN.
• give the CloudWatch rule permission to invoke the lambda function.

I’ve pasted my Terraform config for it below, but it’s also very straightforward to do it from either the AWS console or CLI.

Now you too can have 100% automated TLS certificate renewals!