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
secretNameproperty containing the name of the Kubernetes secret resource that will include the files generated by cert-manager. - The
Issuerthat 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.