Skip to main content
Version: 1.47

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:

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.

note

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.
tip

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​

warning

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:

resource-record.json
{
"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.

tip

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:

config.yaml
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.

note

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.