Keycloak upgrade

Keycloak provides authentication and identity management for the Virtana Platform. Upgrade your Keycloak deployment whenever you upgrade the Virtana Platform to 2026.6.1. This topic describes how to upgrade an existing Keycloak deployment to version 2026.6.1.

Prerequisites

Before you upgrade Keycloak to 2026.6.1, confirm that your environment meets the following requirements:

An existing Keycloak deployment.
A Kubernetes cluster with Helm 3.x installed.
Access to the Virtana Helm repository.
Valid Docker registry credentials.
A DNS record configured for the Keycloak hostname.

What's new in 2026.6.1

Version 2026.6.1 changes how the Keycloak container image is sourced. Review this change before you prepare your values file. The Keycloak container image changes from quay.io/keycloak/keycloak:26.3 to dhi.io/keycloak:26. The chart now defines this image, so you must remove any image tag override from your existing values file.

Prepare the Keycloak values file

Create a file named keycloak-values.yaml, and replace the placeholder values with your environment-specific settings. The following block defines the global environment settings, the Docker registry and admin credentials, and the Keycloak image and features.

global:
  environment: "app"
  machine_type: "small"   
  secret_source: "valuesfile"  
  storageClass: ""  

  dockerRegistryCredentials:  
    DOCKER_SERVER: "https://index.docker.io/v2/"
    DOCKER_USERNAME: "username"
    DOCKER_PASSWORD: "password"

  create_tls_selfsigned_certs:
    keycloak: "true"

  keycloak:
    HOSTNAME: <KEYCLOAK_HOSTNAME>  
    ADMIN_USER: "vpadmin"
    ADMIN_PASSWORD: "P@ssW0rd@123"
    PG_ADMIN_USER: "postgres"
    PG_ADMIN_PASSWORD: "password1"
    ha_enabled: false

  frontend:
    nodeSelector: {}
    tolerations: []

keycloak:
  kcFeatures: "token-exchange"
  ingress_controller:
    enabled: true
  ## Remove the following two lines if SSL is configured on the load balancer
  nginx_ingress:
    tlsSecretName: ops-tls-secret

The following table describes each field in the values file.

Field	Description	Default values
`global.environment`	Identifies the deployment context. Use `"app"` for standard application deployments. This value is referenced by other chart components to apply environment-specific defaults.	String: `"app"`
`global.machine_type`	Sets the resource profile for all Keycloak pods. `"small"` allocates the minimum CPU and memory, suitable for development or low-traffic environments. `"medium"` and `"large"` allocate progressively more resources for production workloads.	String: `"small"` \| `"medium"` \| `"large"`
`global.secret_source`	Controls how Kubernetes secrets are provided. `"valuesfile"` creates secrets from the credentials you supply in this file. `"none"` skips secret creation; use this option when secrets are managed externally (for example, by HashiCorp Vault or a secrets operator).	String: `"valuesfile"` \| `"none"`
`global.storageClass`	Specifies the Kubernetes StorageClass used for persistent volume claims. If left blank, the cluster's default StorageClass is used. Set this value when your cluster has multiple StorageClasses and you need to target a specific one (for example, a high-performance SSD class for the Keycloak database).	String (optional)
`global.dockerRegistryCredentials.DOCKER_SERVER`	The URL of the Docker registry from which Keycloak and supporting images are pulled. Use `https://index.docker.io/v2/` for Docker Hub. If you pull from a private registry, replace this value with your registry URL (see keycloak-upgrade-private-registry).	String (URL)
`global.dockerRegistryCredentials.DOCKER_USERNAME`	The username for authenticating with the Docker registry. The chart uses this credential to create an `imagePullSecret` in the `keycloak` namespace.	String
`global.dockerRegistryCredentials.DOCKER_PASSWORD`	The password or access token for the Docker registry account. Store this value securely. Avoid committing it to source control; consider injecting it at deploy time using a secrets manager or CI/CD variable.	String (sensitive)
`global.create_tls_selfsigned_certs.keycloak`	When set to `"true"`, the chart generates a self-signed TLS certificate for the Keycloak ingress. Use `"false"` when you supply your own certificate (for example, a certificate issued by your organization's certificate authority or by Let's Encrypt).	String: `"true"` \| `"false"`
`global.keycloak.HOSTNAME`	The fully qualified domain name (FQDN) at which Keycloak is reachable, for example `keycloak.example.com`. This value must match the DNS record you configured as a prerequisite. Keycloak uses it to construct redirect URIs for OAuth 2.0 and OpenID Connect flows.	String (FQDN)
`global.keycloak.ADMIN_USER`	The username for the Keycloak master-realm administrator account. Use this credential to sign in to the Keycloak Admin Console and to perform post-deployment configuration. The default value is `vpadmin`.	String
`global.keycloak.ADMIN_PASSWORD`	The password for the Keycloak administrator account. Replace the default value with a strong, unique password before deploying to a production environment. Avoid committing this value to source control.	String (sensitive)
`global.keycloak.PG_ADMIN_USER`	The superuser account name for the PostgreSQL database that Keycloak uses as its backing store. The default value is `postgres`. This account is used by the chart to initialize the Keycloak database schema on first deployment.	String
`global.keycloak.PG_ADMIN_PASSWORD`	The password for the PostgreSQL superuser account. Replace the default value with a strong, unique password. Avoid committing this value to source control.	String (sensitive)
`global.keycloak.ha_enabled`	Enables or disables high-availability (HA) mode for Keycloak. When set to `true`, the chart deploys multiple Keycloak replicas and configures distributed caching (JGroups). Set to `false` for single-instance deployments. HA mode requires additional cluster resources and a multi-node Kubernetes environment.	Boolean: `true` \| `false`
`global.frontend.nodeSelector`	Constrains Keycloak pods to nodes that match the specified labels. For example, `disktype: ssd` schedules pods only on nodes labeled with that key-value pair. Leave as `{}` to allow scheduling on any node.	Map (key-value pairs)
`global.frontend.tolerations`	Allows Keycloak pods to be scheduled on nodes that have matching taints. Use this setting when your cluster uses taints to reserve nodes for specific workloads. Leave as `[]` if no tolerations are required.	Array of toleration objects
`keycloak.kcFeatures`	Enables one or more Keycloak preview or experimental features at startup. The value `"token-exchange"` activates the Token Exchange feature, which the Virtana Platform requires to allow one service to exchange its token for a token scoped to another service. Do not remove this value unless instructed by Virtana support.	String (comma-separated feature names)
`keycloak.ingress_controller.enabled`	When set to `true`, the chart creates a Kubernetes Ingress resource for Keycloak. Set to `false` only if you manage ingress externally (for example, through a service mesh or a cloud load balancer that terminates traffic directly).	Boolean: `true` \| `false`
`keycloak.nginx_ingress.tlsSecretName`	The name of the Kubernetes TLS secret that the NGINX ingress controller uses for HTTPS termination. The default value, `ops-tls-secret`, is the secret created by the chart when `create_tls_selfsigned_certs.keycloak` is `"true"`. If SSL is configured on the load balancer rather than at the ingress layer, remove the `nginx_ingress` block entirely.	String (Kubernetes secret name)

Because the chart now defines the Keycloak image, remove any image tag override from your existing configuration. If your keycloak-values.yaml file contains the following block, delete it before you upgrade. This applies to both Helm-based deployments (keycloak-values.yaml) and OVA-based deployments (templates/keycloak-values.yaml).

  keycloak:
    image:
      tag: xxxx

Deploy the upgrade

Keycloak upgrades follow the same procedure as the initial deployment. Update the chart to the target version, then redeploy using Helm, Argo CD, or Terraform.

Before you begin, update the Helm repository and check the latest version of the virtana-repo/virtana-co-controller chart:

helm repo update
helm search repo virtana-repo/virtana-co-controller

Warning

If the Helm release name was previously set to opscruise-keycloak, reuse the same release name during the upgrade. Using a different name creates a new release and can disrupt the existing deployment.

Choose one of the following deployment methods.

Helm CLI

To upgrade Keycloak with the Helm CLI, run the following command. Replace <LATEST_VERSION> with the chart version you confirmed earlier.

helm upgrade --install virtana-keycloak virtana-repo/virtana-co-controller \
  --namespace keycloak --create-namespace \
  --set tags.keycloak=true -f keycloak-values.yaml \
  --version <LATEST_VERSION>

Argo CD

To upgrade Keycloak with Argo CD, apply the following Application manifest. Replace <LATEST_VERSION> with the target chart version, and replace <contents of keycloak-values.yaml> with your prepared values file.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: virtana-keycloak
  namespace: argocd
  finalizers:
  - resources-finalizer.argocd.argoproj.io
spec:
  destination:
    server: "https://kubernetes.default.svc"
    namespace: keycloak
  source:
    chart: virtana-co-controller
    repoURL: "https://virtana.gitlab.io/helm-charts"
    targetRevision: <LATEST_VERSION>  # Provide the latest chart version
    helm:
      releaseName: virtana-keycloak
      parameters:
        - name: "tags.keycloak"
          value: "true"
      values: |
        <contents of keycloak-values.yaml>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

Terraform

To upgrade Keycloak with Terraform, apply the following helm_release resource. The version value references your Helm version variable, and the templatefile block supplies your environment-specific values.

resource "helm_release" "keycloak" {
  create_namespace = true
  chart            = "virtana-co-controller"
  name             = "virtana-keycloak"
  namespace        = "keycloak"
  repository       = "https://virtana.gitlab.io/helm-charts"
  version          = var.helm_version
  timeout          = 600
  wait             = true
  values = [
    templatefile("${path.module}/../charts/keycloak-values.yaml", {
      docker_password      = var.docker_password
      docker_username      = var.docker_username
      keycloak_hostname    = var.keycloak_hostname
      keycloak_password    = var.keycloak_password
      keycloak_username    = var.keycloak_username
      db_keycloak_username = var.db_keycloak_username
      db_keycloak_password = var.db_keycloak_password
    })
  ]

  set {
    name  = "tags.keycloak"
    value = "true"
  }
}

Verify the upgrade

To confirm that Keycloak is available after the upgrade, complete the following steps:

In a browser, go to https://<KEYCLOAK_HOSTNAME>:443/auth.
Sign in with your Keycloak admin credentials.
If the Admin Console loads successfully, the upgrade is complete.

Use a private image registry (optional)

To pull the Keycloak image from a private registry, add the following block to keycloak-values.yaml. Replace example.io with your registry hostname.

global:
  image_registry: example.io

In this section: