Skip to content
local-cert
Browse the documentation

Kubernetes

With cert-manager, local-cert is declared as an ACME ClusterIssuer. Ingresses and Certificate resources then use it like any other issuer.

ValueWhere to find itIn this guide
ACME directoryfixed for each instancehttps://certs.example.com/acme/directory
Key ID (kid)Keys & access → EAB credentialseab_XXXXXXXXXXXXXXXX
HMAC keyshown only once, at creationCLE_HMAC

1. The EAB secret

kubectl
kubectl -n cert-manager create secret generic local-cert-eab \
  --from-literal=secret=CLE_HMAC

For a ClusterIssuer, the secret must be in cert-manager's namespace.

2. The ClusterIssuer

local-cert-issuer.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: local-cert
spec:
  acme:
    server: https://certs.example.com/acme/directory
    email: ops@example.com
    privateKeySecretRef:
      name: local-cert-account
    externalAccountBinding:
      keyID: eab_XXXXXXXXXXXXXXXX
      keySecretRef:
        name: local-cert-eab
        key: secret
    solvers:
      - http01:
          ingress:
            ingressClassName: nginx
apply and verify
kubectl apply -f local-cert-issuer.yaml
kubectl get clusterissuer local-cert -o wide   # READY must turn True

Replace ingressClassName with your controller's (traefik on k3s, for example).

3. Request a certificate

With an annotation on an Ingress:

ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nas
  annotations:
    cert-manager.io/cluster-issuer: local-cert
spec:
  ingressClassName: nginx
  tls:
    - hosts: [nas.home.example.com]
      secretName: nas-tls
  rules:
    - host: nas.home.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: nas
                port:
                  number: 80

or explicitly:

certificate.yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: nas
spec:
  secretName: nas-tls
  dnsNames: [nas.home.example.com]
  issuerRef:
    kind: ClusterIssuer
    name: local-cert

Following an issuance

kubectl
kubectl get certificate,certificaterequest,order,challenge -A
kubectl describe challenge -A | tail -n 20

Allow one to three minutes between the challenge being presented and the Certificate turning Ready. cert-manager then renews on its own, at two thirds of the lifetime.

Variants

  • One issuer per namespace: use Issuer instead of ClusterIssuer, with the EAB secret in the same namespace. One EAB credential per team, limited to its domains, gives clean separation.
  • Gateway API: replace the solver with http01.gatewayHTTPRoute.parentRefs.
  • Without cert-manager (k3s with Traefik): the resolver described in Traefik is declared in the chart's arguments through a HelmChartConfig.
  • Wildcards: cert-manager refuses HTTP-01 for a wildcard. Issue it through the API and load it as a TLS secret.