# Cert-Manager

## Overview

The source code and default configuration of the Building Block is available in our [code.syseleven.de](<https://code.syseleven.de/syseleven/building-blocks/helmfiles/cert-manager>). For information on release notes and new features please follow the link: [Release notes cert-manager](<https://code.syseleven.de/syseleven/building-blocks/helmfiles/cert-manager/-/blob/main/RELEASE-NOTES.md>)

### Cert-Manager

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

#### Recommended Setup

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:

```yaml
include:
  - project: syseleven/building-blocks/helmfiles/cert-manager
    file: JobDevelopment.yaml
    ref: {{ site.building_blocks.cert_manager.version|e }}
  - project: syseleven/building-blocks/helmfiles/cert-manager
    file: JobStaging.yaml
    ref: {{ site.building_blocks.cert_manager.version|e }}
  - project: syseleven/building-blocks/helmfiles/cert-manager
    file: JobProduction.yaml
    ref: {{ site.building_blocks.cert_manager.version|e }}
```

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 about issues with your account or certificates, including expiry notification emails.

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

```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:

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

> [!NOTE]
>
> **Notes**
>
> You need to specify the `secretName` to let cert-manager know where to save the certificate and the ingress-controller know 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 [DNSaaS](<https://documentation.syseleven.de/en/prior-docs/openstack-cloud/how-to/dnsaas/index.md>), 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

To use another DNSaaS provider please see the cert-manager upstream [documentation](<https://cert-manager.io/docs/configuration/acme/dns01/>).

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

```yaml
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

> [!NOTE]
>
> **Info**
>
> To make the following example work you need to use the [DNSaaS](<https://documentation.syseleven.de/en/prior-docs/openstack-cloud/how-to/dnsaas/index.md>) to configure your DNS record.

```yaml
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:

```shell
kubectl describe certificate -n syseleven-cert-manager test-certificate
```

or

```shell
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:

```shell
kubectl delete certificate -n syseleven-cert-manager test-certificate
kubectl delete secret -n syseleven-cert-manager test-certificate-secret
```

### Monitoring

#### Additional Alert-Rules

- 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](<https://code.syseleven.de/syseleven/building-blocks/helmfiles/cert-manager/-/blob/main/RELEASE-NOTES.md>)
