Teach you how to use cert-manager to issue free certificates

Overview

With the increasing popularity of HTTPS, more and more websites are upgrading from HTTP to HTTPS. To use HTTPS, you need to apply for a certificate from an authority, and you need to pay a certain cost. If there is a large number of requirements, it is also a considerable expense. cert-manager is an all-round certificate management tool on Kubernetes. If the security level and certificate functions are not high, you can use cert-manager to issue free certificates based on the ACME protocol and Let's Encrypt and automatically renew them, realizing permanent free use of certificates.

How cert-manager works

After cert-manager is deployed to the Kubernetes cluster, it will watch the CRD resources it supports. We create CRD resources to instruct cert-manager to issue certificates for us and renew them automatically:

Explain the following key resources:

Issuer/ClusterIssuer: Used to instruct cert-manager in what way to issue certificates. This article mainly explains the ACME way of issuing free certificates. The only difference between ClusterIssuer and Issuer is that Issuer can only be used to issue certificates under its own namespace, and ClusterIssuer can issue certificates under any namespace.
Certificate: Used to tell cert-manager what domain name certificate we want and some configuration needed to issue the certificate, including a reference to Issuer/ClusterIssuer.

Free certificate issuance principle

Let's Encrypt uses the ACME protocol to verify whether the domain name really belongs to you. After the verification is successful, a free certificate can be automatically issued. The certificate is valid for only 90 days. It needs to be verified again before it expires to achieve renewal. Fortunately, cert -manager can be automatically renewed, so that you can use a permanent free certificate. How to verify whether this domain name belongs to you? The two mainstream verification methods are HTTP-01 and DNS-01. For detailed verification principles, please refer to the operation method of Let's Encrypt , which will be briefly described below.

HTTP-01 verification principle

HTTP-01 parity principle is to give you the domain name points to a temporary increase in the HTTP service location, Let's Encrypt http request is sent to http:///.well-known/acme-challenge/, YOUR_DOMAINis to be verified domain name, TOKENfile client ACME placed in charge of protocol, where the client ACME end is cert-manager, it by modifying or creating Ingress rules to increase the temporary path and check points to provide TOKENservices. Let's Encrypt will compare TOKENmeets expectations, it will issue a certificate after successful verification. This method is only suitable for issuing certificates to services that use Ingress to expose traffic, and does not support pan-domain certificates.

DNS-01 verification principle

The verification principle of DNS-01 is to use the API Key of the DNS provider to get your DNS control authority. After Let's Encrypt provides the ACME client with a token, the ACME client (cert-manager) will create the token and TXT record derived from your account key and put that record _acme-challenge.. Let's Encrypt will then query the DNS system for the record, and if a match is found, the certificate can be issued. This method does not require your service to use Ingress, and supports pan-domain certificates.

Comparison of verification methods

The advantages of the HTTP-01 verification method are: the configuration is simple and universal, no matter which DNS provider is used, the same configuration method can be used; the disadvantage is: you need to rely on Ingress, if your service does not use Ingress to expose traffic, it is not applicable, and Does not support pan-domain certificates.

The advantage of DNS-01 verification method is that it has no disadvantages of HTTP-01 verification method, does not rely on Ingress, and supports pan-domain names; the disadvantage is that different DNS providers have different configuration methods, and there are many DNS providers, cert-manager It’s impossible to support all of the Issuer, but there are some services that can be extended to support Issuer by deploying Webhook services that implement cert-manager , such as DNSPod and Ali DNS. For a detailed list of Webhooks, please refer to: https://cert-manager .io/docs/configuration/acme/dns01/#webhook

Which way to choose? Conditions permitting, the suggestion is the best use of DNS-01the way, less restrictive, more whole.

Steps

Install cert-manager

Usually, you can install cert-manager to the cluster directly by one-click using yaml, refer to the official website document Installing with regular manifests .

The official mirror used by cert-manager is available quay.io. Domestic pull may be slow. You can also use the following command to install with one click (use the mirror synchronized to the domestic CCR):

kubectl apply --validate=false -f https://raw.githubusercontent.com/TencentCloudContainerTeam/manifest/master/cert-manager/cert-manager.yaml

! The above command installation method requires that the cluster version is not lower than 1.16.

Configure DNS

Log in to the backend of your DNS provider and configure the DNS A record of the domain name to point to the externally exposed IP address of the back-end service for which you need a certificate. Take cloudflare as an example:

HTTP-01 verification method issuance certificate

If you use HTTP-01 verification, you need to use Ingress to cooperate with the verification. cert-manager by automatically modifying Ingress Ingress rules automatically added to achieve or expose the external HTTP provisional desired path validation, this is the check to the Issuer http01 configuration, the Ingress specified nameor classdistinguished (see example below).

TKE's built-in Ingress is that each Ingress resource corresponds to a CLB. If you use TKE's built-in Ingress to expose services and use HTTP-01 verification, you can only use the method of automatically modifying Ingress, and you cannot automatically add Ingress. , Because the automatically added Ingress will automatically create other CLBs, and the external IP address is inconsistent with the Ingress of our back-end service. When Let’s Encrypt is verified, the temporary path required for verification cannot be found from the Ingress of our service. The verification failed and the certificate could not be issued. If you use a self Ingress, such as the deployment of Nginx Ingress on the TKE , the same Ingress class of Ingress share the same CLB, so that you can use to automatically add Ingress way.

Some examples are given below.

If your service uses TKE service comes with Ingress exposed, not suitable for administration to issue a certificate for free with cert-manager, because the certificate is to be uploaded to the certificate management to refer to, and not in K8S in management.

Assumed to be deployed on Nginx Ingress TKE , Ingress and back-end services that prod/webcreate Issuer example:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt-http01
  namespace: prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-http01-account-key
    solvers:
    - http01:
       ingress:
         name: web # 指定被自动修改的 Ingress 名称

Using the above Issuer to issue certificates, cert-manager will automatically modify prod/webthe Ingress resources needed to expose the temporary path verification, which is automatically modified Ingress ways that you can use to automatically add Ingress way, example:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt-http01
  namespace: prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-http01-account-key
    solvers:
    - http01:
       ingress:
         class: nginx # 指定自动创建的 Ingress 的 ingress class

Use the Issuer above to issue a certificate, and cert-manager will automatically create an Ingress resource to expose the temporary path required for verification.

With Issuer, then you can create a Certificate and reference the Issuer for signing. Example:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: test-mydomain-com
  namespace: prod
spec:
  dnsNames:
  - test.mydomain.com # 要签发证书的域名
  issuerRef:
    kind: Issuer
    name: letsencrypt-http01 # 引用 Issuer，指示采用 http01 方式进行校验
  secretName: test-mydomain-com-tls # 最终签发出来的证书会保存在这个 Secret 里面

DNS-01 verification method issuance certificate

If you use the DNS-01 verification method, it depends on which DNS provider you use. cert-manager has built-in support for some DNS providers. For detailed list and usage, please refer to Supported DNS01 providers , but cert-manager is not possible To support all DNS providers, what if there is no DNS provider you use? There are two options:

Option 1: Set up Custom Nameserver. Set up a custom nameserver in your DNS provider's backend, pointing to a nameserver address like cloudflare that can manage the domain names of other DNS providers. The specific address can be checked in the cloudflare backend:

The following is an example of namecheap setting a custom nameserver:

Finally, when configuring Issuer to specify DNS-01 verification, add some cloudflare information (see the example below).
Option 2: Use Webhook. Use cert-manager's Webhook to extend the DNS provider supported by cert-manager's DNS-01 verification. There have been many third-party implementations, including the commonly used DNSPod and Ali DNS in China . Refer to Webhook for a detailed list .

Let's take cloudflare as an example to issue a certificate:

Log cloudflare, point to My Profile > API Tokens > Create Tokencreate a Token:

Copy Token and keep it properly:

Save Token in Secret:

apiVersion: v1
kind: Secret
metadata:
 name: cloudflare-api-token-secret
 namespace: cert-manager
type: Opaque
stringData:
 api-token: <API Token> # 粘贴 Token 到这里，不需要 base64 加密。

! If you want to create a ClusterIssuer, the Secret needs to be created in the namespace where the cert-manager is located. If it is an Issuer, it must be created in the namespace where the Issuer is located.

Create ClusterIssuer:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
 name: letsencrypt-dns01
spec:
 acme:
   privateKeySecretRef:
     name: letsencrypt-dns01
   server: https://acme-v02.api.letsencrypt.org/directory
   solvers:
   - dns01:
       cloudflare:
         email: [email protected] # 替换成你的 cloudflare 邮箱账号，API Token 方式认证非必需，API Keys 认证是必需
         apiTokenSecretRef:
           key: api-token
           name: cloudflare-api-token-secret # 引用保存 cloudflare 认证信息的 Secret

Create Certificate:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
 name: test-mydomain-com
 namespace: default
spec:
 dnsNames:
 - test.mydomain.com # 要签发证书的域名
 issuerRef:
   kind: ClusterIssuer
   name: letsencrypt-dns01 # 引用 ClusterIssuer，指示采用 dns01 方式进行校验
 secretName: test-mydomain-com-tls # 最终签发出来的证书会保存在这个 Secret 里面

Obtaining and using certificates

After creating the Certificate, wait a while, we can check whether the issuance is successful with kubectl:

$ kubectl get certificate -n prod
NAME                READY   SECRET                  AGE
test-mydomain-com   True    test-mydomain-com-tls   1m

If READYis Falsefor failure, you can troubleshoot the cause of the failure by viewing describe event:

$ kubectl describe certificate test-mydomain-com -n prod

If Truerepresents the successful issuance of the certificate is saved in Secret we specify (The above example is default/test-mydomain-com-tls), can be viewed kubectl:

$ kubectl get secret test-mydomain-com-tls -n default
...
data:
  tls.crt: <cert>
  tls.key: <private key>

Which tls.crtis a certificate, tls.keyit is key.

You can mount them to the application that requires a certificate, or use the self-built Ingress, you can directly reference the secret in the Ingress, example:

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: test-ingress
  annotations:
    kubernetes.io/Ingress.class: nginx
spec:
  rules:
  - host: test.mydomain.com
    http:
      paths:
      - path: /web
        backend:
          serviceName: web
          servicePort: 80
  tls:
    hosts:
    - test.mydomain.com
    secretName: test-mydomain-com-tls

summary

This article introduces the working principle of cert-manager, the installation method and the principle, comparison and operation method of the two verification methods (HTTP-01 and DNS-01) for issuing free certificates.

Reference

cert-manager official website: https://cert-manager.io/
How Let's Encrypt works: https://letsencrypt.org/zh-cn/how-it-works/
Issuer API documentation: https://cert-manager.io/docs/reference/api-docs/#cert-manager.io/v1.Issuer
Certificate API documentation: https://cert-manager.io/docs/reference/api-docs/#cert-manager.io/v1.Certificate