Skip to content
Guacamole icon
v1.7.3App: v1.6.0Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

Apache Guacamole Helm Chart

Deploy Apache Guacamole on Kubernetes — a clientless remote desktop gateway supporting RDP, VNC, SSH, telnet, and Kubernetes.

Features

  • guacd Sidecar — protocol daemon runs as a sidecar container
  • PostgreSQL Subchart — bundled via HelmForge dependency (default)
  • MySQL Subchart — bundled via HelmForge dependency
  • External Database — connect to existing PostgreSQL or MySQL
  • Database Init Job — automatic schema initialization via post-install hook
  • OpenID Connect — SSO with Keycloak, Okta, Azure AD, and others
  • SAML — SSO with any SAML 2.0 identity provider
  • TOTP — two-factor authentication
  • Reverse Proxy — Tomcat RemoteIpValve for proper client IP detection
  • Ingress — TLS with cert-manager
  • S3 Backup — scheduled CronJob with pg_dump or mysqldump
  • Real Port Overrides — Tomcat and guacd process listeners follow chart values
  • Immutable Images — official images pinned by multi-architecture digest
  • Secure Defaults — non-root, read-only filesystems, seccomp, dropped capabilities, and no API token
  • Ingress Isolation — NetworkPolicy enabled by default

Documentation

Security Scan: guacamole

Framework Score
MITRE + NSA + SOC2 78.78788%

Security posture acceptable with operator-provided resource limits, security contexts, and network policy.

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

Quick Start

postgresql:
  auth:
    password: "change-me"

After deploying, access the web interface and log in with guacadmin / guacadmin. Change the default password immediately.

kubectl port-forward svc/<release>-guacamole 8080:80

Examples

Application and Service Ports

containerPorts.http changes the real Tomcat connector through the official image's entrypoint.d extension point. guacd.port is passed to the guacd daemon with -l and is also supplied to the web application. service.port is an independent client-facing port that targets the named http listener.

containerPorts:
  http: 18080

guacd:
  port: 14822

service:
  port: 8080

The custom-ports-values.yaml k3d scenario requires both overridden listeners to become Ready, proving that these settings change the processes themselves.

OIDC with Keycloak

oidc:
  enabled: true
  authorizationEndpoint: https://keycloak.example.com/realms/master/protocol/openid-connect/auth
  jwksEndpoint: https://keycloak.example.com/realms/master/protocol/openid-connect/certs
  issuer: https://keycloak.example.com/realms/master
  clientId: guacamole

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

See OIDC with Keycloak guide for detailed setup instructions.

Values

Common metadata

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Images

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Guacamole

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Database

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

OIDC (OpenID Connect)

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

SAML

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Service & Ingress

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Backup

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Extra

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Architecture

Guacamole runs as a single Deployment with two containers:

  • guacamole — Java/Tomcat web application on port 8080
  • guacd — protocol daemon on port 4822 (sidecar, communicates via localhost)

A post-install Job initializes the database schema. The init job is idempotent and skips schema creation if tables already exist.

Security

The default application pod uses the non-root users defined by the official images, RuntimeDefault seccomp, a read-only root filesystem, no privilege escalation, and no Linux capabilities. Writable /tmp paths are explicit emptyDir volumes. Kubernetes API token mounting is disabled for the Deployment, initialization Job, and backup CronJob.

NetworkPolicy isolates ingress while intentionally leaving egress open for remote desktop targets and identity providers. Add ingress-controller peers to networkPolicy.ingressFrom when they are outside the release. Use existing Secrets or External Secrets for production database and S3 credentials, and change the default guacadmin password immediately.

Operations and Troubleshooting

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

If the web container is not Ready, verify database initialization, the active Tomcat listener, Secret keys, and reverse-proxy headers. If remote sessions fail while the UI works, verify the guacd logs, target DNS/firewall reachability, and that guacd.port is not overridden by guacamole.extraEnv.

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  Client[Browser or ingress controller] --> Service[Guacamole Service]
  Service --> Web[Guacamole and Tomcat]
  Web --> Daemon[guacd sidecar]
  Web --> Database[(PostgreSQL or MySQL)]
  Daemon --> Targets[Remote desktop targets]
  Backup[Optional backup CronJob] --> Database
  Backup --> S3[S3-compatible storage]
Official Contractvalues.schema.json

Guacamole Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

156 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring-Override the chart name used in resource names.

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring-Override the full release name used in resource names.

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Labels added to every resource created by this chart.

Common Annotations(1)

ParameterTypeDefaultDescription
commonAnnotationsobject-Annotations added to every resource created by this chart.

Image(4)

ParameterTypeDefaultDescription
image.repositorystring-Guacamole web application image.
image.tagstring-Image tag (defaults to appVersion).
image.digeststring-Immutable digest for the Guacamole image.
image.pullPolicystring-Image pull policy.
Allowed:AlwaysIfNotPresentNever

Guacd(8)

ParameterTypeDefaultDescription
guacd.image.repositorystring-guacd daemon image.
guacd.image.tagstring-guacd image tag (defaults to appVersion).
guacd.image.digeststring-Immutable digest for the guacd image.
guacd.image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
guacd.portinteger-guacd daemon port.
guacd.logLevelstring-guacd log level (info, debug, warning, error).
Allowed:infodebugwarningerror
guacd.resourcesobject-Resources for the guacd container.
guacd.securityContextobject-Security context for the guacd container.

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Image pull secrets for private registries.

Container Ports(1)

ParameterTypeDefaultDescription
containerPorts.httpinteger-Actual Tomcat HTTP listener port.

Guacamole(2)

ParameterTypeDefaultDescription
guacamole.contextPathstring-Web application context path (use "ROOT" to serve at /).
guacamole.extraEnvarray-Extra environment variables for the Guacamole container.

Proxy(4)

ParameterTypeDefaultDescription
proxy.enabledboolean-Enable Tomcat RemoteIpValve for reverse proxy.
proxy.allowedIpsRegexstring-Trusted proxy IP regex.
proxy.ipHeaderstring-Header for client IP.
proxy.protocolHeaderstring-Header for protocol.

Oidc(11)

ParameterTypeDefaultDescription
oidc.enabledboolean-Enable OpenID Connect authentication.
oidc.authorizationEndpointstring-Authorization endpoint URI.
oidc.jwksEndpointstring-JWKS endpoint URI for token validation.
oidc.issuerstring-Expected token issuer.
oidc.clientIdstring-Client ID.
oidc.redirectUristring-Redirect URI (auto-detected from ingress if empty).
oidc.scopestring-Space-separated scopes.
oidc.usernameClaimstring-JWT claim for username.
oidc.groupsClaimstring-JWT claim for groups.
oidc.allowedClockSkewinteger-Allowed clock skew in seconds.
oidc.maxTokenValidityinteger-Maximum token validity in minutes.

Saml(10)

ParameterTypeDefaultDescription
saml.enabledboolean-Enable SAML authentication.
saml.idpMetadataUrlstring-IdP metadata URL.
saml.idpUrlstring-IdP URL (used if metadata URL unavailable).
saml.entityIdstring-Service provider entity ID.
saml.callbackUrlstring-Callback URL (auto-detected from ingress if empty).
saml.strictboolean-Enforce certificate validation.
saml.debugboolean-Enable debug logging.
saml.compressRequestboolean-Compress requests.
saml.compressResponseboolean-Compress responses.
saml.groupAttributestring-Group attribute name.

Totp(1)

ParameterTypeDefaultDescription
totp.enabledboolean-Enable TOTP two-factor authentication.

Database(10)

ParameterTypeDefaultDescription
database.typestring-Database type: postgresql or mysql.
Allowed:postgresqlmysql
database.waitForConnection.enabledboolean-Chart configuration parameter
database.waitForConnection.resourcesobject-Resources for the `wait-for-db` init container.
database.external.hoststring-Chart configuration parameter
database.external.portstringinteger-Chart configuration parameter
database.external.namestring-Chart configuration parameter
database.external.usernamestring-Chart configuration parameter
database.external.passwordstring-Chart configuration parameter
database.external.existingSecretstring-Existing secret containing the database password.
database.external.existingSecretPasswordKeystring-Key in the existing secret containing the password.

Init Db(2)

ParameterTypeDefaultDescription
initDb.enabledboolean-Run a Job to initialize the database schema on install.
initDb.resourcesobject-Resources for the init job.

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createboolean-Create a ServiceAccount.
serviceAccount.namestring-ServiceAccount name.
serviceAccount.annotationsobject-Annotations for the ServiceAccount.
serviceAccount.automountServiceAccountTokenboolean-Mount the Kubernetes API token into application and job pods.

Service & Networking(3)

ParameterTypeDefaultDescription
service.typestring-Service type.
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger-HTTP service port.
service.annotationsobject-Annotations for the Service.

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledboolean-Enable ingress for Guacamole.
ingress.ingressClassNamestring-Ingress class name (for example: traefik, nginx).
ingress.annotationsobject-Chart configuration parameter
ingress.hostsarray-Ingress hosts.
ingress.tlsarray-Ingress TLS configuration.

Health Probes(18)

ParameterTypeDefaultDescription
probes.startup.enabledboolean-Chart configuration parameter
probes.startup.pathstring-Chart configuration parameter
probes.startup.initialDelaySecondsinteger-Chart configuration parameter
probes.startup.periodSecondsinteger-Chart configuration parameter
probes.startup.timeoutSecondsinteger-Chart configuration parameter
probes.startup.failureThresholdinteger-Chart configuration parameter
probes.liveness.enabledboolean-Chart configuration parameter
probes.liveness.pathstring-Chart configuration parameter
probes.liveness.initialDelaySecondsinteger-Chart configuration parameter
probes.liveness.periodSecondsinteger-Chart configuration parameter
probes.liveness.timeoutSecondsinteger-Chart configuration parameter
probes.liveness.failureThresholdinteger-Chart configuration parameter
probes.readiness.enabledboolean-Chart configuration parameter
probes.readiness.pathstring-Chart configuration parameter
probes.readiness.initialDelaySecondsinteger-Chart configuration parameter
probes.readiness.periodSecondsinteger-Chart configuration parameter
probes.readiness.timeoutSecondsinteger-Chart configuration parameter
probes.readiness.failureThresholdinteger-Chart configuration parameter

Resources(1)

ParameterTypeDefaultDescription
resourcesobject-CPU and memory requests/limits.

Pod Security(1)

ParameterTypeDefaultDescription
podSecurityContextobject-Pod-level security context.

Container Security(1)

ParameterTypeDefaultDescription
securityContextobject-Container-level security context.

Network Policy(2)

ParameterTypeDefaultDescription
networkPolicy.enabledboolean-Create an ingress NetworkPolicy.
networkPolicy.ingressFromarray-Additional peers allowed to reach the HTTP listener.

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Node selector for pod scheduling.

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Tolerations for pod scheduling.

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Affinity rules for pod scheduling.

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Topology spread constraints.

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring-Priority class name.

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger-Grace period for shutdown (seconds).

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Additional labels for the pod.

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Additional annotations for the pod.

Backup(33)

ParameterTypeDefaultDescription
backup.enabledboolean-Enable built-in backup CronJob.
backup.schedulestring-Backup schedule in Cron format.
backup.suspendboolean-Suspend backup execution.
backup.concurrencyPolicystring-CronJob concurrency policy.
Allowed:ForbidReplaceAllow
backup.successfulJobsHistoryLimitinteger-Successful job history retained.
backup.failedJobsHistoryLimitinteger-Failed job history retained.
backup.backoffLimitinteger-Job backoff limit.
backup.archivePrefixstring-Prefix for backup archive names.
backup.resourcesobject-Resources for backup containers.
backup.serviceAccount.createboolean-Chart configuration parameter
backup.serviceAccount.namestring-Chart configuration parameter
backup.serviceAccount.annotationsobject-Chart configuration parameter
backup.serviceAccount.automountServiceAccountTokenboolean-Chart configuration parameter
backup.images.uploader.repositorystring-Chart configuration parameter
backup.images.uploader.tagstring-Chart configuration parameter
backup.images.uploader.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
backup.images.postgresql.repositorystring-Chart configuration parameter
backup.images.postgresql.tagstring-Chart configuration parameter
backup.images.postgresql.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
backup.images.mysql.repositorystring-Chart configuration parameter
backup.images.mysql.tagstring-Chart configuration parameter
backup.images.mysql.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
backup.s3.endpointstring-S3-compatible endpoint URL.
backup.s3.bucketstring-Target bucket name.
backup.s3.prefixstring-Optional prefix inside the bucket.
backup.s3.regionstring-AWS region used by ambient workload identity credentials.
backup.s3.credentialsFromPodIdentityboolean-Use ambient workload identity instead of static S3 credentials.
backup.s3.createBucketIfNotExistsboolean-Create bucket if not exists.
backup.s3.existingSecretstring-Existing secret containing access-key and secret-key.
backup.s3.existingSecretAccessKeyKeystring-Chart configuration parameter
backup.s3.existingSecretSecretKeyKeystring-Chart configuration parameter
backup.s3.accessKeystring-Inline access key.
backup.s3.secretKeystring-Inline secret key.

Extra Init Containers(1)

ParameterTypeDefaultDescription
extraInitContainersarray-Additional init containers for the pod.

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Additional volumes for the pod.

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Additional volume mounts for the container.

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Extra manifests to deploy alongside the chart.

Postgresql(5)

ParameterTypeDefaultDescription
postgresql.enabledboolean-Enable the local PostgreSQL chart.
postgresql.architecturestring-Chart configuration parameter
postgresql.auth.databasestring-Chart configuration parameter
postgresql.auth.usernamestring-Chart configuration parameter
postgresql.auth.passwordstring-Required when using the PostgreSQL subchart.

Mysql(5)

ParameterTypeDefaultDescription
mysql.enabledboolean-Enable the local MySQL chart.
mysql.architecturestring-Chart configuration parameter
mysql.auth.databasestring-Chart configuration parameter
mysql.auth.usernamestring-Chart configuration parameter
mysql.auth.passwordstring-Required when using the MySQL subchart.

External Secrets(7)

ParameterTypeDefaultDescription
externalSecrets.enabledboolean-Enable External Secrets Operator integration
externalSecrets.secretStoreRef.namestring-Chart configuration parameter
externalSecrets.secretStoreRef.kindstring-Chart configuration parameter
Allowed:SecretStoreClusterSecretStore
externalSecrets.refreshIntervalstring-Chart configuration parameter
externalSecrets.creationPolicystring-Chart configuration parameter
Allowed:OwnerMergeNone
externalSecrets.deletionPolicystring-Chart configuration parameter
Allowed:RetainDeleteMerge
externalSecrets.itemsarray-Chart configuration parameter