Kubernetes cert-manager

Concept

Workflow

Feedback
Create a certificate profile in Hanzo KMS with the ACME enrollment method configured on it.
Feedback
Install cert-manager in your Kubernetes cluster.
Feedback
Create a Kubernetes Secret containing the EAB (External Account Binding) credentials for the ACME certificate profile.
Feedback
Create an Issuer or ClusterIssuer resource that connects to the desired Hanzo KMS certificate profile.
Feedback
Create a Certificate resource defining the certificate you wish to issue and the target Secret where the certificate and private key will be stored.
Feedback
Use the resulting Kubernetes Secret in your Ingresses or other resources.

Guide

Follow the instructions here to create a certificate profile that uses ACME enrollment.

After completion, you will have the following values:

• ACME Directory URL
• EAB Key ID (KID)
• EAB Secret

These will be needed in later steps.

Currently, the Hanzo KMS ACME enrollment method only supports authentication via dedicated EAB credentials generated per certificate profile.

Support for Kubernetes Auth is planned for the near future.

Install cert-manager in your Kubernetes cluster by following the official guide here or by applying the manifest directly:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.1/cert-manager.yaml

Create a Kubernetes Secret that contains the EAB Secret (HMAC key) obtained in step 1. The cert-manager uses this secret to authenticate with the Hanzo KMS ACME server.

kubectl create secret generic kms-acme-eab-secret \
    --namespace <namespace_you_want_to_issue_certificates_in> \
    --from-literal=eabSecret=<eab_secret>

apiVersion: v1
kind: Secret
metadata:
    name: kms-acme-eab-secret
    namespace: <namespace_you_want_to_issue_certificates_in>
data:
    eabSecret: <eab_secret>

kubectl apply -f acme-eab-secret.yaml

Next, create a cert-manager Issuer (or ClusterIssuer) by replacing the placeholders <acme_server_url>, <your_email>, and <acme_eab_kid> in the configuration below and applying it. This resource configures cert-manager to use your KMS PKI collection's ACME server for certificate issuance.

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
    name: issuer-kms
    namespace: <namespace_you_want_to_issue_certificates_in>
spec:
    acme:
        # ACME server URL from your Hanzo KMS certificate profile (Step 1)
        server: <acme_server_url>
        # Email address for ACME account
        # (any valid email works; currently ignored by Hanzo KMS)
        email: <your_email>
        # Required to honor the duration field in Certificate resources
        enableDurationFeature: true
        externalAccountBinding:
            # EAB Key ID from Step 1
            keyID: <acme_eab_kid>
            # Reference to the Kubernetes Secret containing the EAB
            # HMAC key (created in Step 3)
            keySecretRef:
                name: kms-acme-eab-secret
                key: eabSecret
        privateKeySecretRef:
            name: issuer-kms-account-key
        solvers:
        - http01:
            ingress:
                # Replace with your actual ingress class if different
                className: nginx

kubectl apply -f issuer-kms.yaml

You can check that the issuer was created successfully by running the following command:

kubectl get issuers.cert-manager.io -n <namespace_of_issuer> -o wide

NAME               AGE
issuer-kms   21h

• Currently, the ACME enrollment method only supports the HTTP-01 challenge method. Support for the DNS-01 challenge method is planned for a future release. If domain ownership validation is not desired, you can disable it by enabling the Skip DNS ownership validation option in your ACME certificate profile configuration.
• An Issuer is namespace-scoped. Certificates can only be issued using an Issuer that exists in the same namespace as the Certificate resource.
• If you need to issue certificates across multiple namespaces with a single resource, create a ClusterIssuer instead. The configuration is identical except kind: ClusterIssuer and no metadata.namespace.
• More details: https://cert-manager.io/docs/configuration/acme/

Finally, request a certificate from Hanzo KMS ACME server by creating a cert-manager Certificate resource. This configuration file specifies the details of the (end-entity/leaf) certificate to be issued.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
    name: certificate-by-issuer
    namespace: <namespace_you_want_to_issue_certificates_in>
spec:
    dnsNames:
    - certificate-by-issuer.example.com
    # name of the resulting Kubernetes Secret
    secretName: certificate-by-issuer
    # total validity period of the certificate
    duration: 48h
    # cert-manager will attempt renewal 12 hours before expiry
    renewBefore: 12h
    # set to true to issue a CA certificate (policy must allow/require CA)
    isCA: false
    privateKey:
        algorithm: ECDSA
        # uses NIST P-256 curve
        size: 256
    issuerRef:
        name: issuer-kms

The above sample configuration file specifies a certificate to be issued with the dns name certificate-by-issuer.example.com and ECDSA private key using the P-256 curve, valid for 48 hours; the certificate will be automatically renewed by cert-manager 12 hours before expiry. The certificate is issued by the issuer issuer-kms created in the previous step and the resulting certificate and private key will be stored in a secret named certificate-by-issuer.

Note that the full list of the fields supported on the Certificate resource can be found in the API reference documentation here.

The enableDurationFeature: true flag in the Issuer configuration (Step 4) is required for cert-manager to honor the duration field. Without it, certificates default to 47 days regardless of what you specify. This flag is disabled by default in cert-manager because public ACME servers like Let's Encrypt don't support custom durations.

cert-manager does not currently support specifying a pathLen in the Certificate resource. When issuing CA certificates with isCA: true, ensure your Hanzo KMS certificate policy does not set a Maximum Allowed Path Length restriction, otherwise the request will fail validation.

You can check that the certificate was created successfully by running the following command:

kubectl get certificates -n <namespace_of_your_certificate> -o wide

NAME                    READY   SECRET                  ISSUER             STATUS                                          AGE
certificate-by-issuer   True    certificate-by-issuer   issuer-kms   Certificate is up to date and has not expired   20h

Since the actual certificate and private key are stored in a Kubernetes secret, we can check that the secret was created successfully by running the following command:

kubectl get secret certificate-by-issuer -n <namespace_of_your_certificate>

NAME                    TYPE                DATA   AGE
certificate-by-issuer   kubernetes.io/tls   2      26h

We can describe the secret to get more information about it:

kubectl describe secret certificate-by-issuer -n default

Name:         certificate-by-issuer
Namespace:    default
Labels:       controller.cert-manager.io/fao=true
Annotations:  cert-manager.io/alt-names:
            cert-manager.io/certificate-name: certificate-by-issuer
            cert-manager.io/common-name:
            cert-manager.io/alt-names: certificate-by-issuer.example.com
            cert-manager.io/ip-sans:
            cert-manager.io/issuer-group: cert-manager.io
            cert-manager.io/issuer-kind: Issuer
            cert-manager.io/issuer-name: issuer-kms
            cert-manager.io/uri-sans:

Type:  kubernetes.io/tls

Data
====
ca.crt: 1306 bytes
tls.crt: 2380 bytes
tls.key:  227 bytes

Here, ca.crt is the Root CA certificate, tls.crt is the requested certificate followed by the certificate chain, and tls.key is the private key for the certificate.

We can decode the certificate and print it out using openssl:

kubectl get secret certificate-by-issuer -n default -o jsonpath='{.data.tls\.crt}' | base64 --decode | openssl x509 -text -noout

In any case, the certificate is ready to be used as Kubernetes Secret by your Kubernetes resources.

Injecting CA Certificate into Secrets with trust-manager

Installing trust-manager

helm repo add jetstack https://charts.jetstack.io --force-update

helm upgrade trust-manager jetstack/trust-manager \
  --install \
  --namespace cert-manager \
  --wait \
  --set secretTargets.enabled=true \
  --set secretTargets.authorizedSecretsAll=true

The secretTargets.authorizedSecretsAll=true option grants trust-manager permission to write to all secrets in the cluster. For production environments, consider using secretTargets.authorizedSecrets to specify only the secrets that trust-manager should manage. Refer to the trust-manager Helm chart documentation for more details.

Creating the CA Certificate Secret

Feedback
Navigate to your project in Hanzo KMS
Feedback
Go to the Certificate Authorities tab
Feedback
Select the CA that is issuing your certificates
Feedback
Click the menu (three dots) next to the CA certificate and select Download CA Certificate Chain

apiVersion: v1
kind: Secret
metadata:
  name: kms-ca-cert
  namespace: cert-manager
type: Opaque
stringData:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    <paste_the_downloaded_certificate_chain_here>
    -----END CERTIFICATE-----

kubectl apply -f kms-ca-cert.yaml

Creating the trust-manager Bundle

apiVersion: trust.cert-manager.io/v1alpha1
kind: Bundle
metadata:
  name: certificate-by-issuer
spec:
  sources:
    - secret:
        name: kms-ca-cert
        key: ca.crt
  target:
    secret:
      key: ca.crt
    namespaceSelector:
      matchLabels:
        kubernetes.io/metadata.name: default

kubectl apply -f trust-bundle.yaml

• The metadata.name of the Bundle must match the secretName specified in your Certificate resource.
• Update the namespaceSelector to match the namespace(s) where your certificate secrets are located.
• The Bundle is cluster-scoped and can target secrets across multiple namespaces using namespaceSelector.

Verifying the CA Certificate Injection

kubectl get secret certificate-by-issuer -o yaml

apiVersion: v1
data:
  ca.crt: <base64_encoded_ca_certificate>
  tls.crt: <base64_encoded_certificate_chain>
  tls.key: <base64_encoded_private_key>
kind: Secret
metadata:
  annotations:
    cert-manager.io/certificate-name: certificate-by-issuer
    cert-manager.io/issuer-name: issuer-kms
    trust.cert-manager.io/hash: <hash_value>
  labels:
    controller.cert-manager.io/fao: "true"
    trust.cert-manager.io/bundle: certificate-by-issuer
  name: certificate-by-issuer
  namespace: default
type: Opaque

FAQ

The full list of the fields supported on the Certificate resource can be found in the API reference documentation here.

Currently, not all fields are supported by the KMS PKI ACME server.

Make sure your Issuer or ClusterIssuer has enableDurationFeature: true set under the acme block (see Step 4). Without this flag, cert-manager defaults to 47 days regardless of the duration field in your Certificate resource.

This flag is disabled by default in cert-manager because public ACME servers like Let's Encrypt don't support custom durations. For more details, see the cert-manager v1.1 release notes.

Yes. cert-manager will automatically renew certificates according to the renewBefore threshold of expiry as specified in the corresponding Certificate resource.

You can read more about the renewBefore field here.