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
- Simple bundled PostgreSQL
- Production ingress, OIDC, and backups
- External PostgreSQL
- OIDC with Keycloak
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
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.
Images
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.
Guacamole
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.
Database
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.
OIDC (OpenID Connect)
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.
SAML
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.
Service & Ingress
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.
Backup
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.
Extra
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.
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 SyncedVerified 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]
Guacamole Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Global settings shared by the chart. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | - | Override the chart name used in resource names. |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | - | Override the full release name used in resource names. |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Labels added to every resource created by this chart. |
Common Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonAnnotations | object | - | Annotations added to every resource created by this chart. |
Image(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | - | Guacamole web application image. |
| image.tag | string | - | Image tag (defaults to appVersion). |
| image.digest | string | - | Immutable digest for the Guacamole image. |
| image.pullPolicy | string | - | Image pull policy. Allowed: AlwaysIfNotPresentNever |
Guacd(8)
| Parameter | Type | Default | Description |
|---|---|---|---|
| guacd.image.repository | string | - | guacd daemon image. |
| guacd.image.tag | string | - | guacd image tag (defaults to appVersion). |
| guacd.image.digest | string | - | Immutable digest for the guacd image. |
| guacd.image.pullPolicy | string | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
| guacd.port | integer | - | guacd daemon port. |
| guacd.logLevel | string | - | guacd log level (info, debug, warning, error). Allowed: infodebugwarningerror |
| guacd.resources | object | - | Resources for the guacd container. |
| guacd.securityContext | object | - | Security context for the guacd container. |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Image pull secrets for private registries. |
Container Ports(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| containerPorts.http | integer | - | Actual Tomcat HTTP listener port. |
Guacamole(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| guacamole.contextPath | string | - | Web application context path (use "ROOT" to serve at /). |
| guacamole.extraEnv | array | - | Extra environment variables for the Guacamole container. |
Proxy(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| proxy.enabled | boolean | - | Enable Tomcat RemoteIpValve for reverse proxy. |
| proxy.allowedIpsRegex | string | - | Trusted proxy IP regex. |
| proxy.ipHeader | string | - | Header for client IP. |
| proxy.protocolHeader | string | - | Header for protocol. |
Oidc(11)
| Parameter | Type | Default | Description |
|---|---|---|---|
| oidc.enabled | boolean | - | Enable OpenID Connect authentication. |
| oidc.authorizationEndpoint | string | - | Authorization endpoint URI. |
| oidc.jwksEndpoint | string | - | JWKS endpoint URI for token validation. |
| oidc.issuer | string | - | Expected token issuer. |
| oidc.clientId | string | - | Client ID. |
| oidc.redirectUri | string | - | Redirect URI (auto-detected from ingress if empty). |
| oidc.scope | string | - | Space-separated scopes. |
| oidc.usernameClaim | string | - | JWT claim for username. |
| oidc.groupsClaim | string | - | JWT claim for groups. |
| oidc.allowedClockSkew | integer | - | Allowed clock skew in seconds. |
| oidc.maxTokenValidity | integer | - | Maximum token validity in minutes. |
Saml(10)
| Parameter | Type | Default | Description |
|---|---|---|---|
| saml.enabled | boolean | - | Enable SAML authentication. |
| saml.idpMetadataUrl | string | - | IdP metadata URL. |
| saml.idpUrl | string | - | IdP URL (used if metadata URL unavailable). |
| saml.entityId | string | - | Service provider entity ID. |
| saml.callbackUrl | string | - | Callback URL (auto-detected from ingress if empty). |
| saml.strict | boolean | - | Enforce certificate validation. |
| saml.debug | boolean | - | Enable debug logging. |
| saml.compressRequest | boolean | - | Compress requests. |
| saml.compressResponse | boolean | - | Compress responses. |
| saml.groupAttribute | string | - | Group attribute name. |
Totp(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| totp.enabled | boolean | - | Enable TOTP two-factor authentication. |
Database(10)
| Parameter | Type | Default | Description |
|---|---|---|---|
| database.type | string | - | Database type: postgresql or mysql. Allowed: postgresqlmysql |
| database.waitForConnection.enabled | boolean | - | Chart configuration parameter |
| database.waitForConnection.resources | object | - | Resources for the `wait-for-db` init container. |
| database.external.host | string | - | Chart configuration parameter |
| database.external.port | stringinteger | - | Chart configuration parameter |
| database.external.name | string | - | Chart configuration parameter |
| database.external.username | string | - | Chart configuration parameter |
| database.external.password | string | - | Chart configuration parameter |
| database.external.existingSecret | string | - | Existing secret containing the database password. |
| database.external.existingSecretPasswordKey | string | - | Key in the existing secret containing the password. |
Init Db(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| initDb.enabled | boolean | - | Run a Job to initialize the database schema on install. |
| initDb.resources | object | - | Resources for the init job. |
Service Account(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | - | Create a ServiceAccount. |
| serviceAccount.name | string | - | ServiceAccount name. |
| serviceAccount.annotations | object | - | Annotations for the ServiceAccount. |
| serviceAccount.automountServiceAccountToken | boolean | - | Mount the Kubernetes API token into application and job pods. |
Service & Networking(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | - | Service type. Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | - | HTTP service port. |
| service.annotations | object | - | Annotations for the Service. |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | - | Enable ingress for Guacamole. |
| ingress.ingressClassName | string | - | Ingress class name (for example: traefik, nginx). |
| ingress.annotations | object | - | Chart configuration parameter |
| ingress.hosts | array | - | Ingress hosts. |
| ingress.tls | array | - | Ingress TLS configuration. |
Health Probes(18)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.startup.enabled | boolean | - | Chart configuration parameter |
| probes.startup.path | string | - | Chart configuration parameter |
| probes.startup.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.startup.periodSeconds | integer | - | Chart configuration parameter |
| probes.startup.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.startup.failureThreshold | integer | - | Chart configuration parameter |
| probes.liveness.enabled | boolean | - | Chart configuration parameter |
| probes.liveness.path | string | - | Chart configuration parameter |
| probes.liveness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.liveness.periodSeconds | integer | - | Chart configuration parameter |
| probes.liveness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.liveness.failureThreshold | integer | - | Chart configuration parameter |
| probes.readiness.enabled | boolean | - | Chart configuration parameter |
| probes.readiness.path | string | - | Chart configuration parameter |
| probes.readiness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.readiness.periodSeconds | integer | - | Chart configuration parameter |
| probes.readiness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.readiness.failureThreshold | integer | - | Chart configuration parameter |
Resources(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources | object | - | CPU and memory requests/limits. |
Pod Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext | object | - | Pod-level security context. |
Container Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext | object | - | Container-level security context. |
Network Policy(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| networkPolicy.enabled | boolean | - | Create an ingress NetworkPolicy. |
| networkPolicy.ingressFrom | array | - | Additional peers allowed to reach the HTTP listener. |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Node selector for pod scheduling. |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Tolerations for pod scheduling. |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Affinity rules for pod scheduling. |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Topology spread constraints. |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | - | Priority class name. |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | - | Grace period for shutdown (seconds). |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Additional labels for the pod. |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Additional annotations for the pod. |
Backup(33)
| Parameter | Type | Default | Description |
|---|---|---|---|
| backup.enabled | boolean | - | Enable built-in backup CronJob. |
| backup.schedule | string | - | Backup schedule in Cron format. |
| backup.suspend | boolean | - | Suspend backup execution. |
| backup.concurrencyPolicy | string | - | CronJob concurrency policy. Allowed: ForbidReplaceAllow |
| backup.successfulJobsHistoryLimit | integer | - | Successful job history retained. |
| backup.failedJobsHistoryLimit | integer | - | Failed job history retained. |
| backup.backoffLimit | integer | - | Job backoff limit. |
| backup.archivePrefix | string | - | Prefix for backup archive names. |
| backup.resources | object | - | Resources for backup containers. |
| backup.serviceAccount.create | boolean | - | Chart configuration parameter |
| backup.serviceAccount.name | string | - | Chart configuration parameter |
| backup.serviceAccount.annotations | object | - | Chart configuration parameter |
| backup.serviceAccount.automountServiceAccountToken | boolean | - | Chart configuration parameter |
| backup.images.uploader.repository | string | - | Chart configuration parameter |
| backup.images.uploader.tag | string | - | Chart configuration parameter |
| backup.images.uploader.pullPolicy | string | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
| backup.images.postgresql.repository | string | - | Chart configuration parameter |
| backup.images.postgresql.tag | string | - | Chart configuration parameter |
| backup.images.postgresql.pullPolicy | string | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
| backup.images.mysql.repository | string | - | Chart configuration parameter |
| backup.images.mysql.tag | string | - | Chart configuration parameter |
| backup.images.mysql.pullPolicy | string | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
| backup.s3.endpoint | string | - | S3-compatible endpoint URL. |
| backup.s3.bucket | string | - | Target bucket name. |
| backup.s3.prefix | string | - | Optional prefix inside the bucket. |
| backup.s3.region | string | - | AWS region used by ambient workload identity credentials. |
| backup.s3.credentialsFromPodIdentity | boolean | - | Use ambient workload identity instead of static S3 credentials. |
| backup.s3.createBucketIfNotExists | boolean | - | Create bucket if not exists. |
| backup.s3.existingSecret | string | - | Existing secret containing access-key and secret-key. |
| backup.s3.existingSecretAccessKeyKey | string | - | Chart configuration parameter |
| backup.s3.existingSecretSecretKeyKey | string | - | Chart configuration parameter |
| backup.s3.accessKey | string | - | Inline access key. |
| backup.s3.secretKey | string | - | Inline secret key. |
Extra Init Containers(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraInitContainers | array | - | Additional init containers for the pod. |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Additional volumes for the pod. |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Additional volume mounts for the container. |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Extra manifests to deploy alongside the chart. |
Postgresql(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| postgresql.enabled | boolean | - | Enable the local PostgreSQL chart. |
| postgresql.architecture | string | - | Chart configuration parameter |
| postgresql.auth.database | string | - | Chart configuration parameter |
| postgresql.auth.username | string | - | Chart configuration parameter |
| postgresql.auth.password | string | - | Required when using the PostgreSQL subchart. |
Mysql(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| mysql.enabled | boolean | - | Enable the local MySQL chart. |
| mysql.architecture | string | - | Chart configuration parameter |
| mysql.auth.database | string | - | Chart configuration parameter |
| mysql.auth.username | string | - | Chart configuration parameter |
| mysql.auth.password | string | - | Required when using the MySQL subchart. |
External Secrets(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalSecrets.enabled | boolean | - | Enable External Secrets Operator integration |
| externalSecrets.secretStoreRef.name | string | - | Chart configuration parameter |
| externalSecrets.secretStoreRef.kind | string | - | Chart configuration parameter Allowed: SecretStoreClusterSecretStore |
| externalSecrets.refreshInterval | string | - | Chart configuration parameter |
| externalSecrets.creationPolicy | string | - | Chart configuration parameter Allowed: OwnerMergeNone |
| externalSecrets.deletionPolicy | string | - | Chart configuration parameter Allowed: RetainDeleteMerge |
| externalSecrets.items | array | - | Chart configuration parameter |
No schema parameters match your search
Try searching for a different keyword or reset the filter.