Configuring transport layer security (TLS) certificates

Generating certificates with certificate manager

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.

You can add annotations to the service certificates by using the .spec.service.certificate.annotations parameter.

Generating certificates with certificate manager (existing certificate scenario)

By default, the operator creates its own certificate authority (CA) for issuing service certificates. However, you can use your 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 by 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

Generating certificates with certificate manager (custom issuer)

You 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

Generating 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 your own certificate for a secret Route with the WebSphereLibertyApplication CR .spec.route.certificateSecretRef parameter. Specify your 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 that contains 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.