Secure Kubernetes certificates with cert-manager and Dekorate

Cert-manager is a cloud-native certificate management service for Kubernetes and Red Hat OpenShift. To configure cert-manager, you need to install several resources using custom resource definitions (CRDs). Depending on the issuer type and the certificate you need, creating these custom resources can become complex. This article introduces Dekorate as an easier way to generate the cert-manager custom resources. We will also provide an example Java application based on Spring Boot that uses the certificate generated by cert-manager.

Getting started with the Dekorate cert-manager extension

Cert-manager requires the installation of several resources, including Issuer, ClusterIssuer, and Certificate. Cert-manager processes these resources to populate a secret, containing authentication information, such as a CA certificate, private key, server certificate, or Java keystores. This secret can then be used to secure your application endpoints or Kubernetes Ingress resources.

Dekorate, starting with version 2.10, can generate the certificate and issuer resources for you. Include the cert-manager Dekorate dependency in your POM file using the latest version of Dekorate from Maven central as follows:

<dependency>
  <groupId>io.dekorate</groupId>
  <artifactId>certmanager-annotations</artifactId>
  <version>{dekorate.version}</version>
</dependency>

The minimal information Dekorate needs for certificate configuration is:

• A secretName property containing the name of the Kubernetes secret resource that will include the files generated by cert-manager.
• The Issuer that represents the certificate authority (CA). The Issuer section of the Dekorate documentation lists supported options.

You can start with a minimal configuration in the .properties file and set up the following keys:

dekorate.certificate.secret-name=tls-secret
# The self-signed issuer:
dekorate.certificate.self-signed.enabled=true

The Dekorate Cert-Manager Configuration Guide lists many configuration options that determine how Dekorate works with cert-manager. You can specify configuration options by adding the @Certificate annotation to your Java program:

@Certificate(secretName = "tls-secret", selfSigned = @SelfSigned(enabled = true))
public class Main {
    // ...
}

This configuration generates all the resources in the target/classes/dekorate/kubernetes.yml file, which should look like this:

---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: kubernetes-example
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: kubernetes-example
spec:
  encodeUsagesInRequest: false
  isCA: false
  issuerRef:
    name: kubernetes-example
  secretName: tls-secret

The Dekorate cert-manager extension considers the secret that contains the files generated by cert-manager and mounts it as a volume and as part of the deployment. Dekorate allows the application to access the files and configure the HTTPS/TLS endpoint:

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kubernetes-example
spec:
  replicas: 1
  template:
    spec:
      containers:
        - name: kubernetes-example
          volumeMounts:
            - mountPath: /etc/certs
              name: volume-certs
              readOnly: true
      volumes:
        - name: volume-certs
          secret:
            optional: false
            secretName: tls-secret

Securing resources

When securing your resources, it's important to validate that the requests are coming from known hosts. To add these trusted hosts, use the dnsNames property for the certificate configuration. The following line, for example, adds a single hostname to the property:

dekorate.certificate.dnsNames=foo.bar.com

The certificate will then allow only requests for the foo.bar.com server host. Add multiple hosts by separating them with commas.

Note: If the DNS hostname does not exist, you will get an error.

In Kubernetes, you can publicly expose an application using Ingress resources, such as:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: kubernetes-example
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - pathType: Prefix
        path: "/"
        backend:
          service:
            name: kubernetes-example
            port:
              number: 8080
  tls:
    - hosts:
        - foo.bar.com
      secretName: tls-secret # < cert-manager will store the created certificate in this secret.

Dekorate can help you generate the previous Ingress resource definition by adding the following key properties:

dekorate.kubernetes.ingress.host=foo.bar.com
dekorate.kubernetes.ingress.expose=true
dekorate.kubernetes.ingress.tlsSecretName=tls-secret

Configuring HTTPS/TLS with Dekorate cert-manager extension for a Spring Boot application

The example in this section demonstrates how to configure an HTTPS/TLS microservice using the Dekorate cert-manager extension.

Enabling HTTPS transport

To enable the HTTPS/TLS transport in Spring Boot, add the following properties:

server.port=8443
server.ssl.enabled=true

Next, configure the Java PKCS#12 keystore properties that your Spring Boot application will use to get the server certificate signed and obtain the private key:

server.ssl.key-store-type=PKCS12
server.ssl.key-store=/path/to/keystore.p12
server.ssl.key-store-password=the password

Since the keystore file is password protected, you need to create the secret that contains that password. This is where cert-manager comes into play. The following sections illustrate how to instruct cert-manager to generate the keystore and how to configure the application to mount and use the secret.

Generating a self-signed certificate and keystore

You can configure the Dekorate cert-manager extension to request the generation of the keystore.p12 PKCS#12 file and a self-signed certificate by specifying:

dekorate.certificate.secret-name=tls-secret
dekorate.certificate.self-signed.enabled=true
dekorate.certificate.keystores.pkcs12.create=true
# the secret name of the password:
dekorate.certificate.keystores.pkcs12.passwordSecretRef.name=pkcs12-pass 
dekorate.certificate.keystores.pkcs12.passwordSecretRef.key=password

Based on this configuration, Dekorate will create the Certificate and Issuer resources that you can install in Kubernetes. This resource will be used by the Certificate Manager to generate a self-signed certificate and the keystore files within a secret named tls-secret.

To protect the keystore, create a secret named pkcs12-pass in the src/main/resources/k8s/common.yml file. The data field must include the key password which is encoded in base64. The following example, shows the "supersecret" string encoded in base64:

---
apiVersion: v1
kind: Secret
metadata:
  name: pkcs12-pass
data:
  # "supersecret" in base64:
  password: c3VwZXJzZWNyZXQ=
type: Opaque

You can instruct Dekorate to find the common.yml under src/main/resources/ by setting the folder name (eg. k8s) in the dekorate.options.input-path property:

dekorate.options.input-path=k8s

After configuring these details and installing the resources created by Dekorate on the Kubernetes platform, cert-manager will generate the generated PKCS#12 keystore file named keystore.p12 within the tls-secret secret.

The Dekorate cert-manager extension will also configure the Spring Boot application to automatically mount a volume using the tls-secret secret at the path /etc/certs (the path can be specified using the dekorate.certificate.volume-mount-path property). Therefore, you can map the Keystore file and password into the server.ssl.key-store and server.ssl.key-store-password Spring Boot properties:

dekorate.kubernetes.env-vars[0].name=SERVER_SSL_KEY_STORE
dekorate.kubernetes.env-vars[0].value=/etc/certs/keystore.p12
dekorate.kubernetes.env-vars[1].name=SERVER_SSL_KEY_STORE_PASSWORD
dekorate.kubernetes.env-vars[1].secret=pkcs12-pass
dekorate.kubernetes.env-vars[1].value=password

Running the application in Kubernetes

To run this example, you must have access to a Kubernetes cluster and install cert-manager.

Next, generate the manifests and push the application container image to your container registry. This example uses Quay.io as the container registry and user as the group name, but you should substitute the values from your environment:

mvn clean install -Ddekorate.push=true -Ddekorate.docker.registry=quay.io -Ddekorate.docker.group=user

After you execute the previous command, install the generated manifests, which are available at target/classes/META-INF/dekorate/kubernetes.yml:

kubectl apply -f target/classes/META-INF/dekorate/kubernetes.yml

After a few moments, check for the secret resource named tls-secret created by the Cert-Manager in the form of a PKCS#12 keystore file:

kubectl get secret/tls-secret -o yaml | grep keystore.p12

Check the status of your pods using the command:

kubectl get pods -w

If your application is running, the output looks like this:

NAME                                                    READY   STATUS    RESTARTS   AGE
spring-boot-with-certmanager-example-566546987c-nj94n   1/1     Running   0          2m23s

Try out the application by port-forwarding port 8443:

kubectl port-forward spring-boot-with-certmanager-example-566546987c-nj94n 8443:8443

Now if you browse to https://localhost:8443/, you should see Hello world from HTTPS!

Dekorate reduces the complexity of certification management

In this article, you learned how to easily generate cert-manager custom resources using Dekorate, and how to use the generated secret by cert-manager for a Spring Boot application.