Creating an ACME resolver webhook for responses to DNS01 challenges

Install the cert-manager application with the DNS01 webhook resolver to automatically pass domain ownership checks for domains 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 and run a webhook in a Managed Service for Kubernetes cluster.
3. Test the webhook.
4. 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 for this solution 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 the new Managed Service for Kubernetes cluster and node group will reside.

6. Create these 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 performance and availability of the cluster and the services and applications running in it.

8. Add the following rules to your security groups:

   • Add to the cluster security group an outbound traffic rule allowing certificate checks via a cert-manager webhook:
     • Port range: 10250.
     • Protocol: TCP.
     • Destination name: CIDR.
     • CIDR blocks: 0.0.0.0/0.
   • Add to the node group security group an outbound traffic rule allowing connection to Let's Encrypt® servers for 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

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

Create a node groupCreate a node group

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

1. Clone the webhook repository with the certificate manager configured to issue Let's Encrypt certificates:

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

2. Install Helm to manage packages in your Kubernetes cluster.

3. Install the webhook using Helm:

   helm install \
     --namespace cert-manager \
     --create-namespace \
     yandex-webhook ./cert-manager-webhook-yandex/deploy/cert-manager-webhook-yandex
   

4. 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-55********-tw4mq   1/1     Running   1          43m
   

Test the webhookTest the webhook

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 that uses the DNS01 webhook resolver for the Cloud DNS domain:

   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
    name: clusterissuer
    namespace: default
   spec:
    acme:
     email: <email_address_for_notifications_from_Lets_Encrypt>
     server: https://acme-v02.api.letsencrypt.org/directory
     privateKeySecretRef:
      name: secret-ref
     solvers:
      - dns01:
         webhook:
           config:
             folder: <ID_of_folder_with_public_zone>
             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
    namespace: default
   spec:
    secretName: your-site-secret
    issuerRef:
     name: clusterissuer
     kind: ClusterIssuer
    dnsNames:
      - <domain_name>
   

Issue a certificate using the webhookIssue a certificate using the webhook

1. Create the objects in the Kubernetes cluster:

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

2. Check the certificate status:

   kubectl get certificate
   

   Result:

   NAME        READY  SECRET            AGE
   your-site   True   your-site-secret  45m
   

   The True status in the READY column means that the certificate was issued successfully.

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.