Deploying Keycloak on Kubernetes

Keycloak manages authentication and access for the Virtana Platform. A Helm chart is the recommended way to install Keycloak on Kubernetes, because it handles the setup for you.

In this setup, you will create a configuration file named keycloak-values.yaml. This file defines the configuration and behavior of the Keycloak service in Kubernetes.

Prepare your environment

Before you begin, make sure you have access to your Kubernetes cluster and that the Helm CLI is installed on your computer. To add the Helm repo, see Add the Virtana Platform Helm repository.

Open your terminal or command prompt and enter the following command to make sure you have the latest information from Virtana:
```
helm repo update
```

Find the most recent version of the Keycloak chart.

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

Create a new YAML file

Create a new file named keycloak-values.yaml in your working directory. This file defines who can log in as an admin and how Keycloak handles security.

Update the placeholder values and sample credentials based on your environment and security requirements.

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:
  image:
    tag: 26.1.4                  
  kcFeatures: "token-exchange"   

  ingress_controller:
    enabled: true

    ## Remove the following 2 lines if SSL is already terminated at the external load balancer
    nginx_ingress:
      tlsSecretName: ops-tls-secret

Use the following tables to understand the settings you need to provide.

Global Configuration

These settings apply to the entire installation.

Field	Description	Default value
`keycloak.image.tag`	The name of the environment where you are deploying.	"app"
`global.machine_type`	The size of the machine. Supported: small, medium, large.	"small"
`global.secret_source`	Where secrets are stored. Supported: valuesfile, none.	"valuesfile"
`global.storageClass`	The storage type for data. If empty, it uses the cluster default.	""

Registry and Admin Credentials

Enter the login details for your container registry and set up your Keycloak admin account.

Field	Description	Sample Value
`DOCKER_SERVER`	The web address for the official Docker Hub registry.	"`https://index.docker.io/v2/`"
`DOCKER_USERNAME`	Your username for the Docker registry.	"username"
`DOCKER_PASSWORD`	Your password for the Docker registry.	"password"
`keycloak.HOSTNAME`	The full web address (FQDN) for your Keycloak service.	<KEYCLOAK_HOSTNAME>
`keycloak.ADMIN_USER`	The username you will use to log into the Keycloak console.	"vpadmin"
`keycloak.ADMIN_PASSWORD`	A strong password for your Keycloak admin account.	"Abcdefgh@123"
`keycloak.PG_ADMIN_USER`	The username you will use to log in if your PostgreSQL admin user is different.	"postgres"
`keycloak.PG_ADMIN_PASSWORD`	A strong password for your PostgreSQL admin account.	"abcdefgh1"
`keycloak.ha_enabled`	Set to true only if you need "High Availability" for extra reliability.	false

Keycloak Image and Features

This section defines which version of Keycloak to run and which special features to turn on.

Field	Description	Default Value
`keycloak.image.tag`	The specific version of the Keycloak software.	26.1.4 or more (latest version)
`keycloak.kcFeatures`	Enables extra Keycloak features as needed.	"token-exchange"
`ingress_controller.enabled`	Enables or disables the Keycloak ingress controller for exposing the Keycloak service externally.	true
`nginx_ingress.tlsSecretName`	Specifies the Kubernetes TLS secret name used by the NGINX ingress for Keycloak HTTPS termination. You can remove this command if SSL is already terminated at the external load balancer.	ops-tls-secret

Deploy Keycloak

You can deploy Keycloak using three ways. Choose the one that matches your environment.

Option A: Helm CLI (best for quick testing)

Use this option to install Keycloak immediately with a single command from your terminal.

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

Option B: Argo CD (best for automation)

Use this option if you manage your cluster with Argo CD. It keeps your deployment in sync with your Git repository. Create a virtana-keycloak-argo.yaml file and include your values in the values section.

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 latest version
      helm:
        releaseName: opscruise-keycloak
        parameters:
          - name: "tags.keycloak"
            value: "true"
        values: |
          <contents of keycloak-values.yaml>
    syncPolicy:
      automated:
        prune: true
        selfHeal: true
      syncOptions:
      - CreateNamespace=true

Option C: Terraform (best for infrastructure as code)

Use this if you manage your entire cloud setup using Terraform. It allows you to treat your Keycloak deployment as a resource in .tf files.

resource "helm_release" "keycloak" {
  create_namespace = true
  chart            = "virtana-co-controller"
  name             = "opscruise-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 Keycloak deployment

When you run the helm upgrade --install command, Helm provides immediate feedback in your terminal. A STATUS: deployed indicates a successful installation. After Helm reports a successful installation, perform the following steps to verify the deployment.

Access the following URL: https://KEYCLOAK_HOSTNAME:443/auth.
Sign in with the Keycloak admin credentials you configured in keycloak-values.yaml.

Confirm that you can access the Keycloak admin console and that the realms, clients, and other configuration elements load correctly.

If you can't access the admin console, check the pod health. Pods are the containers that runs the Keycloak software. Use the following command to see whether they are active:

kubectl get pods -n keycloak

Status	Meaning	Action
`Running`	The software is active.	Check your Ingress or Network settings.
`Pending`	Waiting for resources.	Check if your cluster has enough CPU/RAM or a valid storage class.
`CrashLoopBackOff`	The app started but crashed.	Check the logs using the command: kubectl logs -l app.kubernetes.io/name=keycloak -n keycloak
`ImagePullBackOff`	Cannot download the image.	Verify your `DOCKER_USERNAME` and `DOCKER_PASSWORD`.

Optional: Use a Private Image Registry

If you want to pull images from a private container registry instead of the default public registry, add the following configuration to keycloak-values.yaml under the global section:

global:
  image_registry: example.io

Replace example.io with the hostname of your private image registry.

If your registry requires authentication, create the appropriate image pull secrets in the target namespace.

In this section: