Configure transport layer security (TLS) certificates

An administrator can configure TLS certificates to secure applications that run on Kubernetes-based clusters. By default, the operator generates certificates. Instead, an administrator can specify certificates for the Route and Service.

By default, the WebSphereLibertyApplication .spec.manageTLS parameter is set to true and the operator attempts to generate certificates and mount them to the pod at /etc/x509/certs. If .spec.expose is set to true, the Route also is configured automatically to enable TLS using reencrypt termination. This configuration ensures end-to-end encryption from an external source to the application or pod.

To change this default configuration, see the following sections.

Attention: If the application CR sets .spec.manageTLS to false, then the operator does not manage the certificate. We must provide our own TLS certificates and configure probes, monitoring, routes, and other parameters.


Generate certificates with certificate manager

Important: When .spec.manageTLS is set to true, the default, certificate manager must be installed on the Kubernetes cluster.

When certificate manager is installed on the cluster, the service certificate is generated with the cert-manager.io/v1Certificate kind. The cert-manager tool enables the operator to automatically provision TLS certificates for pods and routes. Certificates are mounted into containers from a Kubernetes secret so that the certificates are automatically refreshed when they update. For more information about the cert-manager tool, see https://cert-manager.io/.

The operator creates a certificate authority (CA) Issuer instance to be shared by applications within a single namespace. The secret (or issuer) must be created in the same namespace as the WebSphereLibertyApplication. The issuer is used to generate a service certificate for each application that is mounted into the pod. The tls.crt, tls.key, and ca.crt files are mounted to the pod. The TLS_DIR environment variable sets the location. The same secret (or issuer) is used for all instances of the application in the namespace.

By default, the cert-manager certificates requested by Liberty operator are valid for 90 days (duration), but the rotation happens well before that. The default renew-before period is 1/3 of the duration prior to expiry, so the rotation will happen at 60 days by default.

The default 90 days duration can be changed by updating the value of certManagerCertDuration and certManagerCACertDuration in the Operator ConfigMap (global configuration) and must be specified in Go time.Duration string format. The certManagerCertDuration and certManagerCACertDuration fields are the durations before expiry for the cert-manager issued service certificate and CA, respectively. This global configuration applies to all applications managed by Liberty operator.


Generate certificates with certificate manager (existing certificate scenario)

By default, the operator creates its own certificate authority (CA) for issuing service certificates. However, we can use our own CA certificate. To use your CA certificate, create a Kubernetes secret that is named wlo-custom-ca-tls. This secret must contain the CA's tls.crt and tls.key file. After this secret is provided, the operator reissues certificates for the service using the provided CA.

See the following example CA secret: 

    apiVersion: v1
kind: Secret
metadata:
  name: wlo-custom-ca-tls
data:
  tls.crt: >-
    LS0tLS.....
  tls.key: >-
    LS0tL.....
type: kubernetes.io/tls


Generate certificates with certificate manager (custom issuer)

We can provide a custom Issuer (for example, certificate authority (CA), or Vault) for the service certificates.

The issuer must be named wlo-custom-issuer.

See the following example custom issuer: 

    apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: wlo-custom-issuer
spec:
  vault:
    auth:
      tokenSecretRef:
        key: token
        name: vault-token
    path: pki/sign/cert-manager
    server: >-
      https://vault-internal.vault.svc:8201


Generate certificates with Red Hat OpenShift service CA

If the operator runs on Red Hat OpenShift® Container Platform, the operator can automatically generate service certificates with Red Hat OpenShift Service CA.

This method is the default, and is the simplest way to generate certificates if the certificate manager operator is not installed on the cluster.

The tls.crt and tls.key files are mounted to the pod and the TLS_DIR environment variable sets the location. The Red Hat OpenShift CA certificate is in the /var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt file.

If the certificate manager is installed on the cluster, the certificate manager generates service certificates unless otherwise specified by the application. For example, to force use of the Red Hat OpenShift service CA, add an annotation to the application YAML file with .spec.service.annotations. 

    apiVersion: liberty.websphere.ibm.com/v1
kind: WebSphereLibertyApplication
metadata:
  name: my-app
  namespace: my-namespace
spec:
  applicationImage: quay.io/my-repo/my-app:1.0
  manageTLS: true
  expose: true
  service:
    annotations:
      service.beta.openshift.io/serving-cert-secret-name: my-app-svc-tls-ocp
    port: 9443


Specifying certificates for a secret Route and Service

Specify our own certificate for a secret Route with the WebSphereLibertyApplication CR .spec.route.certificateSecretRef parameter. Specify our own certificate for a secret Service with the .spec.service.certificateSecretRef parameter.

The following examples specify certificates for a route.

For .spec.route.certificateSecretRef, replace my-app-rt-tls with the name of a secret containing TLS key, certificate, and CA to use in the route. It can also contain destination CA certificate. 

    apiVersion: liberty.websphere.ibm.com/v1
Kind: WebSphereLibertyApplication
metadata:
  name: my-app
  namespace: test
spec:
  applicationImage: quay.io/my-repo/my-app:1.0
  expose: true
  route:
    host: myapp.example.com
    termination: reencrypt
    certificateSecretRef: my-app-rt-tls
  service:
    port: 9443

The following example manually provides a route secret. For the secret, replace my-app-rt-tls with the name of the secret. For a route, the following keys are valid in the secret.

  • ca.crt
  • destCA.crt
  • tls.crt
  • tls.key 

    kind: Secret
apiVersion: v1
metadata:
  name: my-app-rt-tls
data:
  ca.crt: >-
    Certificate Authority public certificate...(base64)
  tls.crt: >-
    Route public certificate...(base64)
  tls.key: >-
    Route private key...(base64)
  destCA.crt: >-
    Pod/Service certificate Certificate Authority (base64). Might be required when using reencrypt termination policy.
type: kubernetes.io/tls

For an example that uses .spec.route.certificateSecretRef and makes applications available externally, see the .spec.expose examples.