Cert-manager

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

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: 4.31.1
  - project: syseleven/building-blocks/helmfiles/cert-manager
    file: JobStaging.yaml
    ref: 4.31.1
  - project: syseleven/building-blocks/helmfiles/cert-manager
    file: JobProduction.yaml
    ref: 4.31.1

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 recommended configuring a 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.

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

Check the generated certificate:
kubectl describe certificate -n syseleven-cert-manager test-certificate-secret
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-secret
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 infos on release notes and new features Release notes Cert-Manager