Creating IBM Cloud Private Certificate manager (cert-manager) certificates

The IBM® Cloud Private Certificate manager service is used to issue and manage certificates for services that run on IBM Cloud Private. Certificate manager is based on the jetstack/cert-manager project .

• Adding a certificate to a Kubernetes workload
• Adding a certificate to a Kubernetes Ingress

Adding a certificate to a Kubernetes workload

An icp-ca-issuer is automatically created as a ClusterIssuer for each IBM Cloud Private installation. This Issuer contains the self-signed IBM Cloud Private cluster CA and is accessible from all namespaces. More Issuers (namespace-scoped) or ClusterIssuers (cluster-scoped) can be defined. See the Creating Issuers section.

1. To define the certificate, edit the metadata where <name> is associated with the certificate and the <namespace> is where the certificate is created. Additionally, edit the spec section of the following sample, which defines a certificate that uses the default ClusterIssuer that is provided by IBM Cloud Private:

apiVersion: certmanager.k8s.io/v1alpha1
kind: Certificate
metadata:
  name: hello-deployment-tls-1
  namespace: foobar
spec:
  # name of the tls secret to store
  # the generated certificate/key pair
  secretName: hello-deployment-tls-1
  issuerRef:
    # ClusterIssuer Name
    name: icp-ca-issuer
    # Issuer can be referenced
    # by changing the kind here.
    # the default value is Issuer (i.e.
    # a locally namespaced Issuer)
    kind: ClusterIssuer
  commonName: "foo1.bar1"
  dnsNames:
   # one or more fully-qualified domain names
   # can be defined here
  - foo1.bar1

1. Mount the Secret to the Deployment, DaemonSet, or StatefulSet.

   The Kubernetes Secret that contains the certificate is mounted to the file system in the same manner as any other secret. For more information, see the Kubernetes documentation .

Adding a certificate to Kubernetes Ingress

The Ingress Kubernetes resource type is used to expose services to an external network. Cert-manager generated certificates can be added to Ingress resources. IBM Cloud Private provides a NGINX Kubernetes Ingress point out-of-the-box.

Handling Multiple Domain Names

Requests to multiple virtual hosts are handled by the same Ingress. Each virtual host can be terminated with its own certificates. In this case, the fully-qualified domain name in the TLS/HTTPS request is used to identify the requested virtual host. The TLS-SNI protocol extension defines this process.

Complete the following procedure to secure the Kubernetes Ingress:

1. Define the certificate, similar to the previous step. The following example defines a certificate that uses the default ClusterIssuer that is provided by IBM Cloud Private:

   apiVersion: certmanager.k8s.io/v1alpha1
   kind: Certificate
   metadata:
    name: hello-deployment-tls-1
    namespace: foobar
   spec:
    # name of the tls secret to store
    # the generated certificate/key pair
    secretName: hello-deployment-tls-1
    issuerRef:
      # ClusterIssuer Name
      name: icp-ca-issuer
      # Issuer can be referenced
      # by changing the kind here.
      # the default value is Issuer (i.e.
      # a locally namespaced Issuer)
      kind: ClusterIssuer
    commonName: "foo1.bar1"
    dnsNames:
     # one or more fully-qualified domain names
     # can be defined here
    - foo1.bar1
   

   Cert-manager creates the certificate based on the certificate resource definition and stores it as a Kubernetes Secret.

2. Add the Secret to the Kubernetes Ingress. The following example defines a TLS-enabled Kubernetes Ingress that is integrated with cert-manager. Here, hello-k8s-ingress-tls-1 matches the secretName that you previously defined and host matches the DNS name that you previously defined in the certificate.

   apiVersion: extensions/v1beta1
   kind: Ingress
   metadata:
    name: hello-k8s-ingress-tls
    annotations:
      kubernetes.io/ingress.class: "nginx"
      ingress.kubernetes.io/rewrite-target: "/"
   spec:
    tls:
    # k8s ingress defines different tls certificates
    # for each nginx server blocks.
    # k8s ingress default cert is used if
    # no host-specific secret specified
    - hosts:
    # this is the fully-qualified domain name
    # of the first server block
      - foo1.bar1
      # certificate hello-k8s-ingress-tls-1
      # is only used by foo1.bar1
      secretName: hello-k8s-ingress-tls-1
    rules:
      # each server block redirects request
      # to its own backend service
    - host: foo1.bar1
      http:
        paths:
        - backend:
            serviceName: hello-world-svc
            servicePort: 80
          path: /fb
   

Note: Certificates that are created by cert-manager are automatically renewed before expiration. Workloads must pick up the new certificates.

See Using IBM Cloud Private Certificate manager (cert-manager) for more Certificate manager topics.