ln/

Keycloak deployen op GKE met een custom Helm chart

In deze guide leer je hoe je Keycloak deployt op Google Kubernetes Engine (GKE) met:

  • Een Chart.yaml waarin de dependencies staan (Bitnami Keycloak),
  • values.yaml voor de configuratie,
  • ingress.yaml om te bepalen hoe verkeer je cluster binnenkomt,
  • managed-cert.yaml voor een SSL-certificaat dat door GKE wordt beheerd,
  • keycloak-argo.yaml voor geautomatiseerde GitOps via Argo CD (optioneel).

1. Vereisten

  1. GKE-cluster

    • Je hebt een werkend GKE-cluster nodig. Controleer of kubectl ernaar wijst:
    kubectl config get-contexts

  2. Helm (v3+)

    • Controleer of Helm geïnstalleerd is:
    helm version

  3. Bastion host (indien nodig)

    • Is je cluster privé? Controleer dan of je via SSH op een bastion host kunt komen die toegang heeft tot het cluster.

  4. Argo CD (optioneel)

    • Wil je deployments automatiseren, zorg dan dat Argo CD in het cluster geïnstalleerd is.

  5. Gereserveerd statisch IP (optioneel)

    • Overweeg om in GCP een globaal statisch IP te reserveren, zodat je altijd hetzelfde externe IP hebt.

2. Structuur van de chart

Hieronder zie je een gangbare structuur voor je custom Keycloak chart. Zet deze bestanden in een map (bijvoorbeeld keycloak/) in je Git repository:

keycloak/
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── ingress.yaml
│   ├── managed-cert.yaml
│   └── _other_templates_.yaml
├── keycloak-argo.yaml
└── README.md (optional)

Je kunt keycloak-argo.yaml in de root van je repo zetten of naast de bestanden van je chart.

3. Chart.yaml

Doel: definieert de naam, versie, beschrijving en dependencies van je Helm chart.

Bekijk de Chart.yaml-configuratie
apiVersion: v2
name: keycloak
description: A wrapper chart for Bitnami Keycloak
version: 0.1.0
appVersion: "24.4.10"
dependencies:
  - name: keycloak
    version: "24.4.10"
    repository: "https://charts.bitnami.com/bitnami"

Belangrijkste punten:

  • apiVersion: v2 is verplicht voor Helm 3.
  • dependencies: verwijst naar de Bitnami Keycloak chart en de versie daarvan.
  • name, version en appVersion kun je aanpassen naar wat je nodig hebt.

Als je helm dependency update uitvoert in de map van deze chart, haalt Helm de Bitnami Keycloak chart op uit de opgegeven repository.

4. values.yaml

Doel: bevat de belangrijkste configuratie voor Keycloak, de database en de resources. Deze waarden overschrijven of vullen de defaults van de Bitnami chart aan.

Bekijk de values.yaml-configuratie
keycloak:
  # Enable production mode
  production: true
 
  # TLS Configuration
  tls:
    enabled: true
    autoGenerated: true
 
  # Configure proxy settings for edge termination
  proxy: edge
  httpRelativePath: /
 
  # Pod configuration
  replicaCount: 1
  resources:
    requests:
      memory: 256Mi
      cpu: 250m
    limits:
      memory: 512Mi
      cpu: 500m
  persistence:
    enabled: true
    storageClass: "standard"
    accessModes:
      - ReadWriteOnce
    size: 8Gi
 
  # Configure authentication
  auth:
    adminUser: admin
    adminPassword: "mySecureAdminPassword"
 
  # Extra environment variables
  extraEnvVars:
    - name: KC_HOSTNAME
      value: "keycloak.mydomain.com"
    - name: KC_HOSTNAME_STRICT
      value: "true"
    - name: KC_HOSTNAME_STRICT_HTTPS
      value: "true"
    - name: KC_PROXY
      value: "edge"
    - name: KEYCLOAK_LOG_LEVEL
      value: DEBUG
 
  # Ingress configuration (used by our custom template)
  ingress:
    enabled: false # Disabled because we use a custom Ingress template
    hostname: keycloak.mydomain.com
 
  postgresql:
    enabled: true
    auth:
      postgresPassword: "postgrespassword"
      username: keycloak
      password: "keycloakpassword"
      database: keycloak_db
    persistence:
      enabled: true
      storageClass: "standard"
      accessModes:
        - ReadWriteOnce
      size: 8Gi

Belangrijkste punten:

  • production: true: schakelt strengere beveiligingsinstellingen in.
  • proxy: edge: configureert Keycloak voor SSL die aan de edge wordt getermineerd.
  • auth.adminPassword: moet je aanpassen voordat je naar productie gaat.
  • postgresql.enabled: true: deployt een interne PostgreSQL-instantie met persistente opslag.
  • ingress.enabled: false: omdat we de Ingress-resource in een apart template-bestand (ingress.yaml) definiëren, schakelen we de standaard ingress van Bitnami Keycloak uit.

5. ingress.yaml

In een typische Helm chart zet je dit bestand onder templates/ingress.yaml.

Bekijk de ingress.yaml-configuratie
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ .Release.Name }}-ingress
  namespace: {{ .Release.Namespace }}
  annotations:
    kubernetes.io/ingress.class: "gce"
    kubernetes.io/ingress.global-static-ip-name: "keycloak-global-ip"
    networking.gke.io/managed-certificates: {{ .Release.Name }}-cert
    # Temporarily allow HTTP while certificate is provisioning
    kubernetes.io/ingress.allow-http: "true"
spec:
  ingressClassName: gce
  rules:
    - host: {{ .Values.keycloak.ingress.hostname }}
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: {{ .Release.Name }}
                port:
                  number: 80

Belangrijkste punten:

  • kubernetes.io/ingress.class: "gce": gebruikt Google Cloud Load Balancing.
  • kubernetes.io/ingress.global-static-ip-name: vul hier de naam van je statische IP in (als je er een hebt gereserveerd).
  • allow-http: "true": laat HTTP-verkeer door zolang het SSL-certificaat nog niet klaar is. Je kunt dit later verwijderen of aanpassen.

6. managed-cert.yaml

Staat ook in templates/ (bijvoorbeeld templates/managed-cert.yaml). Deze resource vraagt een SSL-certificaat voor je domein aan en beheert het.

Bekijk de managed-cert.yaml-configuratie
apiVersion: networking.gke.io/v1
kind: ManagedCertificate
metadata:
  name: {{ .Release.Name }}-cert
  namespace: {{ .Release.Namespace }}
spec:
  domains:
    - {{ .Values.keycloak.ingress.hostname }}

Belangrijkste punten:

  • domains: moet overeenkomen met het domein in de Ingress host.
  • Het kan tot 30 minuten duren voordat GCP het certificaat uitgeeft en activeert.

7. keycloak-argo.yaml (optioneel)

Wil je een GitOps-aanpak met Argo CD, dan kun je een Argo CD Application definiëren die naar deze Helm chart verwijst. Je kunt het bestand in de root van je repo zetten of in de map keycloak/.

Bekijk de keycloak-argo.yaml-configuratie
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: keycloak
  namespace: argocd
spec:
  project: default
  source:
    repoURL: "[email protected]:my-org/keycloak.git"
    path: "."
    targetRevision: HEAD
  destination:
    server: "https://kubernetes.default.svc"
    namespace: keycloak
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Belangrijkste punten:

  • repoURL: zet dit op je eigen repository.
  • path: staat je chart in een submap (bijvoorbeeld keycloak/), pas dit dan aan.
  • prune en selfHeal: zorgen ervoor dat je cluster altijd in sync blijft met Git.

8. Deployen

8.1 (optioneel) Dependencies voorbereiden

Heb je dependencies gedefinieerd in Chart.yaml (zoals Bitnami Keycloak), voer dan dit uit:

helm dependency update path/to/keycloak/

Dit downloadt de Bitnami Keycloak chart lokaal, zodat Helm hem kan samenvoegen met je wrapper.

8.2 Met de Helm CLI

Deploy je handmatig:

helm upgrade --install keycloak path/to/keycloak/ \
  --namespace keycloak \
  --create-namespace

Helm rendert Chart.yaml, values.yaml en alles onder templates/.

8.3 Met Argo CD

  1. Push je wijzigingen naar Git
    Commit en push je chart-bestanden (Chart.yaml, values.yaml, templates/, enzovoort) samen met keycloak-argo.yaml.
  2. Argo CD sync
    • Forward Argo CD indien nodig: 
      kubectl port-forward svc/argocd-server -n argocd 8081:443
    • Ga naar https://localhost:8081 en zoek de applicatie keycloak. Argo CD synct automatisch, of je klikt zelf op "Sync" om te deployen.

9. Controles na de deployment

  1. Pods:

    kubectl get pods -n keycloak
    • Controleer of de Keycloak- en PostgreSQL-pods de status "Running" hebben.

  2. Ingress:

    kubectl get ingress -n keycloak
    • Zodra de load balancer is opgezet, verschijnt er een extern IP.

  3. Managed Certificate:

    kubectl describe managedcertificate -n keycloak
    • Wacht op "Active" voordat HTTPS volledig werkt.

  4. Test in de browser:

    • Ga naar https://keycloak.mydomain.com (of welk domein je ook hebt ingesteld).
    • Je zou nu het inlogscherm van Keycloak moeten zien.

10. Tips voor troubleshooting

  • Certificaat wordt nog aangemaakt
    • Dit kan tot 30 minuten duren. Controleer of je DNS-record naar het externe IP wijst.
  • Pods crashen of falen 
    kubectl logs -n keycloak -l app.kubernetes.io/name=keycloak
    • Kijk of er problemen zijn zoals verkeerde database-credentials of te weinig geheugen.
  • Fouten in Argo CD
    • Bekijk de "Events" of de details van de "Application" in de Argo CD UI.
    • Controleer of je repoURL, path en de verwijzingen in Chart.yaml kloppen.
  • Ingress resolvet niet
    • Controleer of de DNS van je domein naar het externe IP van de Ingress wijst.
    • Gebruik je een statisch IP, controleer dan of de naam overeenkomt met kubernetes.io/ingress.global-static-ip-name.

11. Best practices voor beveiliging

  1. Gebruik veilige wachtwoorden
    • Pas keycloak.auth.adminPassword en de database-credentials aan voordat je naar productie gaat.
  2. Productiemodus
    • Laat production: true staan om strengere beveiligingsinstellingen af te dwingen.
  3. TLS
    • Gebruik extern door GKE beheerde certificaten en intern automatisch gegenereerde self-signed certificaten, zodat alles end-to-end versleuteld is.
  4. Argo CD prune en self-heal
    • Test wijzigingen eerst in een staging-omgeving. Deze features kunnen onverwacht resources verwijderen of handmatige aanpassingen terugdraaien als je daar niet op voorbereid bent.