Renew TLS certificates on Astronomer Software

After you set up a transport layer security (TLS) certificate for Astronomer, you’ll need to establish a process for periodically renewing the certificate. The following methods are available for certificate renewal:

• Automatic renewal: Let’s Encrypt provides a service that automatically renews your TLS certificate every 90 days. Astronomer recommends this option for smaller organizations where the DNS administrator and cluster administrator are either the same person or on the same team.
• Manual renewal: Manual renewal works similarly to the initial certificate creation process, except that you replace your existing certificate by creating a new certificate. Astronomer recommends this method for large organizations that have their own processes for issuing certificates.

1
sudo certbot certonly --manual --preferred-challenges=dns -d -d *. --key-type=rsa

Automatically renew TLS certificates Using Let’s Encrypt

Let’s Encrypt is a certificate authority that provides free, 90-day certificates using the ACME protocol. You can use the Cert Manager project for Kubernetes to automatically renew certificates. When you renew a TLS certificate with Let’s Encrypt, you must specify the RSA key type to sign certificates or your deploys will fail and error messages will appear in the registry and Houston logs.

1. Install the Kubernetes Cert Manager by following the official installation guide.

2. If you’re running Astronomer on AWS, grant your nodes access to Route 53 by adding the following CloudFormation snippet to your nodes’ Instance Profile (if you don’t use AWS, complete whatever setup is necessary to authenticate Cert Manager to your DNS):

   1
   Type: "AWS::IAM::Role"
   2
   Properties:
   3
     RoleName: instance-profile-role
   4
     Policies:
   5
       - PolicyName: instance-profile-policy
   6
         PolicyDocument:
   7
           Version: '2012-10-17'
   8
           Statement:
   9
             - Effect: Allow
   10
               Action: route53:GetChange
   11
               Resource: arn:aws:route53:::change/*
   12
             - Effect: Allow
   13
               Action:
   14
                 - route53:ChangeResourceRecordSets
   15
                 - route53:ListResourceRecordSets
   16
               # Use the second Resource format if you're updating this through the AWS UI
   17
               Resource: !Sub arn:aws:route53:::hostedzone/${HostedZoneIdLookup.HostedZoneId}
   18
             - Effect: Allow
   19
               Action: route53:ListHostedZonesByName
   20
               Resource: '*'
   21
     AssumeRolePolicyDocument:
   22
       Version: "2012-10-17"
   23
       Statement:
   24
         - Effect: "Allow"
   25
           Principal:
   26
             Service:
   27
               - "ec2.amazonaws.com"
   28
           Action:
   29
             - "sts:AssumeRole"

   For more information on how to complete this setup, refer to AWS documentation.

3. Create a “ClusterIssuer” resource that declares how requests for certificates will be fulfilled. To do so, first create a clusterissuer.yaml file with the following values:

   1
   apiVersion: cert-manager.io/v1
   2
   kind: ClusterIssuer
   3
   metadata:
   4
       name: letsencrypt-prod
   5
   spec:
   6
       acme:
   7
           email: <your-email>
   8
           server: https://acme-v02.api.letsencrypt.org/directory
   9
           privateKeySecretRef:
   10
               name: cert-manager-issuer-secret-key
   11
           solvers:
   12
           - selector: {}
   13
             dns01:
   14
                route53:
   15
                   region: <your-server-region>

   Then, create the ClusterIssuer by running the following command:

   1
   kubectl apply -f clusterissuer.yaml -n astronomer

4. Create a Certificate resource that declares the type of certificate you’ll request from Let’s Encrypt. First, create a certificate.yaml file and replace BASE_DOMAIN with your base domain. If you use a third-party ingress-controller, un-comment the secretTemplate section and change the value of the platform-release label to match your Astronomer platform release name:

   1
   apiVersion: cert-manager.io/v1
   2
   kind: Certificate
   3
   metadata:
   4
       name: acme-crt
   5
   spec:
   6
       # if using a third-party ingress controller for Software v0.36 or greater, you can define the secretName to a custom value
   7
       secretName: astronomer-tls
   8
       dnsNames:
   9
           - BASE_DOMAIN
   10
           - app.BASE_DOMAIN
   11
           - deployments.BASE_DOMAIN
   12
           - registry.BASE_DOMAIN
   13
           - houston.BASE_DOMAIN
   14
           - grafana.BASE_DOMAIN
   15
           - kibana.BASE_DOMAIN
   16
           - install.BASE_DOMAIN
   17
           - prometheus.BASE_DOMAIN
   18
           - alertmanager.BASE_DOMAIN
   19
       issuerRef:
   20
           name: letsencrypt-prod
   21
           kind: ClusterIssuer
   22
           group: cert-manager.io
   23
     # If using a third-party ingress controller, uncomment the following section and change
   24
     # the value of platform-release to match your Astronomer platform release name
   25
     # secretTemplate:
   26
     #   annotations:
   27
     #     astronomer.io/commander-sync="platform-release=astronomer"

   Then, create the certificate by running the following command and waiting a few minutes:

   1
   kubectl apply -f certificate.yaml -n astronomer

5. Ensure that the certificate was created by running:

   1
   kubectl get certificates -n astronomer

6. Note your certificate name. You will need it later when you create a Kubernetes TLS secret and push it to your Software configuration. See the Astronomer Software installation guide for the procedure.

Manually renew TLS certificates

Use a manual process to renew TLS certificates when your organization has its own process for requesting and renewing TLS certificates. When you renew a TLS certificate with Let’s Encrypt, you must specify the RSA key type to sign certificates or your deploys will fail and error messages will appear in the registry and Houston logs.

1. Delete your current TLS certificate by running the following command:

   1
   kubectl delete secret astronomer-tls -n astronomer

2. Follow the instructions for requesting a TLS certificate from your organization’s security team as described in Step 7: Request and validate an Astronomer TLS certificate.

3. Restart your Houston, nginx, and registry pods to begin using the new certificate by running the following commands:

   1
   kubectl rollout restart deployments -n astronomer
   2
   kubectl rollout restart statefulsets -n astronomer
   3
   kubectl rollout restart daemonsets -n astronomer