Configuring the Kubernetes backend¶

The Kubernetes backend uses the API server to store domain and zone information using a Custom Resource Definition. To use the Kubernetes backend, DNS4ACME must be compiled with the kubernetes build tag (enabled for our binary packages).

Note

The Kubernetes backend is not related to installing on Kubernetes. You can use the Kubernetes backend without running DNS4ACME on Kubernetes and vice versa.

Deploying the CRD¶

DNS4ACME doesn't automatically deploy its CustomResourceDefinition, you will have to do this manually. Please deploy the following CRD:

crd.yml

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: domains.dns4acme.github.io
  namespace: dns4acme
spec:
  group: dns4acme.github.io
  names:
    kind: Domain
    listKind: DomainList
    plural: domains
    singular: domain
  scope: Namespaced
  versions:
    - name: v1
      schema:
        openAPIV3Schema:
          type: object
          required:
            - spec
          properties:
            spec:
              type: object
              required:
                - update_key
                - serial
              properties:
                update_key:
                  title: "DNS update key"
                  description: "Base64-encoded key to authenticate updates. This must be at least as long as the chosen HMAC method requires (43 characters for SHA256, 86 characters for SHA512)."
                  type: string
                  format: byte
                serial:
                  title: "Serial"
                  description: "A non-negative serial number for the zone. DNS4ACME increments this number automatically every time the challenge list changes."
                  type: integer
                  format: int64
                  minimum: 0
                acme_challenge_answers:
                  title: "ACME challenge answers"
                  description: "The answers stored for the ACME challenges. DNS4ACME automatically updates this field automatically."
                  type: array
                  items:
                    type: string
      served: true
      storage: true

Creating credentials for DNS4ACME¶

The next step is to create a role, role binding and service account for DNS4ACME. If you are deploying in-cluster, your procedure may be different depending on your cluster configuration.

First, the role:

role.yml

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: dns4acme
  name: dns4acme
rules:
  - apiGroups: ["dns4acme.github.io"]
    resources: ["domains"]
    verbs: ["*"]

Then the service account:

service_account.yml

apiVersion: v1
kind: ServiceAccount
metadata:
  name: dns4acme
  namespace: dns4acme
# Change this to true for in-cluster operations:
automountServiceAccountToken: false

Finally, the role binding:

role_binding.yml

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: dns4acme
  namespace: dns4acme # Customize this namespace
subjects:
  - kind: ServiceAccount
    name: dns4acme
    namespace: dns4acme
roleRef:
  kind: Role
  name: dns4acme
  apiGroup: rbac.authorization.k8s.io

If you are running DNS4ACME outside the cluster, you can now create a token using the following command:

kubectl create token dns4acme

Setting up domains¶

The Kubernetes backend requires you to create an entry for each domain you want DNS4ACME to server. For example:

domain.yml

apiVersion: dns4acme.github.io/v1
kind: Domain
metadata:
  name: example.com
  namespace: dns4acme
spec:
  # Set a strong update key in base64-encoding here:
  update_key: EeheighupumieZ0saya0aedaiV7quaj9
  serial: 0

Configuration options¶

The Kubernetes backend has several configuration options.

CLI option	Environment variable	Default	Description
`--backend`	`DNS4ACME_BACKEND`	-	Set this option to `kubernetes` to use the Kubernetes backend.
`--kubernetes-bearer-token`	`DNS4ACME_KUBERNETES_BEARER_TOKEN`	-	Token used to authenticate to the Kubernetes API.
`--kubernetes-bearer-token-file`	`DNS4ACME_KUBERNETES_BEARER_TOKEN_FILE`	-	File containing the bearer token used to authenticate to the Kubernetes API. Set to `/var/run/secrets/kubernetes.io/serviceaccount/token` for in-cluster authentication.
`--kubernetes-host`	`DNS4ACME_KUBERNETES_HOST`	`kubernetes.default.svc`	Host name for the Kubernetes cluster API server.
`--kubernetes-server-name`	`DNS4ACME_KUBERNETES_SERVER_NAME`	-	SNI name to pass to the Kubernetes API server.
`--kubernetes-base-path`	`DNS4ACME_KUBERNETES_BASE_PATH`	`/`	Base path for the API endpoint
`--kubernetes-namespace`	`DNS4ACME_KUBERNETES_NAMESPACE`	`default`	Namespace to look for content in.
`--kubernetes-cacert`	`DNS4ACME_KUBERNETES_CACERT`	-	PEM-encoded Certificate Authority to verify the connection to the Kubernetes API.
`--kubernetes-cacert-file`	`DNS4ACME_KUBERNETES_CACERT_FILE`	-	File containing the PEM-encoded CA certificate to verify the connection to the Kubernetes API. Set to `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt` for in-cluster operation.
`--kubernetes-cert`	`DNS4ACME_KUBERNETES_CERT`	-	PEM-encoded client certificate to use for authenticating to the Kubernetes API.
`--kubernetes-cert-file`	`DNS4ACME_KUBERNETES_CERT_FILE`	-	File containing the PEM-encoded client certificate to use for authenticating to the Kubernetes API.
`--kubernetes-key`	`DNS4ACME_KUBERNETES_KEY`	-	PEM-encoded client private key to use for authenticating to the Kubernetes API.
`--kubernetes-key-file`	`DNS4ACME_KUBERNETES_KEY_FILE`	-	File containing the PEM-encoded client private key to use for authenticating to the Kubernetes API.
`--kubernetes-username`	`DNS4ACME_KUBERNETES_USERNAME`	-	Username for authenticating to the Kubernetes API.
`--kubernetes-password`	`DNS4ACME_KUBERNETES_PASSWORD`	-	Password for authenticating to the Kubernetes API.
`--kubernetes-qps`	`DNS4ACME_KUBERNETES_QPS`	`5`	Maximum QPS to use for Kubernetes API requests.
`--kubernetes-burst`	`DNS4ACME_KUBERNETES_BURST`	`10`	Maximum burst to use for Kubernetes API requests.
`--kubernetes-timeout`	`DNS4ACME_KUBERNETES_TIMEOUT`	`5s`	Maximum time to wait for a response from the Kubernetes API. Supports adding time qualifiers.