Installing cert-manager with the Yandex Cloud DNS ACME webhook plugin

cert-manager is an application that adds certificates and certificate issuers as resource types in Managed Service for Kubernetes clusters to facilitate obtaining, renewal, and use of such certificates. For example, to get Let's Encrypt® certificates, you can pass the following challenges to prove domain ownership:

• DNS-01. To pass this challenge, use Yandex Cloud DNS. Together with cert-manager, you need to install the ACME webhook Yandex Cloud DNS plugin for integration with the service.
• HTTP-01. To pass this challenge, use an Ingress controller installed in a cluster.

Getting startedGetting started

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

   The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

2. Make sure that the Managed Service for Kubernetes cluster is located in the same folder as the Cloud DNS public zone.

3. Make sure that the security groups for the Managed Service for Kubernetes cluster and its node groups are configured correctly. If any rule is missing, add it.

   Warning

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

4. Install kubect and configure it to work with the new cluster.

5. Create a service account to run cert-manager.

6. Assign the service account the dns.editor role for the folder hosting the public DNS zone.

7. Create an authorized key for the service account and save it to the key.json file.

Installation using Yandex Cloud MarketplaceInstallation using Yandex Cloud Marketplace

1. Navigate to the folder dashboard and select Managed Service for Kubernetes.
2. Click the name of the Managed Service for Kubernetes cluster you need and select the Marketplace tab.
3. Under Application available for installation, select the cert-manager app with the Yandex Cloud DNS ACME webhook plugin and click Go to install.
4. Configure the application:
   • Namespace: Create a new namespace, e.g., cert-manager-dns-space. If you leave the default namespace, cert-manager with the Yandex Cloud DNS plugin may work incorrectly.
   • Application name: Specify the app name, e.g., cert-manager.
   • Service account key: Paste the contents of the key.json file or create a new key.
   • Folder ID: Specify the ID of the folder hosting the Cloud DNS zone, to confirm domain ownership at the DNS-01 challenge.
   • Email address to get notifications from Let's Encrypt: Specify the email address for Let's Encrypt® notifications.
   • Let's Encrypt server address: Select a Let's Encrypt® server address from the list:
     • https://acme-v02.api.letsencrypt.org/directory: Primary URL.
     • https://acme-staging-v02.api.letsencrypt.org/directory: Test URL.
5. Click Install.
6. Wait for the application to change its status to Deployed.

Installation using a Helm chartInstallation using a Helm chart

1. Install Helm v3.8.0 or higher.

2. Install kubect and configure it to work with the new cluster.

3. To install a Helm chart with cert_manager and the Yandex Cloud DNS plugin, run this command:

   helm pull oci://cr.yandex/yc-marketplace/yandex-cloud/cert-manager-webhook-yandex/cert-manager-webhook-yandex \
     --version 1.0.8-1 \
     --untar && \
   helm install \
     --namespace <namespace> \
     --create-namespace \
     --set-file config.auth.json=key.json \
     --set config.email='<email_address_for_notifications_from_Lets_Encrypt>' \
     --set config.folder_id='<ID_of_folder_with_Cloud_DNS_zone>' \
     --set config.server='Lets_Encrypt_server_URL' \
     cert-manager-webhook-yandex ./cert-manager-webhook-yandex/
   

   As a Let's Encrypt® server URL, use:

   • https://acme-v02.api.letsencrypt.org/directory: Primary URL.
   • https://acme-staging-v02.api.letsencrypt.org/directory: Test URL.

   This command also creates a new namespace required for cert-manager.

   If you set namespace to the default namespace, cert-manager may work incorrectly. We recommend you to specify a value different from all existing namespaces (e.g., cert-manager-dns-space).

   Note

   If you are using a Helm version below 3.8.0, append the export HELM_EXPERIMENTAL_OCI=1 && \ string to the command to enable Open Container Initiative (OCI) support in the Helm client.

4. Make sure the cert-manager pod has changed its status to Running:

   kubectl get pods --namespace=<namespace> -l app=cert-manager-webhook-yandex -w
   

Getting a test certificateGetting a test certificate

To test the installed application, get a test certificate. To issue a certificate, we are going to use the yc-clusterissuer issuer. It is created when you install cert-manager and pre-configured to work with Let's Encrypt®.

1. Create a file named certificate.yaml with a request for a test certificate:

   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: domain-name
     namespace: <namespace>
   spec:
     secretName: domain-name-secret
     issuerRef:
       # ClusterIssuer created along with the Yandex Cloud DNS ACME webhook.
       name: yc-clusterissuer
       kind: ClusterIssuer
     dnsNames:
       # The domain must belong to your public Cloud DNS zone.
       # Make sure to specify the domain name, e.g., test.example.com, rather than the DNS record name.
       - <domain_name>
   

2. Install the certificate in the Managed Service for Kubernetes cluster:

   kubectl apply -f certificate.yaml
   

3. Check if the certificate is available:

   kubectl get certificate
   

   Result:

   NAME         READY  SECRET              AGE
   domain-name  True   domain-name-secret  45m
   

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

4. (Optional) Get detailed information about the certificate:

   kubectl -n <namespace> describe certificate domain-name
   

   The command output will contain similar events:

   Events:
     Type    Reason     Age   From                                       Message
     ----    ------     ----  ----                                       -------
     Normal  Issuing    ...   cert-manager-certificates-trigger          Issuing certificate as Secret does not exist
     Normal  Generated  ...   cert-manager-certificates-key-manager      Stored new private key in temporary Secret resource...
   

   Certificates are used bundled with related Kubernetes secrets, which store key pairs and service information. If there is no secret, the certificate is reissued automatically and a new secret is created – with a notification in the events. For more information on what can cause the reissue of a certificate, see the cert-manager documentation.

   As the certificate is being issued for the first time, it has no such related secret so far. The presence of notification events about the fact should not be considered an error.

Use casesUse cases

• DNS Challenge for Let's Encrypt® certificates
• Installing an NGINX Ingress controller with a Let's Encrypt® certificate manager

See alsoSee also

• Let's Encrypt® documentation
• cert-manager documentation