Tutorial: How to use Cert Manager to manage certificates in Apache APISIX Ingress Controller

October 22, 2021 · 6 min read

This article shows how to create a certificate and pair it with Apache APISIX Ingress Controller via the Cert Manager.

Apache APISIX Ingress Controller is a Kubernetes Ingress Controller Open Source Tool that uses Apache APISIX as a data surface and has been updated to v1.3 with features such as certificate management, load balancing, Canary Publishing, and more.

For a long time, certificate management is not a simple thing although Apache APISIX Ingress Controller supports extracting certificates and private keys from Kubernetes Secrets Resources and converting them into Apache APISIX recognizable SSL objects, but this is only a part of the whole certificate management chain, certificate issuance, rotation, revocation logic still need to be implemented by administrators, especially when the number of certificates is relatively large, the workload is often not small, so it takes up a lot of the administrator’s time.

Cert Manager is a piece of software dedicated to simplifying certificate management on the Kubernetes platform and supports docking many different certificate sources, such as Let’s Encrypt and HashiCorp Vault.

If you’re having trouble with certificate management when using Apache APISIX Ingress Controller, using the Cert Manager is a good option, and this article shows how to create a certificate and pair it with Apache APISIX Ingress Controller via the Cert Manager.

Step 1: Environmental Preparation#

If you want to follow the instructions in this article, make sure the following environments and tools are in place:

To prepare a usable Kubernetes cluster, in the development environment, you can use Kind and Minikube
Install kubectl
Install Helm v3

Note that all of the following operations will be performed in the ingress-apisix namespace, so you need to create the namespace first: kubectl create namespace ingress-apisix

Step 2：Install Apache APISIX Ingress Controller#

You can install Apache APISIX Ingress Controller via Helm, including Apache APISIX and etcd clusters for data planes.

helm repo add apisix https://charts.apiseven.comhelm repo updatehelm install apisix apisix/apisix --set gateway.tls.enabled=true --set ingress-controller.enabled=true --namespace ingress-apisix

Click to view the installation details.

Step 3：Install Cert Manager#

To Install Cert Manager from Helm, click to view the installation details.

helm install cert-manager jetstack/cert-manager --namespace ingress-apisix  --set prometheus.enabled=false --set installCRDs=true

Please wait for a moment after installation to check the running status of the components and make sure that all the components are working properly. You can do this by following the command.

kubectl get all -n ingress-apisix

The result is as follows, indicating that all components are working properly.

NAME                                             READY   STATUS        RESTARTS   AGEpod/apisix-5d99956d88-j68sj                      1/1     Running       0          63spod/apisix-69459554d4-btnwn                      0/1     Terminating   0          57mpod/apisix-etcd-0                                1/1     Running       0          57mpod/apisix-etcd-1                                1/1     Running       0          57mpod/apisix-etcd-2                                0/1     Running       0          50spod/apisix-ingress-controller-7b5c767cc7-j62hb   1/1     Running       0          55mpod/cert-manager-5ffd4f6c89-q9f7m                1/1     Running       0          45mpod/cert-manager-cainjector-748dc889c5-nrvkh     1/1     Running       0          45mpod/cert-manager-startupapicheck-kmgxf           0/1     Completed     0          45mpod/cert-manager-webhook-bc964d98b-mkjj7         1/1     Running       0          45m
NAME                                TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGEservice/apisix-admin                ClusterIP   10.96.16.25     <none>        9180/TCP                     57mservice/apisix-etcd                 ClusterIP   10.96.232.251   <none>        2379/TCP,2380/TCP            57mservice/apisix-etcd-headless        ClusterIP   None            <none>        2379/TCP,2380/TCP            57mservice/apisix-gateway              NodePort    10.96.118.75    <none>        80:32039/TCP,443:30107/TCP   57mservice/apisix-ingress-controller   ClusterIP   10.96.13.76     <none>        80/TCP                       57mservice/cert-manager-webhook        ClusterIP   10.96.182.188   <none>        443/TCP                      45m
NAME                                        READY   UP-TO-DATE   AVAILABLE   AGEdeployment.apps/apisix                      1/1     1            1           57mdeployment.apps/apisix-ingress-controller   1/1     1            1           57mdeployment.apps/cert-manager                1/1     1            1           45mdeployment.apps/cert-manager-cainjector     1/1     1            1           45mdeployment.apps/cert-manager-webhook        1/1     1            1           45m
NAME                                                   DESIRED   CURRENT   READY   AGEreplicaset.apps/apisix-5d99956d88                      1         1         1       63sreplicaset.apps/apisix-69459554d4                      0         0         0       57mreplicaset.apps/apisix-ingress-controller-74c6b5fbdd   0         0         0       57mreplicaset.apps/apisix-ingress-controller-7b5c767cc7   1         1         1       55mreplicaset.apps/apisix-ingress-controller-7d58db957c   0         0         0       55mreplicaset.apps/cert-manager-5ffd4f6c89                1         1         1       45mreplicaset.apps/cert-manager-cainjector-748dc889c5     1         1         1       45mreplicaset.apps/cert-manager-webhook-bc964d98b         1         1         1       45m
NAME                           READY   AGEstatefulset.apps/apisix-etcd   2/3     57m
NAME                                     COMPLETIONS   DURATION   AGEjob.batch/cert-manager-startupapicheck   1/1           6m24s      45m

The mechanism of the Kubernetes Controller Manager determines that the Pod name will be different.

Step 4: Apply for a Certificate and Test it#

First we need to configure the credential issuing object.

# issuer.yamlapiVersion: cert-manager.io/v1kind: Issuermetadata:  name: issuer  namespace: ingress-apisixspec:  selfSigned: {}

And create a self-signed certificate issuer.

kubectl apply -f issuer.yaml

Note that self-signed authoring objects are not recommended for use in production environments! See here for more on the configuration of the certificate authority object.

。Then create a certificate for the domain name httpbin. org.

# httpbin-cert.yamlapiVersion: cert-manager.io/v1kind: Certificatemetadata:  name: httpbin  namespace: ingress-apisixspec:  secretName: httpbin  duration: 2160h # 90d  renewBefore: 360h # 15d  subject:    organizations:      - foo  commonName: httpbin.org  isCA: false  privateKey:    algorithm: RSA    encoding: PKCS1    size: 2048  usages:    - server auth  dnsNames:    - "httpbin.org"    - "*.httpbin.org"  issuerRef:    name: issuer    kind: Issuer    group: cert-manager.io

kubectl apply -f httpbin-cert.yaml

At this point, it is necessary to see whether the corresponding Secrets have been created.

kubectl get secrets -n ingress-apisix httpbinNAME      TYPE                DATA   AGEhttpbin   kubernetes.io/tls   3      2m5s

With the above validation, the creation of the Secrets object has been captured by Apache APISIX Ingress Controller, we try to access Apache APISIX Ingress Controller to verify the certificate is valid, first we need to create additional routing objects.

# Create backendkubectl run httpbin --image kennethreitz/httpbin --namespace ingress-apisixkubectl expose pod httpbin -n ingress-apisix --port 80

# Define ApisixTls ObjectsapiVersion: apisix.apache.org/v1kind: ApisixTlsmetadata:  name: httpbin  namespace: ingress-apisixspec:  hosts:  - httpbin.org  secret:    name: httpbin    namespace: ingress-apisix---# Define the route to access the backendapiVersion: apisix.apache.org/v2beta1kind: ApisixRoutemetadata:  name: httpbin  namespace: ingress-apisixspec:  http:  - name: httpbin    match:      paths:      - /*      hosts:      - httpbin.org    backends:    - serviceName: httpbin      servicePort: 80

Next access the service apisix-gateway. Note that the service is NodePort by default, and you can change its type as needed. If your Kubernetes cluster is hosted by the cloud vendor, consider changing it to the LoadBalancer type, to get an externally accessible IP.

Here we map the service to local via port forwarding.

kubectl port-forward -n ingress-apisix svc/apisix-gateway 8443:443

Then start configuring access.

curl https://httpbin.org:8443/json --resolve 'httpbin.org:8443:127.0.0.1' -sk{  "slideshow": {    "author": "Yours Truly",    "date": "date of publication",    "slides": [      {        "title": "Wake up to WonderWidgets!",        "type": "all"      },      {        "items": [          "Why <em>WonderWidgets</em> are great",          "Who <em>buys</em> WonderWidgets"        ],        "title": "Overview",        "type": "all"      }    ],    "title": "Sample Slide Show"  }}

After the above operation, you can see that the access was successful, that the certificate has been validated. Note that since the certificate is self-signed, the -k option needs to be added to ignore the certificate validation.

In addition, if you want to rotate the certificate, remove the httpbin as the Secret object, and Cert Manager immediately creates a new httpbin Secret object and includes the new certificate.

Summary#

This article focuses on how to use the CERT Manager to create and manage certificates in Apache APISIX Ingress Controller. For more on Apache APISIX Ingress, see this article.

Or take part in a biweekly online discussion on the Apache APISIX Ingress Project to share current project progress, best practices, and design ideas.