DNS Challenge on Google CloudDNS

Configure cert-manager with Google CloudDNS dns-01 challenge for Let's Encrypt certs

If your cluster isn't accessible publicly you can leverage DNS validation with Let's Encrypt.
This documentation is based on https://cert-manager.io/docs/configuration/acme/dns01/google/.

Use these instructions for a Hydrolix deployment running k8s cert-manager to acquire a certificate from Let's Encrypt using the DNS challenge when authoritative DNS is hosted on Google CloudDNS.

Prerequisites

To start this guide, you'll need

  • A Hydrolix cluster running k8s cert-manager deployed anywhere
  • A Google CloudDNS Public DNS zone for the Hydrolix cluster hostname
  • Static credentials to a service account that can control the CloudDNS hosted zone

The Hydrolix cluster can be private or publicly visible. Responding to the DNS challenge doesn't require the cluster to be publicly reachable.

Create a service account

Follow the cert-manager Google CloudDNS instructions for creating a service account and generating a key from the service account in the Google Cloud Console.

Retrieve the key.

Store static credentials in cluster

Create a secret and store the key into your Kubernetes cluster:

apiVersion: v1
kind: Secret
metadata:
  name: letsencrypt-production-gclouddns
type: Opaque
stringData:
  api-token: ${REPLACE_WITH_CLOUDDNS_STATIC_CREDENTIALS}

After creating this Secret in yaml file cloudflare-secret.yaml, deploy to your cluster:

kubectl apply -f letsencrypt-production-gclouddns

Create an Issuer CRD

In TLS ecosystem, an issuer is an entity capable of issuing certificates, more commonly, a Certification Authority (CA). The cert-manager software uses an Issuer Custom Resource Definition (CRD)to configure how to interact with any CA.

Create an Issuer CRD describing the Let's Encrypt production CA with the following required elements:

  • name - display name of the issuer or CA
  • server - the ACME server URL of the CA
  • email - email presented to the ACME API
  • solvers - preferred configuration for responding to the ACME challeng

Each solver has slightly different configuration. See configuration examples.

For further detail, see Issuer Configuration.

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt-production-gclouddns
  namespace: ${HDX_KUBERNETES_NAMESPACE}
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: ${HDX_ADMIN_EMAIL}
    privateKeySecretRef:
      name: letsencrypt-production-gclouddns
    solvers:
    - dns01:
        cloudDNS:
          project: ${REPLACE_WITH_GOOGLE_PROJECT_ID}

After creating the Issuer CRD in yaml file issuer-prod-lets-enc-gcloud.yaml, deploy to your cluster:

kubectl apply -f issuer-prod-lets-enc-gcloud.yaml

Create a Certificate CRD

After deploying your certificate Issuer, create a new Certificate which manages the lifetime of certificate contents, secrets, and related status information when interacting with the CA.

The Certificate CRD contains the information required to generate and send a Certificate Signing Request (CSR), and will also store a successfully acquired TLS certificate and its private key in the configured secret.

  • metadata.name and metadata.namespace - the Kubernetes namespace in which the Hydrolix cluster runs
  • spec.issuerRef.name - the name of the Issuer CRD to use for acquiring this certificate
  • commonName - the primary name on the certificate
  • dnsNames - a list of Subject Alternate Names (SANs) to include on the certificate, should always include at least the commonName
  • spec.secretName - where to store the certificate and corresponding TLS private key

Hydrolix requires the certificate to be stored into the secretName: traefik-tls. This is the default location used by the reverse proxy when loading a certificate.

Here's a configuration example:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: ${HDX_KUBERNETES_NAMESPACE}$YOURNAMESPACE - TO BE REPLACE
  namespace: ${HDX_KUBERNETES_NAMESPACE}$YOURNAMESPACE - TO BE REPLACE
spec:
  secretName: traefik-tls
  issuerRef:
    name: letsencrypt-production-gclouddns
  commonName: ${myhost}.hydrolix.live
  dnsNames:
  - ${myhost}.hydrolix.live

After creating this Certificate CRD in yaml file cert-req.yaml, deploy to your cluster:

kubectl apply -f cert-req.yaml

Check the certificate status

Once applied, you can check the certificate status with the following command:

kubectl describe certificate ${HDX_KUBERNETES_NAMESPACE}

If the CA can validate ownership, you can should see the following:

Normal  Issuing    12s   cert-manager-certificates-issuing          The certificate has been successfully issued

Enable TLS

Once the certificate is deployed, enable TLS for network services by changing the protocol in the hydrolix_url in your Hydrolix spec from http to https:

hydrolix_url: https://${myhost}.hydrolix.live

After changing the protocol, traefik should restart and use the new certificate.

See also Enable TLS.