Installing cert-manager with the Yandex Cloud DNS ACME webhook plugin
cert-manager
- 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.
Note
The cert-manager app with the Yandex Cloud DNS ACME webhook plugin supports Wildcard certificates
Getting started
-
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the
--folder-name
or--folder-id
parameter. -
Make sure that the Managed Service for Kubernetes cluster is located in the same folder as the Cloud DNS public zone.
-
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.
-
Install kubectl
and configure it to work with the created cluster. -
Create a service account to run cert-manager.
-
Assign the service account the
dns.editor
role for the folder hosting the public DNS zone. -
Create an authorized key for the service account and save it to the
key.json
file.
Installation using Yandex Cloud Marketplace
- Go to the folder page
and select Managed Service for Kubernetes. - Click the name of the Managed Service for Kubernetes cluster you need and select the
Marketplace tab. - Under Application available for installation, select the cert-manager app with the Yandex Cloud DNS ACME webhook plugin and click Go to install.
- Configure the application:
- Namespace: Select a namespace or create a new one.
- 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.
- Click Install.
- Wait for the application to change its status to
Deployed
.
Installation using a Helm chart
-
Install Helm
v3.8.0 or higher. -
Install kubectl
and configure it to work with the created cluster. -
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.
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. -
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 certificate
To test the installed application, get a test certificate. To issue the 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®.
-
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>
-
Install the certificate in the Managed Service for Kubernetes cluster:
kubectl apply -f certificate.yaml
-
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 theREADY
column means that the certificate was issued successfully. -
(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 cases
- Checking DNS Challenge for Let's Encrypt® certificates
- Installing an NGINX Ingress controller with a Let's Encrypt® certificate manager