Using private domains for APIs with Serverless Framework and Terraform
By: Roberto Javier Yudice Monico
Tags: DevOps, Terraform, Serverless

Photo by Maarten Deckers on Unsplash

By default when creating an AWS API Gateway you will get an AWS generated domain name, which is neither easy to remember or reliable and it could change if you for some reason need to recreate your API gateway or the whole cloud formation stack. While normally the chances of recreating your gateway are low, this is not the case when working with the Serverless Framework, since it internally uses a cloud formation stack which can sometimes get desynched and you might need to recreate it. Also as mentioned before the DNS name created by AWS is not easy to remember and is not expressive either.

The generated DNS is also hard to remember as it is a subdomain with a bunch of random characters. To make your API’s more friendly you definitely want a domain name that is easy to remember or at least that it is readable so that it sticks more easily.

In our case we typically use custom domain names to differentiate between environments, such as “your-api.yourcompany.dev” or “your-api.yourcompany.staging” and so on. As you can see this are not standard TLD’s. We keep all of our API’s internally so that’s why we can work like this, I’m aware it might not be the case for you. With that said, we wanted to have friendlier DNS names for our API’s and we wanted them to be created through the Serverless Framework.

Serverless Domain Manager

Serverless Domain Manager is a Serverless Framework plugin for managing custom domains in AWS. It makes it much easier as you can define your API gateway domain within your serverless.yml file. It also gives you the possibility of set other options that are part of the domain creation, you can read more about it in the documentation.

Creating the Certificates

API gateway enforces HTTPS, which means that if you want to create a custom domain you have to also create a SSL Certificate that is valid for the domain that you want to create, and you will also have to create a CA (Certificate Authority). For this we are going to use the following Terraform script:

This is the locals that we will use for the whole tutorial, we will not use all of them for this first piece of the CA.

locals {

private_key_algorithm = "RSA"

private_key_rsa_bits = "2047"

private_key_ecdsa_curve = "P256"

ca_common_name = "your-company.dev"

ca_organization_name = "Your Company Development"

dns_names = [

"your-api-gateway.your-company.dev"

]

}

And this is where we create the Certificate Authority:

resource "tls_private_key" "ca" {

algorithm = local.private_key_algorithm

ecdsa_curve = local.private_key_ecdsa_curve

rsa_bits = local.private_key_rsa_bits

} resource "tls_self_signed_cert" "ca" {

key_algorithm = tls_private_key.ca.algorithm

private_key_pem = tls_private_key.ca.private_key_pem

is_ca_certificate = true validity_period_hours = 26280

allowed_uses = [

"cert_signing",

"key_encipherment",

"digital_signature",

] subject {

common_name = local.ca_common_name

organization = local.ca_organization_name

} }

Now that we have the Certificate Authority (CA) we can generate our certificates using this authority. The reason why we are using a CA is because then you can trust your CA in yours server to remove any self-signed cert warning. By trusting your CA you automatically trust all of the certificates generated based on the CA which is better for security and makes maintenance easier also.

resource "tls_private_key" "cert" {

algorithm = local.private_key_algorithm

ecdsa_curve = local.private_key_ecdsa_curve

rsa_bits = local.private_key_rsa_bits } resource "tls_cert_request" "cert" {

key_algorithm = "${tls_private_key.cert.algorithm}"

private_key_pem = "${tls_private_key.cert.private_key_pem}" dns_names = local.dns_names subject {

common_name = local.common_name

organization = local.organization_name

}

} resource "tls_locally_signed_cert" "cert" {

cert_request_pem = "${tls_cert_request.cert.cert_request_pem}" ca_key_algorithm = "${tls_private_key.ca.algorithm}"

ca_private_key_pem = "${tls_private_key.ca.private_key_pem}"

ca_cert_pem = "${tls_self_signed_cert.ca.cert_pem}" validity_period_hours = "87600"

allowed_uses = [

"key_encipherment",

"digital_signature",

] }

Getting the Certificate into ACM

Now we need to get the certificate into AWS ACM so that we can use it in our API Gateway.

The Certificate Chain

Now there is a tricky part in getting the certificate into ACM: You have to provide the certificate chain and currently Terraform doesn’t have a straightforward way to get it. However if you are familiar enough with TLS you will know that the certificate chain is simply your CA’s PEM and your Certificate’s PEM appended together in a text file, so we can generate simply by doing this:

resource "aws_acm_certificate" "pricing-gateway-apigateway-cert" {

private_key = tls_private_key.cert.private_key_pem

certificate_body = tls_locally_signed_cert.cert.cert_pem

certificate_chain = <<-EOT

${tls_self_signed_cert.ca.cert_pem}

${tls_locally_signed_cert.cert.cert_pem}

EOT

tags = {

Name = "self-signed-cert generated by terraform "

} }

Notice that the certificate chain we are passing are the PEM’s of our CA and our Cert joined in a string.

Lastly we will need the ARN of our certificate to use in the Serverless Framework configuration so we need to add an output:

output "certificate_arn" {

description = "Certificate ARN"

value = aws_acm_certificate.acm-cert.arn

}

Adding the Certificate to your serverless.yml File

Now that we have the certificate we can set it up on our serverless.yml file. First you will need to setup the serverless domain manager plugin, please refer to its documentation.

After setting up the plugin you should have a “customDomain” section in your serverless.yml. This is how it will look with the certificate configured:

customDomain:

domainName: your-api-gateway.your-company.dev

basePath: '' # Adjust this to your needs

stage: ${self:provider.stage}

createRoute53Record: true # Adjust this to your needs

certificateArn: <Your Certificate ARN output from the Terraform script>

endpointType: 'regional' # Adjust this to your needs

hostedZoneId: <Your Hosted Zone ID>

hostedZonePrivate: true # Adjust this to your needs

A few things…