Creating an ACME resolver webhook for responses to DNS01 checks

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.

Getting startedGetting started

Sign up for Yandex Cloud and create a billing account:

1. Navigate to the management console and log in to Yandex Cloud or create a new account.
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 and link a cloud to it.

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

Learn more about clouds and folders here.

Required paid resourcesRequired paid resources

The support cost includes:

• Fee for using the master and outgoing traffic in a Managed Service for Kubernetes cluster (see Managed Service for Kubernetes pricing).
• Fee for using computing resources, OS, and storage in cluster nodes (VMs) (see Compute Cloud pricing).
• Fee for a public IP address for the cluster nodes (see Virtual Private Cloud pricing).

Set up your environmentSet up your environment

1. If you do not have the Yandex Cloud CLI installed 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 you will create your Managed Service for Kubernetes cluster and node group.

6. Create service accounts:

   • sa-kubernetes with the following roles:

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

     This service account will be used to create the resources your cluster needs, 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.

7. Create security groups for the Managed Service for Kubernetes cluster and its node groups.

   Warning

   The configuration of security groups determines the performance and availability of the cluster and the services and applications running in it.

8. Add the following rules to the security group applied to the node group:

   • Rule for inbound traffic to allow certificate checking via a cert-manager webhook:
     • Port range: 10250.
     • Protocol: TCP.
     • Destination name: CIDR.
     • CIDR blocks: 0.0.0.0/0.
   • Rule for outbound traffic to allow connection to Let's Encrypt® servers for issuing certificates:
     • Port range: 443.
     • Protocol: TCP.
     • Destination name: CIDR.
     • CIDR blocks: 0.0.0.0/0.

Prepare your Managed Service for Kubernetes clusterPrepare your Managed Service for Kubernetes cluster

Create a Managed Service for Kubernetes clusterCreate a Managed Service for Kubernetes cluster

To create a Managed Service for Kubernetes cluster:

Add credentials to the configuration fileAdd credentials to the kubectl configuration file

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

Create a node groupCreate a node group

To create a Managed Service for Kubernetes node group:

Install the latest version of the certificate managerInstall 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 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 managerInstall the Helm package manager

Install Helm to manage packages on your Kubernetes cluster.

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

Install a webhookInstall a webhook

1. Clone the webhook 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 filesPrepare 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 service account key:

   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:
             # The ID of the folder where dns-zone 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 webhookRun 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. Make sure 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
   

If you have an error and need help, contact support.

Delete the resources you createdDelete the resources you created

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