Apache Guacamole

Deploy Apache Guacamole on Kubernetes — a clientless remote desktop gateway that allows RDP, VNC, SSH, and Telnet access directly from a web browser with no client installation required.

Key Features

• guacd sidecar — protocol daemon runs alongside the web app, communicating on localhost:4822
• Dual-image architecture — guacamole (Tomcat web app) + guacd (protocol daemon)
• PostgreSQL bundled by default — no extra setup for quick start
• Schema init Job — automatic guacamole_db schema creation on install
• OIDC, SAML, and TOTP — SSO and MFA integrations
• Tomcat reverse proxy — correct client IP via X-Forwarded-For support
• Database-aware backup — pg_dump or mysqldump to S3
• Real listener overrides — configure Tomcat HTTP and guacd process ports independently from the Service
• Immutable official images — Guacamole and guacd 1.6.0 are pinned by multi-architecture digest
• Secure pod defaults — non-root users, read-only filesystems, seccomp, dropped capabilities, and no API token
• Ingress isolation — NetworkPolicy enabled by default

Chart Documentation

• Chart design
• Database configuration
• OIDC with Keycloak
• Backup guide
• External PostgreSQL example

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install guacamole helmforge/guacamole -f values.yaml

OCI registry:

helm install guacamole oci://ghcr.io/helmforgedev/helm/guacamole -f values.yaml

Deployment Examples

# values.yaml — Guacamole with bundled PostgreSQL (default)
# Default credentials: guacadmin / guacadmin — CHANGE IMMEDIATELY after first login

guacd:
  logLevel: info

postgresql:
  enabled: true
  auth:
    database: guacamole_db
    username: guacamole_user
    password: 'strong-db-password'

ingress:
  enabled: true
  ingressClassName: traefik
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: remote.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: guacamole-tls
      hosts:
        - remote.example.com

# values.yaml — Guacamole with OIDC SSO (Keycloak example)
# OIDC replaces local database authentication for login
# redirectUri is auto-detected from ingress if left empty

oidc:
  enabled: true
  authorizationEndpoint: 'https://auth.example.com/realms/myrealm/protocol/openid-connect/auth'
  jwksEndpoint: 'https://auth.example.com/realms/myrealm/protocol/openid-connect/certs'
  issuer: 'https://auth.example.com/realms/myrealm'
  clientId: guacamole
  redirectUri: 'https://remote.example.com/' # auto-detected from ingress if empty
  scope: 'openid email profile'
  usernameClaim: preferred_username
  groupsClaim: groups

totp:
  enabled: true # combine OIDC with TOTP for 2FA on top of SSO

postgresql:
  enabled: true
  auth:
    password: 'strong-db-password'

ingress:
  enabled: true
  ingressClassName: traefik
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: remote.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: guacamole-tls
      hosts:
        - remote.example.com

# values.yaml — Guacamole with SAML SSO
saml:
  enabled: true
  idpMetadataUrl: 'https://auth.example.com/realms/myrealm/protocol/saml/descriptor'
  entityId: 'https://remote.example.com/'
  callbackUrl: 'https://remote.example.com/' # auto-detected from ingress if empty
  strict: true
  groupAttribute: groups

postgresql:
  enabled: true
  auth:
    password: 'strong-db-password'

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: remote.example.com
      paths:
        - path: /
          pathType: Prefix

# values.yaml — Guacamole with external PostgreSQL and S3 backup
postgresql:
  enabled: false

mysql:
  enabled: false

database:
  type: postgresql
  external:
    host: postgres.database.svc.cluster.local
    port: 5432
    name: guacamole_db
    username: guacamole_user
    existingSecret: guacamole-db-credentials
    existingSecretPasswordKey: password

backup:
  enabled: true
  schedule: '0 2 * * *'
  s3:
    endpoint: https://s3.amazonaws.com
    bucket: guacamole-backups
    existingSecret: guacamole-s3-credentials

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: remote.example.com
      paths:
        - path: /
          pathType: Prefix

Application and Service Ports

containerPorts.http configures the real Tomcat HTTP connector through the official image’s supported entrypoint.d startup extension. guacd.port configures both the daemon listener and the web application’s local connection. service.port remains the independent client-facing Kubernetes Service port.

containerPorts:
  http: 18080

guacd:
  port: 14822

service:
  port: 8080

The chart’s k3d validation requires both overridden listeners to become Ready; these settings do not change only Kubernetes metadata.

Configuration Reference

Images

Guacamole

Reverse Proxy

OIDC

SAML

Database and Init Job

Service and Ingress

Backup

Database-aware: pg_dump for PostgreSQL, mysqldump for MySQL.

Security and Operations

The official web and guacd images run as their upstream non-root UIDs. The default pod uses RuntimeDefault seccomp, a read-only root filesystem, no privilege escalation, no Linux capabilities, explicit writable /tmp volumes, and no mounted Kubernetes API token. Keep these defaults unless an audited extension requires a documented exception.

The default NetworkPolicy isolates ingress but leaves egress open because guacd must reach operator-selected remote desktop targets and the web application may contact identity providers. Add ingress-controller peers with networkPolicy.ingressFrom when they are outside the release. Use existing Secrets or External Secrets for production database and backup credentials, and change the default guacadmin password immediately.

kubectl -n <namespace> rollout status deployment/<release>-guacamole
kubectl -n <namespace> logs deployment/<release>-guacamole -c guacamole
kubectl -n <namespace> logs deployment/<release>-guacamole -c guacd
kubectl -n <namespace> get events --sort-by=.lastTimestamp

More Information

• Apache Guacamole Official Documentation
• Apache Guacamole GitHub Repository
• HelmForge Guacamole Chart Source