Upgrade from 3.x to 4.x

This guide describes the steps to perform an upgrade of the component from version 3.x to 4.x.

The major changes affect the ingress feature and configuration. This component now features re-encrypted ingress by default. That means traffic between the ingress controller and Keycloak is now encrypted.

Step-by-step guide

  1. Decide where you want to terminate user traffic. You can either terminate the TLS session at the ingress controller and re-encrypt traffic to Keycloak. Or you can pass-through the TLS traffic directly to Keycloak, provided the ingress controller supports TLS pass-through.

  2. Decide how you aim to provision and rotate TLS certificates. The cert-manager operator provides easy Let’s Encrypt certificate provisioning by default. You can also provision your own CA issued certificate.

The sections below explain more.

Changed parameters

  • ingress.secretName has moved to ingress.tls.secretName.

  • ingress.enabled changed to true by default.

  • ingress.annotations received several annotations depending on tls.provider and tls.termination.

  • helm_values.extraVolumes and helm_values.extraVolumeMounts got an additional volume/mount from the tls.secretName secret.

  • helm_values.ingress.servicePort changed to https by default.

You might need to update your configuration if you’ve configured some of them.

Re-encrypted TLS with Let’s Encrypt

User traffic > Ingress controller (LE certificate) > Re-encrypt with self-signed certificate > Keycloak

This mode is the default in v4.x.

  1. Generate new long-running self-signed certificate and store in Vault.

Re-encrypted TLS with CA issued certificate

User traffic > Ingress controller (own certificate) > Re-encrypt with self-signed certificate > Keycloak

  1. Set the provider

    parameters:
  keycloak:
    tls:
      provider: vault

  2. Generate new long-running self-signed certificate and store in Vault.

Pass-through TLS with Let’s Encrypt

User traffic > Ingress controller (pass-through) > Keycloak (with LE certificate)

This mode requires an ingress controller that supports SSL/TLS pass-through. See Configure Ingress for an example with component-ingress-nginx.

  1. Set the termination

    parameters:
  keycloak:
    tls:
      termination: passthrough

You need to restart Keycloak every time Let’s Encrypt updates the certificate. Keycloak doesn’t reload the certificate from the mounted secret.

Pass-through TLS with CA issued certificate

User traffic > Ingress controller (pass-through) > Keycloak (with own certificate)

This mode requires an ingress controller that supports SSL/TLS pass-through.

  1. Set the termination and provider

    parameters:
  keycloak:
    tls:
      termination: passthrough
      provider: vault

  2. Store your certificate in Vault.