Cert-manager

Table of Contents

Overview

The source code and default configuration of the Building Block is available in our code.sysEleven.de. For information on release notes and new features please follow the link: Release notes cert-manager

Cert-Manager

Cert-Manager is an addon to automate the managment and issuance of TLS certificates from a wide ranges of sources.

A recommended resource overview is listed in the table below.

CPU / vCPU Memory
0.22 448MiB

No further activities need to be carried out in advance.

Adding the Building Block

Add the directory syseleven-cert-manager to your control repository. Add a .gitlab-ci.yml to the directory with the following content:

include:
  - project: syseleven/building-blocks/helmfiles/cert-manager
    file: JobDevelopment.yaml
    ref: 9.1.0
  - project: syseleven/building-blocks/helmfiles/cert-manager
    file: JobStaging.yaml
    ref: 9.1.0
  - project: syseleven/building-blocks/helmfiles/cert-manager
    file: JobProduction.yaml
    ref: 9.1.0

Remove environments you are not using by removing their include.

Required configuration

Strictly speaking, no configuration is required to deploy this Building Block. But we strongly recommend configuring an ACME account email address. It will be used to contact you in case of issues with your account or certificates, including expiry notification emails.

values-cert-manager-extension.yaml or values-cert-manager-extension-$ENVIRONMENT.yaml:

email: letsencrypt@example.org

Provision a TLS certificate for an ingress automatically

You need to add one of two annotations to your ingress and configure the TLS section:

Annotations

  • Add the annotation cert-manager.io/cluster-issuer: "letsencrypt-production" to get a valid certificate from Let's Encrypt.
  • Add the annotation cert-manager.io/cluster-issuer: "letsencrypt-staging" to get a certificate from Let’s Encrypts staging CA. This certificate will not be accepted by tooling and browsers. Use it only for testing purposes.

TLS section

Your ingress needs a spec.tls section. An example:

  tls:
    - hosts:
        - subdomain.example.com
      secretName: subdomain.example.com-tls

Notes:

  • You need to specify the secretName so that cert-manager knows where to save the certificate and the ingress-controller knows which certificate to use. The secret does not need to exist beforehand as it automatically will get generated by cert-manager.

DNS challenge

If you use our SysEleven Stack DNSaaS, the relevant configuration for DNS challenges is already included by default.

To use the DNS challenge add the following label to your Ingress/Certificate:

  • cert-manager.io/solver: dns01

Other DNSaaS providers

If you want to use another DNSaaS provider please consult the cert-manager upstream documentation.

You need to add the configuration for the provider to the values-cert-manager-extension.yaml like:

solvers:
  - dns01:
      route53:
        region: eu-central-1
        accessKeyID: <Access ID for less-privileged.example.org here>
        hostedZoneID: <Zone ID for less-privileged.example.org here>
        secretAccessKeySecretRef:
          <Secret name where the SecretAccessKey is stored>
    selector:
      matchLabels:
        # Define label for dns challenge to be able to match the certificate
        cert-manager.io/solver: dns01

In this case you do not need the designate-webhook. To disable the installation of it just add the environment variable RELEASE_DESIGNATE_CERTMANAGER_WEBHOOK_ENABLED=false

Example configuration

To make the following example work you need to use the SysEleven DNSaaS to configure your DNS record.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  labels:
    # Use acme/solver: dns01 defined in ClusterIssuer: letsencrypt-production.
    cert-manager.io/solver: dns01
  name: test-certificate
  namespace: syseleven-cert-manager
spec:
  dnsNames:
    - test-certificate.<customerdomain>.de
  issuerRef:
    group: cert-manager.io
    kind: ClusterIssuer
    name: letsencrypt-production
  # Store the certificate as secret named testdomain-cert-secret in namespace: syseleven-cert-manager
  secretName: test-certificate-secret

Issuing the certificate can take a few minutes. Please check regularly with the following command:
kubectl describe certificate -n syseleven-cert-manager test-certificate
or
kubectl get -n syseleven-cert-manager secret test-certificate-secret -o jsonpath='{.data.tls\.crt}'| base64 -d -| openssl x509 -dates -subject -noout

Cleanup

To remove the example again, the following resources must be removed:
kubectl delete certificate -n syseleven-cert-manager test-certificate
kubectl delete secret -n syseleven-cert-manager test-certificate-secret

Monitoring

Additional alertrules

  • None

Additional Grafana dashboards

  • None

Scale Setup

This building block consists of multiple components. Each of the components can and must be scaled individually.

  • Usually it is not needed to scale replicas unless you have an excessive amount of certificate requests
  • Requests/limits for CPU/memory can be adjusted

Release-Notes

Please find more information on release notes and new features Release notes Cert-Manager