Opstella Keycloak Installation

Opstella Keycloak is a Single-Sign On and User Identity and Access Management System for Opstella.

Installation

The following steps describe how to install Opstella Keycloak on the 🟢 Management cluster, utilizing PostgreSQL (via CloudnativePG) for metadata and SeaweedFS HA for database backups.

1. Connect to 🟢 Management Kubernetes Cluster ; _i.e w/ Kubeconfig File.

   Ensure you have defined and loaded your Global Shell Variables as described in Shell Variables.

   source $HOME/opstella-installation/shell-values/kubernetes/management_cluster.vars.sh

   export KUBECONFIG="$HOME/opstella-installation/kubeconfigs/management_cluster.yaml"

2. Export Required Shell Variables

   Ensure KEYCLOAK_DOMAIN and KEYCLOAK_ADMIN_PASSWORD are defined as per the Shell Variables guide. Additionally, export the following backend-related variables:

   # PostgreSQL Backend Passwords
   export KEYCLOAK_POSTGRES_SUPERUSER_PASSWORD="CHANGEME"
   export KEYCLOAK_POSTGRES_USER_PASSWORD="CHANGEME"
   export SEAWEEDFS_HA_S3_POSTGRES_BACKUP_PASSWORD="CHANGEME" # Match cnpg-backup password from Bootstrap
   
   # Infrastructure Configuration
   # Ensure `K8S_INGRESS_TLS_CERTIFICATE_SECRET_NAME` and `K8S_STORAGECLASS_NAME` are defined as per the [Shell Variables](/install/preparations/setup/shell-variables#%F0%9F%9F%A2-management) guide.

3. Create Namespace for Keycloak

   kubectl create namespace opstella-identity-system

4. Install PostgreSQL Backend (CloudnativePG)

   Apply the PostgreSQL cluster manifest. This instance will store Keycloak’s identity data and configurations.

   cat <<EOF > $HOME/opstella-installation/kubernetes-manifests/keycloak-postgres.yaml
   ---
   # Postgres Superuser (root) Credentials
   apiVersion: v1
   kind: Secret
   type: kubernetes.io/basic-auth
   metadata:
     name: keycloak-postgres-superuser
     namespace: opstella-identity-system
   stringData:
     username: postgres
     password: "${KEYCLOAK_POSTGRES_SUPERUSER_PASSWORD}"
   ---
   # Keycloak Application User Credentials
   apiVersion: v1
   kind: Secret
   type: kubernetes.io/basic-auth
   metadata:
     name: keycloak-postgres-user
     namespace: opstella-identity-system
   stringData:
     username: keycloak
     password: "${KEYCLOAK_POSTGRES_USER_PASSWORD}"
   ---
   # S3 Credentials for Postgres Backups (to SeaweedFS HA)
   apiVersion: v1
   kind: Secret
   type: Opaque
   metadata:
     name: keycloak-postgres-s3-secret
     namespace: opstella-identity-system
   stringData:
     S3_ACCESS_KEY: "postgres-backup"
     S3_SECRET_KEY: "${SEAWEEDFS_HA_S3_POSTGRES_BACKUP_PASSWORD}"
   ---
   apiVersion: barmancloud.cnpg.io/v1
   kind: ObjectStore
   metadata:
     name: keycloak-postgres-backup
     namespace: opstella-identity-system
   spec:
     # This resource defines the backup destination for the Barman Cloud Plugin
     configuration:
       destinationPath: s3://postgres-backups/
       endpointURL: http://seaweedfs-s3.apps-supporting-services.svc:9000
       s3Credentials:
         accessKeyId:
           name: keycloak-postgres-s3-secret
           key: S3_ACCESS_KEY
         secretAccessKey:
           name: keycloak-postgres-s3-secret
           key: S3_SECRET_KEY
       wal:
         compression: gzip
       data:
         compression: gzip
   
     # Retention policy for backups and WALs handled by the plugin
     retentionPolicy: "30d"
   
   ---
   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   metadata:
     name: keycloak-postgres
     namespace: opstella-identity-system
     labels:
       app.kubernetes.io/name: keycloak-postgres
       app.kubernetes.io/part-of: keycloak
   spec:
     instances: 1
   
     # Image configuration (Postgres 15)
     imageName: ghcr.io/cloudnative-pg/postgresql:15
   
     # Enable the Barman Cloud Plugin for backups
     plugins:
       - name: barman-cloud.cloudnative-pg.io
         isWALArchiver: true
         parameters:
           serverName: "keycloak-postgres"
           barmanObjectName: "keycloak-postgres-backup"
   
     # Storage Configuration
     storage:
       size: 1Gi
       storageClass: "${K8S_STORAGECLASS_NAME}"
   
     walStorage:
       size: 1Gi
       storageClass: "${K8S_STORAGECLASS_NAME}"
   
     # Bootstrap Configuration
     bootstrap:
       initdb:
         database: keycloak
         owner: keycloak
         # Secret containing password for the SeaweedFS application user
         secret:
           name: keycloak-postgres-user
   
     # Superuser credentials (root/postgres)
     superuserSecret:
       name: keycloak-postgres-superuser
   
     # Backup Configuration (Barman Cloud Plugin will automatically detect matching ObjectStore)
     backup:
       {}
   
     # Monitoring (disabled for now)
     monitoring:
       enablePodMonitor: false
   
     # Resources
     resources:
       requests:
         memory: "256Mi"
         cpu: "200m"
       limits:
         memory: "1Gi"
         cpu: "1000m"
   
   EOF

   kubectl apply -f keycloak-postgres.yaml

5. Create Keycloak Application Credentials

   Apply the secret containing the Keycloak initial admin password.

   cat <<EOF > $HOME/opstella-installation/kubernetes-manifests/keycloak.yaml
   ---
   apiVersion: v1
   kind: Secret
   type: Opaque
   metadata:
     name: keycloak-credentials
     namespace: opstella-identity-system
   stringData:
     kc-admin-password: "${KEYCLOAK_ADMIN_PASSWORD}"
   EOF

   kubectl apply -f keycloak.yaml

6. Install Opstella Keycloak Helm Release

   Install Keycloak into the opstella-identity-system namespace using the provided values.

   cat <<EOF > $HOME/opstella-installation/helm-values/keycloak-values.yaml
   image:
     ## @param image.registry Keycloak image registry
     registry: asia-southeast1-docker.pkg.dev
     ## @param image.repository Keycloak image repository
     repository: opstella/platform/opstella-keycloak
     ## @param image.tag Keycloak image tag (immutable tags are recommended)
     tag: "24.0.5-otv5.1.0"
     ## @param image.imagePullPolicy Keycloak image pull policy
   
   containerSecurityContext:
     seccompProfile:
       type: RuntimeDefault
   
   keycloak:
     adminUser: admin
     existingSecret: keycloak-credentials
     secretKeys:
       adminPasswordKey: kc-admin-password
     proxyHeaders: xforwarded
     production: true
     httpRelativePath: /
   
   extraEnvVars:
     - name: KEYCLOAK_ADMIN
       value: admin
     - name: KEYCLOAK_ADMIN_PASSWORD
       valueFrom:
         secretKeyRef:
           name: keycloak-credentials
           key: kc-admin-password
   
   database:
     type: postgres
     host: keycloak-postgres-rw.opstella-identity-system.svc
     port: "5432"
     name: keycloak
     existingSecret: keycloak-postgres-user
     secretKeys:
       passwordKey: password
       usernameKey: username
   
   postgres:
     enabled: false
   
   ingress:
     enabled: true
     className: nginx
     annotations:
       nginx.ingress.kubernetes.io/proxy-buffer-size: 128k
       ingress.kubernetes.io/proxy-body-size: 128k
     hosts:
       - host: "${KEYCLOAK_DOMAIN}"
         paths:
           - path: /
             pathType: Prefix
     tls:
       - hosts:
           - "${KEYCLOAK_DOMAIN}"
         secretName: "${K8S_INGRESS_TLS_CERTIFICATE_SECRET_NAME}"
   
   preserveProviders: true
   EOF

   helm upgrade --install keycloak oci://registry-1.docker.io/cloudpirates/keycloak \
       --version 0.13.6 \
       --namespace opstella-identity-system \
       -f $HOME/opstella-installation/helm-values/keycloak-values.yaml

Post-Installation

1. Verify Pod Status

   kubectl get pods -n opstella-identity-system

   💡 All Keycloak components and the PostgreSQL cluster should be Running:

   NAME                                 READY   STATUS    RESTARTS   AGE
   keycloak-0                           1/1     Running   0          ...
   keycloak-postgres-1                  1/1     Running   0          ...

2. Verify Keycloak UI Access

   • Access the Keycloak UI at https://${KEYCLOAK_DOMAIN}.
   • Click on Administration Console.
   • Login with the admin account and the password defined in ${KEYCLOAK_ADMIN_PASSWORD}.