Contact UsGet started

Creating an ACME resolver webhook for responses to DNS01 checks

Written by
Updated at September 24, 2024

To pass checks for domain rights automatically using the cert-manager utility, add a webhook with a DNS01 resolver to the utility configuration.

Below, we have an example of creating a ClusterIssuer object with a DNS01 resolver webhook for a domain registered in Yandex Cloud DNS.

To run a webhook in a Managed Service for Kubernetes cluster:

  1. Set up the Managed Service for Kubernetes cluster.
  2. Install the latest version of the certificate manager.
  3. Install the Helm package manager.
  4. Install and run a webhook in a Managed Service for Kubernetes cluster.
  5. Delete the resources you created.

Note

The certificate manager with the ACME webhook for Yandex Cloud DNS supports Wildcard certificates.

Getting started

Sign up for Yandex Cloud and create a billing account:

  1. Go to the management console and log in to Yandex Cloud or create an account if you do not have one yet.
  2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one.

If you have an active billing account, you can go to the cloud page to create or select a folder for your infrastructure to operate in.

Learn more about clouds and folders.

Prepare the environment

  1. If you do not have the Yandex Cloud command line interface yet, install and initialize it.

  2. Install kubectl, which is the command line interface for Kubernetes.

  3. Make sure you have enough resources available in the cloud.

  4. If you do not have a network yet, create one.

  5. If you do not have any subnets yet, create them in the availability zones where your Managed Service for Kubernetes cluster and node group will be created.

  6. Create service accounts:

    • sa-kubernetes with the following roles:

      • k8s.clusters.agent and vpc.publicAdmin for the folder where the Managed Service for Kubernetes is created.
      • container-registry.images.puller for the folder containing a Docker image registry.

      On behalf of this service account, resources your cluster needs will be created and Managed Service for Kubernetes nodes will pull the required Docker images from the registry.

    • sa-dns-editor with the dns.editor role for the folder containing the public zone. This service account will be used to create DNS resource records.

Prepare your Managed Service for Kubernetes cluster

Create a Managed Service for Kubernetes cluster

To create a Managed Service for Kubernetes cluster:

  1. In the management console, select the folder where you want to create a Managed Service for Kubernetes cluster.
  2. Select Managed Service for Kubernetes.
  3. Click Create cluster.
  4. Enter the name for the cluster: kubernetes-cluster-wh.
  5. Service account for resources: Specify the sa-kubernetes service account that will be used to create resources.
  6. Service account for nodes: Specify the sa-kubernetes service account the Managed Service for Kubernetes nodes will use to access the Docker image registry.
  7. Specify a release channel. You will not be able to edit this setting once you create a Managed Service for Kubernetes cluster.
  8. Under Master configuration:
    • Kubernetes version: Select a Kubernetes version to install on the Managed Service for Kubernetes master. It must match the Kubernetes command line version.
    • Public address: Select the IP address assignment method:
      • Auto: Assign a random IP address from the Yandex Cloud IP pool.
    • Type of master: Select the master type:
      • Zonal: To create a single master host in the selected availability zone. Specify a cloud network and select a subnet for the master host.
      • Regional: To create a single master host in each availability zone. Specify a cloud network and subnet for each availability zone.
    • Select security groups for the Managed Service for Kubernetes cluster's network traffic.
  9. Under Cluster network settings:
    • CIDR cluster: Specify an IP range to allocate addresses to pods from.
    • CIDR services: Specify an IP range to allocate IP addresses to services from.
    • Set the Managed Service for Kubernetes node subnet mask and the maximum number of pods per node.
  10. Click Create.
  11. Wait for the cluster status to change to Running and its state to Healthy.

Add credentials to the kubectl configuration file

To add Managed Service for Kubernetes cluster credentials to the kubectl configuration file:

  1. Run this command:

    yc managed-kubernetes cluster get-credentials kubernetes-cluster-wh --external

    By default, credentials are added to the $HOME/.kube/config directory. If you need to change the configuration location, use --kubeconfig <file_path>.

  2. Check the kubectl configuration after adding the credentials:

    kubectl config view

    Result:

    apiVersion: v1
clusters:
  - cluster:
    certificate-authority-data: DATA+OMITTED
...

Create a node group

To create a Managed Service for Kubernetes node group:

  1. In the management console, select the folder where the required Managed Service for Kubernetes cluster was created.

  2. In the list of services, select Managed Service for Kubernetes.

  3. Select the kubernetes-cluster-wh cluster.

  4. On the cluster page, go to Nodes manager.

  5. Click Create a node group.

  6. Enter a name and description for the Managed Service for Kubernetes node group.

  7. In the Kubernetes version field, select a Kubernetes version for Managed Service for Kubernetes nodes.

  8. Under Scaling, select its type:

    • Fixed, to keep the number of nodes in the Managed Service for Kubernetes group constant. Specify the number of nodes in the Managed Service for Kubernetes group.
    • Automatic, to control the number of nodes in the Managed Service for Kubernetes group via Managed Service for Kubernetes cluster autoscaling.

  9. Under Allow when creating and updating, specify the maximum number of instances by which you can exceed or reduce the size of the Managed Service for Kubernetes group.

  10. Under Computing resources:

  11. Under Storage:

    • Specify the Disk type for the Managed Service for Kubernetes group nodes:

      • HDD: Standard network drive; network block storage on an HDD.
      • SSD: Fast network drive; network block storage on an SSD.
      • Non-replicated SSD: Network drive with enhanced performance achieved by removing redundancy. You can only change the size of this type of disk in 93 GB increments.
      • SSD IO: Network drive with the same performance characteristics as Non-replicated SSD, plus redundancy. You can only change the size of this type of disk in 93 GB increments.

      For more information about disk types, see the Yandex Compute Cloud documentation.

    • Specify the disk size for the Managed Service for Kubernetes group nodes.

  12. Under Network settings:

    • In the Public address field, choose a method for IP address assignment:
      • Auto: Assign a random IP address from the Yandex Cloud IP pool.
    • Select security groups.
    • Select an availability zone and subnet to deploy the Managed Service for Kubernetes group nodes in.

  13. Under Access, specify the information required to access the Managed Service for Kubernetes group nodes over SSH:

    • Login: Enter the username.
    • SSH key: Insert the contents of the public key file.

  14. Click Create.

  15. Wait for the node group status to change to Running.

Install the latest version of the certificate manager

  1. Install the latest version of the certificate manager configured to issue Let's Encrypt certificates. For example, run the following command for version 1.21.1:

    kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.12.1/cert-manager.yaml

  2. Make sure that the cert-manager namespace has three pods, all of them being 1/1 ready and with the Running status:

    kubectl get pods -n cert-manager --watch

    Result:

    NAME                                      READY  STATUS   RESTARTS  AGE
cert-manager-69********-ghw6s             1/1    Running  0         54s
cert-manager-cainjector-76********-gnrzz  1/1    Running  0         55s
cert-manager-webhook-77********-wz9bh     1/1    Running  0         54s

Install the Helm package manager

Install Helm to manage packages on your Kubernetes cluster.

Install and run a webhook in a Managed Service for Kubernetes cluster

Install a webhook

  1. Clone the webhook's repository:

    git clone https://github.com/yandex-cloud/cert-manager-webhook-yandex.git

  2. Install the webhook using Helm:

    helm install -n cert-manager yandex-webhook ./deploy/cert-manager-webhook-yandex

Prepare configuration files

  1. Create an authorized key for the sa-dns-editor service account and save it to the iamkey.json file:

    yc iam key create iamkey \
  --service-account-id=<service_account_ID> \
  --format=json \
  --output=iamkey.json

  2. Create a secret with the key of the service account:

    kubectl create secret generic cert-manager-secret --from-file=iamkey.json -n cert-manager

  3. Create the cluster-issuer.yml file with the ClusterIssuer object manifest:

    apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
 name: clusterissuer
 namespace: default
spec:
 acme:
  # You must replace this email address with your own.
  # Let's Encrypt will use this to contact you about expiring
  # certificates, and issues related to your account.
  email: your@email.com
  server: https://acme-v02.api.letsencrypt.org/directory
  privateKeySecretRef:
   # Secret resource that will be used to store the account's private key.
   name: secret-ref
  solvers:
   - dns01:
      webhook:
        config:
          # ID of the folder the dns-zone is located in
          folder: <folder_ID>
          # This is the secret used to access the service account
          serviceAccountSecretRef:
            name: cert-manager-secret
            key: iamkey.json
        groupName: acme.cloud.yandex.com
        solverName: yandex-cloud-dns

  4. Create the cluster-certificate.yml file with the Certificate object manifest:

    apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
 name: your-site-com
 namespace: default
spec:
 secretName: example-com-secret
 issuerRef:
  # The issuer created previously
  name: clusterissuer
  kind: ClusterIssuer
 dnsNames:
   - your-site.com

Run the certificate manager with the webhook

  1. Create objects in a Kubernetes cluster:

    kubectl apply -f cluster-issuer.yml && \
kubectl apply -f cluster-certificate.yml

  2. Check that the webhook is running:

    kubectl get pods -n cert-manager --watch

    Make sure the records contain the ACME webhook for Yandex Cloud DNS:

    NAME                                                         READY   STATUS    RESTARTS   AGE
... 
yandex-webhook-cert-manager-webhook-yandex-5578cfb98-tw4mq   1/1     Running   1          43h

Delete the resources you created

If you no longer need the resources you created, delete the Managed Service for Kubernetes cluster.

Previous
Checking DNS Challenge for Let's Encrypt® certificates
Next
Backups in Object Storage