Example Keycloak

This guide details the deployment of our pre-configured Keycloak SSO server using ArgoCD. This component handles authentication for the SENSE platform and requires specific database and ingress configurations.

1. Environment Dependencies

The following resources must exist in the target namespace (sense) before syncing the application. For more information about chart usage, read the chart readme using helm show readme sense-helm/sense-keycloak.

Required Secrets

• regcred: Credentials for pulling the virnao/stackv-keycloak image.
• test-kc-auth: Contains the initial admin credentials for Keycloak.
  • Expected key: admin-password (Standard Keycloak chart requirement).
• test-keycloak-psql-auth: Credentials for the PostgreSQL database connection.
  • Expected keys: postgres-password (or similar, depending on the bundled Postgres sub-chart).

Infrastructure Requirements

• Cert-Manager: The ingress configuration relies on a ClusterIssuer named le-stackv-cluster. Ensure this resource exists in the cluster.

3.Application Manifest

The configuration uses Helm value substitution to dynamically set hostnames based on the global domain.

File: argocd/keycloak-application.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: new-keycloak
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://stackv.github.io/sense-helm/
    chart: sense-keycloak
    targetRevision: 0.8.0
    helm:
      valuesObject:
        global:
          domain: dev3.virnao.com
        namespaceOverride: sense
        ingress:
          annotations:
            # Ensures TLS certificates are provisioned via Let's Encrypt
            cert-manager.io/cluster-issuer: le-stackv-cluster
          # Dynamic Hostnames:
          # Console: new-kc.dev3.virnao.com
          # Auth API: new-auth.dev3.virnao.com
          hostname: new-kc.{{ .Values.global.domain }}
          authHostname: new-auth.{{ .Values.global.domain }}
        postgres:
          database: bitnami_keycloak
          secret: test-keycloak-psql-auth
        keycloak:
          externalDatabase:
            existingSecret: test-keycloak-psql-auth
          image:
            repository: virnao/stackv-keycloak
            tag: preview
            pullPolicy: Always
            pullSecrets:
              - regcred
          auth:
            adminUser: tempadmin
            existingSecret: test-kc-auth
  destination:
    server: https://kubernetes.default.svc
    # Note: Deployment targets the 'sense' namespace
    namespace: sense
  syncPolicy:
    syncOptions:
      - CreateNamespace=true

4. Setup & Deployment Procedures

4.1 Registering the Application

Apply the manifest to the ArgoCD control plane.

kubectl apply -f argocd/keycloak-application.yaml -n argocd

4.2 Verifying Ingress & TLS

Keycloak is highly sensitive to correct hostname configuration. After the sync completes:

1. Check Ingress Status:

kubectl get ingress -n sense

Ensure the ADDRESS field is populated (LoadBalancer IP).

2. Verify Certificate Issuance:

kubectl get certificate -n sense

Ensure the certificates for new-kc.dev3.virnao.com and new-auth.dev3.virnao.com state Ready: True.

4.3 Initial Access

1. Navigate to https://new-kc.dev3.virnao.com.
2. Click Administration Console.
3. Log in using:

• Username: tempadmin (as defined in keycloak.auth.adminUser).
• Password: The value inside the test-kc-auth secret.

5. Operational Notes

• Image Tag: The manifest uses tag: preview with pullPolicy: Always. This is a moving target. For production stability, pin this to a specific version number.
• Database Connectivity: If the Keycloak pod is in CrashLoopBackOff, it is likely unable to connect to Postgres. Verify the test-keycloak-psql-auth secret exists in the sense namespace and contains the correct credentials.
• Namespace Isolation: Unlike the Orchestrator (which deployed to default in the previous example), Keycloak deploys to sense. Ensure you are checking the correct namespace when debugging.