DNS Challenge on Cloudflare

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/cloudflare/.

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

Prerequisites⚓︎

To start this guide, you'll need:

A Hydrolix cluster running k8s cert-manager deployed anywhere
A Cloudflare managed DNS zone for the Hydrolix cluster hostname
The email address of the account owning a Cloudflare API token and the API token itself

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

Create token to alter zone⚓︎

To use Cloudflare, you may use one of two types of tokens. API Tokens allow application-scoped keys bound to specific zones and permissions, while API Keys are globally-scoped keys that carry the same permissions as your account.

API Tokens are recommended for higher security, since they have more restrictive permissions and are more easily revocable.

Tokens can be created at User Profile > API Tokens > API Tokens. The following settings are recommended:

Permissions:
- Zone - DNS -Edit
- Zone - Zone - Read
Zone Resources:
- Include - All Zones

Store API token in cluster⚓︎

Once the token is created, create a secret and store that information into your Kubernetes cluster:

apiVersion: v1
kind: Secret
metadata:
  name: cloudflare-api-token-secret
type: Opaque
stringData:
  api-token: ${REPLACE_WITH_CLOUDFLARE_API_TOKEN}

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

kubectl apply -f cloudflare-secret.yaml

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.

The following example configures the issuer software to use Let's Encrypt, prefer DNS validation, and automate challenge response proof using Cloudflare managed DNS:

issuer-prod-lets-enc-cloudflare.yaml

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt-production-cloudflare
  namespace: ${HDX_KUBERNETES_NAMESPACE}
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: ${HDX_ADMIN_EMAIL}
    privateKeySecretRef:
      name: letsencrypt-production-cloudflare
    solvers:
    - dns01:
        cloudflare:
          email: ${REPLACE_WITH_EMAIL_ID_USED_TO_CREATE_CLOUDFLARE_TOKEN}
          apiTokenSecretRef:
            name: cloudflare-api-token-secret
            key: api-token

Store the configuration in the file issuer-prod-lets-enc-cloudflare.yaml. Use the following command to deploy it to your cluster:

kubectl apply -f issuer-prod-lets-enc-cloudflare.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}
  namespace: ${HDX_KUBERNETES_NAMESPACE}
spec:
  secretName: traefik-tls
  issuerRef:
    name: letsencrypt-production-cloudflare
  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:

1	`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:

hydrolixcluster.yaml

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

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