Key Concepts: Cert-manager, Issuers, and Secrets

By default API Connect uses an open source product that is called cert-manager to handle the issuing and renewal of the certificates that are used by API Connect. The cert-manager has its own Kubernetes pods and runs in its own namespace. The cert-manager adds some additional resources to the Kubernetes environment. The API Connect administrator needs to be familiar with these additional resources:

Issuers

Issuers play the part of certificate authorities (CAs) in the local environment and issue the certificates. Issuers reside in the API Connect namespace. There are two types of Issuers:
  • Self-Signed - This issuer provides the self-signed certificates, for example a root CA.
  • CA - This issuer can be either the root certificate authority or an intermediate certificate authority .
Here is an example of the issuers that can be found on the Management Server:
kubectl get issuers
NAME                 READY   AGE
abc-management-ca    True    96d
selfsigning-issuer   True    96d
  • selfsigning-issuer This is a SelfSigned Issuer that provides the root certificate for all default certificates that are used in API Connect.
  • abc-management-ca This is a CA Issuer that signs all the end-entity certificates that are used by the Management Server. It is in effect an intermediate CA between the Root (selfsigning-issuer) and the end-entity certificates.

Certificates

A certificate is a Kubernetes resource that contains a pointer to a Kubernetes secret which contains the actual TLS certificate. Certificate objects contain other information such as the certificate Issuer, renew-by date, and a status. Below are some of the Certificates that can be found on the Management Server:
kubectl get certificate
NAME                                      READY   SECRET                                    AGE
abc-management-ca                         True    abc-management-ca                         96d
abc-management-client                     True    abc-management-client                     96d
abc-management-natscluster-mgmt           True    abc-management-natscluster-mgmt           96d
abc-management-server                     True    abc-management-server                     96d
...
The first in the list 'abc-management-ca' is the intermediate CA Certificate that is used for signing all the other certificates below it. Describing this resource observe that it is itself issued by the selfsigning-issuer mentioned earlier:
Issuer Ref:
    Kind:  Issuer
    Name:  selfsigning-issuer
Describing the subsequent certificates, observe they are all issued by the abc-management-ca:
Issuer Ref:
    Kind:  Issuer
    Name:  abc-management-ca
Key points:
  • The certificates with '-ca' on the end are all CA Certificates, and they sign all the other subsystem certificates that whose names do not end with '-ca'.
  • The CA certificates are also known as Issuer certificates.
  • Certificates that are signed by the CA certificates are known as end-entity certificates.
  • When a CA certificate is updated, all end-entity certificates that are signed by it must also be updated.

Secrets

This is the standard Kubernetes resource for storing credentials, and for API Connect these are where the certificates are stored.

Notice the output from 'kubectl get certificate' above had a 'Secret' column. This is a shorthand way to know the certificate's corresponding Secret, as defined in its 'Secret Name' property:
kubectl describe certificate abc-management-client | grep "Secret Name"
  Secret Name:        abc-management-client
Below is the describe output for above Secret, showing that it contains the tls certificates:
kubectl describe secret abc-management-client
Name:         abc-management-client
Namespace:    default
Labels:       app.kubernetes.io/instance=abc-management
              app.kubernetes.io/managed-by=ibm-apiconnect
              app.kubernetes.io/name=abc-management-client
Annotations:  cert-manager.io/alt-names: 
              cert-manager.io/certificate-name: abc-management-client
              cert-manager.io/common-name: abc-management-client
              cert-manager.io/ip-sans: 
              cert-manager.io/issuer-group: 
              cert-manager.io/issuer-kind: Issuer
              cert-manager.io/issuer-name: abc-management-ca
              cert-manager.io/uri-sans: 

Type:  kubernetes.io/tls

Data
====
ca.crt:   1107 bytes
tls.crt:  1139 bytes
tls.key:  1675 bytes
The certificates themselves can be seen with kubectl get -o yaml secret abc-management-client.