Managing Certificates

It's a common requirement to expose applications, either publicly or internally, with secure, TLS-encrypted endpoints.

Web applications should use HTTPS endpoints, and it's a strong security recommendation to use end-to-end encryption for internal communication between your applications and services.

Wayfinder automatically installs and configures the cert-manager application in each managed Kubernetes cluster, which creates and manages X.509 certificates (used by TLS) for Kubernetes Ingress objects and other requirements.

This topic gives instructions for configuring cert-manager and creating a self-signed certificate.

Configure cert-manager

cert-manager builds on top of Kubernetes, introducing certificate authorities and certificates as first-class resource types in the Kubernetes API. This makes it possible to provide 'certificates as a service' to developers working within a Kubernetes cluster.

If you would like to learn more, please visit cert-manager.io.

Configure using the UI

To configure cert-manager in the UI:

1. Click your workspace's overview page, then Settings, and then enter an email for your workspace, and then click Save.

   Once you enter the email, your clusters will be configured with certificates. You will receive notifications from the certificate issuer at this email address.

   Your settings are stored in a ConfigMap object called certificates-configuration.

Configure using the CLI

To configure cert-manager with the CLI:

1. Configure cert-manager using the optional ConfigMap object called certificates-configuration, as shown in the Example below.

   Example certificates-configuration.yaml:

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: certificates-configuration
     namespace: myworkspace
   data:
     email: <shared workspace email address>

   Available config parameters:

   • data.email: Let's Encrypt sends certificate expiration (and other account-related) notices to this email address

2. Update the ConfigMap using the wf apply command:

   $ wf apply -w WORKSPACEID -f certificates-configuration.yaml

Certificate issuers

In order to issue certificates, cert-manager requires configuration of Issuer or ClusterIssuer objects for each certificate provider. An Issuer can only be used in the namespace where it was created, but ClusterIssuers can be used in any namespace.

Wayfinder automatically installs the following ClusterIssuers in a cluster.

ClusterIssuer	Description
prod-le-dns01	Recommended. Generation normally takes 1-2 minutes. Uses Let's Encrypt to issue TLS certificates for HTTPS endpoints. Domain ownership is validated by cert-manager creating a TXT record on the domain for which a certificate is created.
prod-le-http01	Generation normally takes 5-6 minutes. Let's Encrypt to issue TLS certificates for HTTPS endpoints. Domain ownership is validated by cert-manager creating a temporary HTTP application that serves the required validation information on a specific path on the domain for which a certificate is created. This validation can only be used if there is an ingress controller called external that is accessible from the Internet.
self-signed	Can be used to generate self-signed certificates in the cluster. Self-signed certificates are commonly used for encrypting internal traffic between the application and the ingress controller.

Create a self-signed certificate

In this example, you will create a self-signed certificate for end-to-end (mTLS) encryption.

To create a self-signed certificate:

1. Create a Certificate object, as shown in the example below.

   Example certificate.yaml:

   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: myapp-cert
     namespace: mynamespace
   spec:
     secretName: myapp-cert
     duration: 2160h
     renewBefore: 720h
     issuerRef:
       kind: ClusterIssuer
       name: self-signed
     commonName: myapp.mynamespace.svc.cluster.local
     isCA: true

2. Run this command to apply the certificate.yaml:

   $ kubectl -n mynamespace apply -f certificate.yaml

To check the status of the certificate:

1. Run the following for your namespace:

   $ kubectl -n mynamespace get certificate
   NAME         READY   SECRET       AGE
   myapp-cert   True    myapp-cert   56s

   If the certificate is ready, the requested certificate data will be saved in the myapp-cert secret:

   $ kubectl -n mynamespace get secret myapp-cert -o yaml
   apiVersion: v1
   kind: Secret
   metadata:
     name: myapp-cert
     namespace: test
     [...]
   type: kubernetes.io/tls
   data:
     ca.crt: <base64-encrypted CA certificate>
     tls.crt: <base64-encrypted certificate>
     tls.key: <certificate private key>

For information on using the generated certificate in your application, see the Kubernetes Secrets documentation.