Setting up certificates with AWS ACM
This guide will walk you through the process of setting certificates issued by or imported into Amazon Certificate Manager.
Requirements
Before you start, make sure you have the following CLI installed in your machine:
aws>= 2.15 (AWS CLI installation guide)
You also need the Load Balancer Controller in your Kubernetes cluster. If it isn't installed yet, create the Load Balancer Controller IAM Role and deploy the Load Balancer Controller to your Kubernetes cluster.
If you don't install the Load Balancer Controller, set the ALPN policy to HTTP2Preferred in the AWS NLB TLS listener on port 443.
Setting up environment variables
The following environment variables help you script the certificate configuration.
The Okteto Domain of your Okteto installation:
export OKTETO_DOMAIN="<<your-okteto-domain>>"
Your AWS Region:
export AWS_REGION="$(aws configure get region)"
Disable AWS CLI pagination (optional):
export AWS_PAGER=""
Create an AWS Route 53 DNS Zone
Okteto uses a DNS zone for both its internal endpoints (e.g., registry, kubernetes, buildkit) and also your application endpoints. Create a DNS zone with the following command:
aws route53 create-hosted-zone \
--name="${OKTETO_DOMAIN}" \
--caller-reference="$(date +%s)"
From the output, note the following properties:
HostedZone.Id: set it as the value of the following environment variable:
export HOSTED_ZONE_ID="<<your-hosted-zone-id>>"
DelegationSet.Nameservers[]: use them to delegate the DNS zone from your domain's nameservers.
You can retrieve your DNS zone's nameservers again with the following command:
aws route53 get-hosted-zone --id="${HOSTED_ZONE_ID}"
Request a Certificate Using AWS ACM with DNS Validation
Okteto requires a wildcard certificate that matches its DNS zone. Request a certificate with the following command:
aws acm request-certificate \
--domain-name="*.${OKTETO_DOMAIN}" \
--validation-method="DNS" \
--region="${AWS_REGION}"
From the output, note the following property:
CertificateArn: it identifies the certificate in integrated AWS services.
export CERTIFICATE_ARN="<<your-certificate-arn>>"
Publish the Validation Records to the DNS Zone
Before you continue, make sure the DNS zone you created is authoritative and correctly delegated from your main domain.
Get the validation records with the following command:
aws acm describe-certificate \
--certificate-arn="${CERTIFICATE_ARN}" \
--region="${AWS_REGION}" \
--query='Certificate.DomainValidationOptions[0].ResourceRecord'
Create a change batch file and replace the highlighted values:
{
"Comment": "Add the CNAME record that validates the ACM certificate",
"Changes": [
{
"Action": "CREATE",
"ResourceRecordSet": {
"Name": "REPLACE ME WITH RESOURCE RECORD NAME",
"Type": "CNAME",
"TTL": 300,
"ResourceRecords": [
{
"Value": "REPLACE ME WITH RESOURCE RECORD VALUE"
}
]
}
}
]
}
Publish the validation records:
aws route53 change-resource-record-sets \
--hosted-zone-id="${HOSTED_ZONE_ID}" \
--change-batch=file://resource-record.json
Watch the status of the validation:
aws acm describe-certificate \
--certificate-arn="${CERTIFICATE_ARN}" \
--region="${AWS_REGION}" \
--query='Certificate.DomainValidationOptions[0].ValidationStatus'
The status changes from PENDING_VALIDATION to SUCCESS when the validation completes.
You can wait until your certificate is validated with the following command:
aws acm wait certificate-validated \
--certificate-arn="${CERTIFICATE_ARN}" \
--region="${AWS_REGION}"
The command polls the AWS API every 60 seconds and exits with code 255 after 40 failed attempts.
Configure Okteto to use your ACM Certificate
Add the following snippet to your Okteto Helm configuration file and replace the highlighted value:
ingress-nginx:
controller:
service:
annotations:
service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "ssl"
service.beta.kubernetes.io/aws-load-balancer-ssl-cert: "<<your-certificate-arn>>"
service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "https"
service.beta.kubernetes.io/aws-load-balancer-scheme: "internet-facing"
service.beta.kubernetes.io/aws-load-balancer-alpn-policy: "HTTP2Preferred"
Upgrade your Okteto instance to apply the new configuration. Upgrade to the same version you already run: it keeps the changes to a minimum and makes any issue easier to troubleshoot.
If you didn't install the Load Balancer Controller, set the ALPN policy to HTTP2Preferred in the AWS NLB TLS listener on port 443.
The AWS documentation explains how to do it from the console or the AWS CLI.