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: zones.dns4acme.github.io
  namespace: dns4acme
spec:
  group: dns4acme.github.io
  names:
    kind: Zone
    listKind: ZoneList
    plural: zones
    singular: zone
  scope: Namespaced
  versions:
    - name: v1
      schema:
        openAPIV3Schema:
          type: object
          required:
            - spec
          properties:
            spec:
              type: object
              required:
                - serial
              properties:
                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
                debug:
                  title: "Debug"
                  description: "Debug log all interactions for this zone. Note: this is extremely verbose, make sure to turn it off once you are done debugging!"
                  type: boolean
                  default: false
      served: true
      storage: true
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: updatekeys.dns4acme.github.io
  namespace: dns4acme
spec:
  group: dns4acme.github.io
  names:
    kind: UpdateKey
    listKind: UpdateKeyList
    plural: updatekeys
    singular: updatekey
  scope: Namespaced
  versions:
    - name: v1
      schema:
        openAPIV3Schema:
          type: object
          required:
            - spec
          properties:
            spec:
              type: object
              required:
                - secretRef
              properties:
                secretRef:
                  type: object
                  required:
                    - name
                    - key
                  properties:
                    name:
                      title: Name
                      description: Name of the secret referenced by this update key.
                      type: string
                    key:
                      title: Key
                      description: Key of the field in the secret referenced. You can use multiple fields in the same secret to manage all of a user's update keys.
                      type: string
      served: true
      storage: true
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: updatekeyzonebindings.dns4acme.github.io
  namespace: dns4acme
spec:
  group: dns4acme.github.io
  names:
    kind: UpdateKeyZoneBinding
    listKind: UpdateKeyZoneBindingList
    plural: updatekeyzonebindings
    singular: updatekeyzonebinding
  scope: Namespaced
  versions:
    - name: v1
      schema:
        openAPIV3Schema:
          type: object
          required:
            - spec
          properties:
            spec:
              type: object
              required:
                - zone
                - updateKey
              properties:
                zone:
                  title: Zone
                  description: Names of the zone the update key applies to.
                  type: string
                updateKey:
                  title: Update key
                  description: Name of the update key that secures this zone.
                  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 zone and update keys¶

The Kubernetes backend requires you to create an entry for each zone and update key you want DNS4ACME to server. For example:

domain.yml

apiVersion: dns4acme.github.io/v1
kind: Zone
metadata:
  name: example.com
  namespace: dns4acme
spec:
  serial: 0
  # Change this to true to turn on (very) verbose logging
  # (requires debug logging to be turned on)
  debug: false
---
apiVersion: v1
kind: Secret
metadata:
  name: example.com
  namespace: dns4acme
data:
  update_key: EeheighupumieZ0saya0aedaiV7quaj9
---
apiVersion: dns4acme.github.io/v1
kind: UpdateKey
metadata:
  name: example.com
  namespace: dns4acme
spec:
  secretRef:
    name: example.com
    key: update_key
---
apiVersion: dns4acme.github.io/v1
kind: UpdateKeyZoneBinding
metadata:
  name: example.com
  namespace: dns4acme
spec:
  zone: example.com
  updateKey: example.com

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.