> ## Documentation Index > Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt > Use this file to discover all available pages before exploring further. # Guacamole > Deploy Apache Guacamole on Control Plane. A clientless remote desktop gateway that opens RDP, VNC, SSH and telnet sessions to internal machines in a browser tab. Single replica with a bundled PostgreSQL, private by default. Needs an existing GVC and a pre-created admin dictionary secret. ## Overview Apache Guacamole is a clientless remote desktop gateway: users open RDP, VNC, SSH, and telnet sessions to internal machines in a plain browser tab, with no client, plugin, or VPN to install. This template deploys the Guacamole web application together with the `guacd` protocol daemon in one workload, backed by a bundled PostgreSQL that holds users, connections, permissions, and session history. The gateway runs as a single replica and is **private by default** — you reach the UI over a port forward and opt in to publishing it. The administrator login is not a template value. It comes from a dictionary secret you create before installing, so it never passes through Helm and never lands in the release. This template deploys into an existing [GVC](/reference/gvc) that you already have — it does not create or manage a GVC. ### What Gets Created | Resource | Name | Purpose | Optional | | - | - | - | - | | Workload | `RELEASE_NAME-guacamole` | Gateway: the `guacamole` web application (UI, REST API, and browser tunnel on port `8080`), the `guacd` protocol daemon, and a `schema-init` container that loads the database schema on first boot (standard, 1 replica) | — | | Workload | `RELEASE_NAME-postgres` | Bundled PostgreSQL from the [postgres](/template-catalog/templates/postgres) template — users, connections, connection parameters, permissions, and session history (stateful, 1 replica) | — | | Workload | `RELEASE_NAME-postgres-backup` | Cron job that dumps the database to object storage on a schedule | `postgres.backup.enabled: true` | | Volume set | `RELEASE_NAME-pg-vs` | PostgreSQL data directory; takes no scheduled snapshots; a final snapshot is taken when the volume set is deleted and kept 7 days. The gateway workload itself mounts no volume set | — | | Secret | the name in `postgres.config.credentialsSecretName` | Dictionary secret the chart creates (`username`, `password`, `database`) from `postgres.credentials.*` and hands to the bundled PostgreSQL | — | | Secret | `RELEASE_NAME-guacamole-start` | Opaque secret holding the start script of the `guacamole` container; contains no credential | — | | Secret | `RELEASE_NAME-guacamole-init` | Opaque secret holding the schema bootstrap script of the `schema-init` container; contains no credential | — | | Identity | `RELEASE_NAME-guacamole-identity` | Bound to the gateway workload; no cloud bindings | — | | Policy | `RELEASE_NAME-guacamole-policy` | Grants that identity `reveal` on exactly four secrets: your admin secret, the database credentials secret, and the two script secrets | — | | Identity | `RELEASE_NAME-pg-identity` | Bound to the bundled PostgreSQL (and its backup job) | — | | Policy | `RELEASE_NAME-pg-policy` | Grants the PostgreSQL identity `reveal` on the database credentials secret only | — | Your admin secret is **not** created by the template — see [Prerequisites](#prerequisites). `guacd` listens on port `4822` and that port is deliberately **not published**. The protocol daemon is unauthenticated — anything that can reach it can drive an arbitrary RDP, VNC, or SSH session — so only the web application running beside it in the same workload can reach it. Do not "fix" this by declaring the port. ## Prerequisites **One secret must exist before you install.** It holds the Guacamole administrator login. The values never pass through Helm, so they do not land in the release. Secrets are org-level, so no GVC flag is involved. A [dictionary secret](/guides/create-secret/dictionary) holding exactly two keys — `username` and `password`. They become the Guacamole administrator account, replacing the well-known stock `guacadmin` account before the web application ever serves a request: ```bash theme={null} cpln secret create-dictionary --name ADMIN_SECRET_NAME \ --entry username=admin \ --entry password='YOUR-STRONG-PASSWORD' ``` Set `admin.secretName` to this name. Pass `-o yaml`. A bare `cpln secret reveal` prints only a summary table, not the values: ```bash theme={null} cpln secret reveal ADMIN_SECRET_NAME -o yaml ``` **Create the secret before installing, or the deployment wedges silently.** The template refuses to render when `admin.secretName` is blank, but a name that points at a secret which does not exist installs "successfully" and then never starts. No container runs, so `cpln logs` returns **zero lines**. The one place the reason appears is `status.versions[].message`: ```bash theme={null} cpln workload get-deployments RELEASE_NAME-guacamole --gvc GVC_NAME -o yaml ``` ```text theme={null} The secret ADMIN_SECRET_NAME no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed. ``` Use `get-deployments` — plain `cpln workload get` has no `versions` key. Creating the missing secret lets the deployment recover on its own; `cpln workload force-redeployment RELEASE_NAME-guacamole --gvc GVC_NAME` skips the wait. **The administrator credentials are applied on first boot only.** They seed the database once. Rotating the secret afterwards does not change your login — change the password in the Guacamole UI instead (see [First Run](#first-run)). Nothing else is required for a default install: the bundled database password is internal plumbing that this template turns into a secret for you. Scheduled database backups need a bucket and, for AWS or GCP, a Control Plane cloud account — see [Backing Up](#backing-up). ## Installation Once your admin secret exists, install from the marketplace registry, pointing `admin.secretName` at it and replacing the bundled database password: ```bash theme={null} cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/guacamole \ --version 1.0.0 --gvc GVC_NAME \ --set admin.secretName=ADMIN_SECRET_NAME \ --set postgres.credentials.password='YOUR-DB-PASSWORD' ``` Installing a second Guacamole release in the same org? Also set `postgres.config.credentialsSecretName` to a name no other release uses — secret names are org-wide. Other ways to install and manage the template: Browse, install, and manage templates visually Manage templates from your terminal }> Declare templates in your Terraform configurations Pulumi Icon Streamline Icon: https://streamlinehq.com } > Declare templates in your Pulumi programs ## Configuration ### Guacamole Web Application ```yaml theme={null} guacamole: image: guacamole/guacamole:1.6.0 # keep this tag equal to the guacd tag resources: minCpu: 500m maxCpu: 1000m minMemory: 1Gi maxMemory: 2Gi # JVM heap defaults to ~1/4 of this ``` ### guacd Protocol Daemon `guacd:1.6.0` has **RDP, VNC, SSH, and telnet** compiled in. The Kubernetes protocol is not included. ```yaml theme={null} guacd: image: guacamole/guacd:1.6.0 # keep this tag equal to the guacamole tag resources: minCpu: 100m maxCpu: 1000m minMemory: 256Mi maxMemory: 1Gi # raise for many concurrent RDP sessions ``` ### Admin Account ```yaml theme={null} admin: secretName: my-guacamole-admin # dictionary secret with username + password — MUST exist before install ``` `admin.secretName` is required. The secret is read on first boot only; afterwards, change the password in the Guacamole UI, not in the secret. ### Logging ```yaml theme={null} logLevel: info # trace | debug | info | error; applies to both containers ``` `warn` is deliberately not an option: `guacd` spells that level `warning` while the web application spells it `warn`, so no single value covers both containers. The chart rejects anything outside the four listed values at render. ### Access ```yaml theme={null} publicAccess: enabled: false # false = internal only; true = UI on the auto-assigned *.cpln.app HTTPS endpoint internalAccess: type: same-gvc # none | same-gvc | same-org | workload-list workloads: [] # used only with workload-list, e.g. //gvc/GVC_NAME/workload/WORKLOAD_NAME ``` | `internalAccess.type` | Who can reach Guacamole over the internal network | | - | - | | `none` | No workload | | `same-gvc` | Every workload in the same GVC (default) | | `same-org` | Every workload in the same org | | `workload-list` | Only the workloads listed in `internalAccess.workloads` | A change to either access knob takes a couple of minutes to take effect after the upgrade reports success. These knobs govern **inbound** traffic to Guacamole. They do not restrict which hosts `guacd` may dial: a remote desktop gateway needs outbound reach to the machines its connections target, so egress stays open. Control what a user can connect to through the connections and permissions you create inside Guacamole. ### Bundled PostgreSQL The database is the [postgres](/template-catalog/templates/postgres) template as a subchart, so every knob of that template is available under `postgres.*`. The chart builds the credentials secret from `postgres.credentials.*` for you — nothing to create before installing. `postgres.image` also sets the image of the `schema-init` container, so `psql` always matches the server version. ```yaml theme={null} postgres: image: postgres:18 # also used by the schema-init container, so psql matches the server credentials: # the chart writes these into the secret named below username: guacamole password: change-me-guacamole-db # change before installing — seeds the database on first boot database: guacamole config: credentialsSecretName: my-guacamole-db-credentials # chart-created; secret names are org-wide, so give each release its own resources: minCpu: 250m maxCpu: 1000m minMemory: 512Mi maxMemory: 1Gi volumeset: capacity: 10 # GiB (minimum 10) backup: enabled: false # scheduled pg_dumpall to object storage — see Backing Up schedule: "0 2 * * *" # daily at 02:00 UTC provider: aws # aws | gcp | minio ``` `postgres.credentials.password` seeds the database on first boot and is not updated by later value edits. Uninstalling the release deletes the volume set; reinstall to reset. ## Connecting | What | Address | Notes | | - | - | - | | Web UI (default, private) | `http://localhost:8080` through `cpln port-forward` (below) | Tunnels through Control Plane and works with public access off. | | Web UI (public) | `https://.cpln.app` | Only while `publicAccess.enabled` is `true`. Read it from `status.canonicalEndpoint` with `cpln workload get RELEASE_NAME-guacamole --gvc GVC_NAME -o yaml`. | | Internal (same GVC) | `http://RELEASE_NAME-guacamole.GVC_NAME.cpln.local:8080` | Reachable per `internalAccess.type`. Use the fully qualified name — a bare short name does not reliably resolve. | | Admin login | `username` / `password` from your admin secret | `cpln secret reveal ADMIN_SECRET_NAME -o yaml` | | PostgreSQL (same GVC) | `RELEASE_NAME-postgres.GVC_NAME.cpln.local:5432` | `username` / `password` / `database` from `cpln secret reveal SECRET_NAME -o yaml`, where `SECRET_NAME` is your `postgres.config.credentialsSecretName`. | Guacamole is served at `/`, not at `/guacamole/`. With the default private install, reach the UI from your machine through a tunnel and open `http://localhost:8080`: ```bash theme={null} cpln port-forward RELEASE_NAME-guacamole 8080:8080 --gvc GVC_NAME ``` ### First Run A default install is closed to the internet. Sign in through a port forward first, set your own password, add a connection, and publish the UI only if you want it reachable from outside the GVC. PostgreSQL comes up first, then the `schema-init` container loads the schema and writes your administrator account, and only then does the web application start serving. Expect the first boot to take a few minutes. ```bash theme={null} cpln workload get-deployments RELEASE_NAME-guacamole --gvc GVC_NAME -o yaml ``` While it waits, the gateway's logs show `guacamole: waiting for the schema and admin account to be applied...`; the boot is finished when `schema-init: bootstrap complete, idling` and `guacamole: schema ready, starting Tomcat` appear: ```bash theme={null} cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-guacamole"}' --limit 50 --since 10m ``` `cpln port-forward` is a top-level command, not a `cpln workload` subcommand: ```bash theme={null} cpln port-forward RELEASE_NAME-guacamole 8080:8080 --gvc GVC_NAME ``` Open `http://localhost:8080` and sign in with the `username` and `password` from your admin secret. The stock `guacadmin` / `guacadmin` login is never valid here — the stock account is replaced by yours before the web application starts. Open the Guacamole menu (top right) → **Settings → Preferences** and use **Change Password**. The password now lives in the database; the secret you created is not consulted again after the first boot, so leaving it unchanged there does not weaken anything. A fresh install has no connections and looks empty until you add one. Go to **Settings → Connections → New Connection**, choose a protocol (RDP, VNC, SSH, or telnet), and set the target host and port. For a machine running as a workload in the same GVC, use its fully qualified internal name as the hostname — `WORKLOAD_NAME.GVC_NAME.cpln.local` — with the service's port (for example `22` for SSH). A bare short name does not reliably resolve. Then grant users access to the connection under **Settings → Users**. Upgrade the release with `publicAccess.enabled` set to `true`. The canonical `*.cpln.app` hostname then appears under `status.canonicalEndpoint`: ```bash theme={null} cpln workload get RELEASE_NAME-guacamole --gvc GVC_NAME -o yaml ``` Allow a couple of minutes for the change to take effect before concluding it did not work. ## Operations ### Backing Up Scheduled backups of the bundled PostgreSQL are off by default. Enabling `postgres.backup.enabled: true` adds one cron workload, `RELEASE_NAME-postgres-backup`, that runs `pg_dumpall` on the schedule and uploads a gzipped dump to your bucket under the configured prefix. The dump covers everything Guacamole persists: users, connections, connection parameters, permissions, and session history. Pick a `postgres.backup.provider` and complete the matching setup **before** installing or upgrading with it on. ```yaml theme={null} postgres: backup: enabled: true provider: aws aws: bucket: my-postgres-bucket region: us-east-1 cloudAccountName: my-s3-cloud-account policyName: my-postgres-backup-policy # bucket-scoped IAM policy prefix: postgres/backups ``` Create an S3 bucket. Set `postgres.backup.aws.bucket` and `postgres.backup.aws.region` to match. If you do not have one, [create a cloud account](/guides/create-cloud-account) for the AWS account holding the bucket. Set `postgres.backup.aws.cloudAccountName` to its name. Create an IAM policy with the JSON below (replace `YOUR_BUCKET_NAME`) and set `postgres.backup.aws.policyName` to its name. The template attaches it to the PostgreSQL identity and nothing else — the bucket in your policy is the only storage the backup job can reach: ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket", "s3:GetObjectVersion", "s3:DeleteObjectVersion", "s3:GetBucketLocation", "s3:AbortMultipartUpload", "s3:ListBucketMultipartUploads", "s3:ListMultipartUploadParts" ], "Resource": [ "arn:aws:s3:::YOUR_BUCKET_NAME", "arn:aws:s3:::YOUR_BUCKET_NAME/*" ] } ] } ``` ```yaml theme={null} postgres: backup: enabled: true provider: gcp gcp: bucket: my-postgres-bucket cloudAccountName: my-gcs-cloud-account prefix: postgres/backups ``` Create a GCS bucket. Set `postgres.backup.gcp.bucket` to its name. [Create a cloud account](/guides/create-cloud-account) for the GCP project holding the bucket and set `postgres.backup.gcp.cloudAccountName` to its name. Grant the cloud account's service account the **Storage Admin** (`roles/storage.admin`) role on the project. The chart additionally binds the identity to `roles/storage.objectAdmin` on exactly the bucket in `postgres.backup.gcp.bucket`. ```yaml theme={null} postgres: backup: enabled: true provider: minio minio: endpoint: http://my-minio-workload:9000 # S3 API address including the port bucket: my-postgres-bucket credentialsSecretName: my-postgres-minio-credentials # dictionary secret with accessKey + secretKey prefix: postgres/backups ``` Create the bucket on your server. Set `postgres.backup.minio.bucket` to its name and `postgres.backup.minio.endpoint` to the S3 API address including the port — for the [MinIO](/template-catalog/templates/minio) template in the same GVC, `http://WORKLOAD_NAME.GVC_NAME.cpln.local:9000`. Create a dictionary secret with the server's keys and set `postgres.backup.minio.credentialsSecretName` to its name. No cloud account is involved. ```bash theme={null} cpln secret create-dictionary --name BACKUP_MINIO_SECRET_NAME \ --entry accessKey=YOUR-ACCESS-KEY \ --entry secretKey='YOUR-SECRET-KEY' ``` `postgres.backup.image` must match the PostgreSQL major version in `postgres.image`. If you move off the defaults, change both together. The full per-provider walkthrough lives on the [postgres](/template-catalog/templates/postgres) template page. The database dump does not include your admin secret, which lives in the secret you created. The PostgreSQL volume set `RELEASE_NAME-pg-vs` takes no scheduled [snapshots](/reference/volumeset); a final snapshot is taken when the volume set is deleted and kept 7 days. ### Restoring a Backup Each backup is a gzipped plain-SQL `pg_dumpall` archive. Restoring means replaying that SQL into the bundled PostgreSQL. The one transport that carries a dump into the container intact is `cpln workload exec` with `--stdin` and a `base64` wrapper on both ends — raw binary piped through exec is corrupted: ```bash theme={null} gunzip -c BACKUP_FILE.sql.gz | base64 | cpln workload exec RELEASE_NAME-postgres --gvc GVC_NAME \ --container postgresql --stdin --quiet -- sh -c 'base64 -d | psql -U "$POSTGRES_USER" -d postgres' ``` Two constraints make this a planned operation: the archive contains `CREATE ROLE` and `CREATE DATABASE` statements, so a straight replay collides with the `guacamole` database the schema-init container already created on first boot; and no user should be signed in while you drop and recreate that database before the replay — every session is cut when its rows disappear. This restore path has not been exercised against this template end to end. Rehearse it on a throwaway release before you depend on it. Restoring from a volume set snapshot is likewise unverified here. ### Scaling and Availability This template runs **exactly one replica**, and there is no `replicas` knob. Guacamole keeps authentication tokens in each web application's memory with no cross-instance sharing, so a second replica would randomly sign users out. Any restart — an upgrade, a replica reschedule, or a forced redeployment — therefore drops active desktop sessions and signs everyone out. Reconnecting re-establishes the session. Nothing persisted is lost: users, connections, permissions, and history all live in PostgreSQL on the `RELEASE_NAME-pg-vs` volume set, which survives restarts, redeploys, and upgrades under the same release name. The first `helm upgrade` after an install can restart the bundled PostgreSQL even when its values are unchanged, so expect a brief interruption. Rotating a secret the workload references does not restart it; the old value stays in force until you run `cpln workload force-redeployment RELEASE_NAME-guacamole --gvc GVC_NAME`. For the admin credentials specifically, even a redeployment does not change your login — those are applied on first boot only. ### Troubleshooting **Symptom:** `cpln helm install` reported success, `cpln logs` returns nothing, and `cpln workload get-deployments RELEASE_NAME-guacamole --gvc GVC_NAME -o yaml` shows `The secret ADMIN_SECRET_NAME no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.` under `status.versions[].message`. **Cause:** The prerequisite admin secret named by `admin.secretName` does not exist. **Fix:** Create it (see [Prerequisites](#prerequisites)). The deployment recovers on its own once the secret exists; `cpln workload force-redeployment RELEASE_NAME-guacamole --gvc GVC_NAME` skips the wait. **Symptom:** The workload is not ready and its logs repeat `guacamole: waiting for the schema and admin account to be applied...` without ever reaching `schema-init: bootstrap complete, idling`. **Cause:** The `schema-init` container is almost always still waiting on PostgreSQL — its own log line reads `schema-init: waiting for postgres at RELEASE_NAME-postgres.GVC_NAME.cpln.local:5432 ...`. **Fix:** Check that `RELEASE_NAME-postgres` is ready with `cpln workload get-deployments RELEASE_NAME-postgres --gvc GVC_NAME -o yaml`, then follow the bootstrap with a server-side filter: ```bash theme={null} cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-guacamole"} |= "schema-init"' --limit 50 --since 10m ``` **Symptom:** Installing a second Guacamole release fails with `cannot be updated because it is being managed by a different release` and creates nothing. **Cause:** Both releases use the same `postgres.config.credentialsSecretName`. Secret names are org-wide, and the first release owns that one. Nothing is shared, overwritten, or deleted. **Fix:** Set `postgres.config.credentialsSecretName` to a distinct name for the second release and install again. **Symptom:** You changed `username` or `password` in the admin secret (and even forced a redeployment), yet the original credentials still sign in and the new ones are rejected. **Cause:** The admin credentials seed the database on first boot only. Once the schema exists the `schema-init` container logs `schema-init: guacamole schema already present, skipping bootstrap` and leaves the account alone — otherwise every restart would overwrite a password changed in the UI. **Fix:** Change the password in the Guacamole UI under **Settings → Preferences**, or as an administrator under **Settings → Users**. **Symptom:** Guacamole's documented stock login returns an invalid-credentials error. **Cause:** Expected. The stock account is renamed and re-hashed to the `username` and `password` in your admin secret before the web application starts serving. **Fix:** Sign in with the values from `cpln secret reveal ADMIN_SECRET_NAME -o yaml`. **Symptom:** `guacamole: logLevel must be 'trace', 'debug', 'info' or 'error', got 'warn'`. **Cause:** `warn` is excluded because `guacd` spells that level `warning` and the web application spells it `warn`, so no single value covers both containers. **Fix:** Use `info` or `error`. **Symptom:** After a `helm upgrade`, a forced redeployment, or a replica reschedule, every user is back at the login page and open desktop sessions ended. **Cause:** Expected. Guacamole holds authentication tokens in the web application's memory, and the template runs one replica — see [Scaling and Availability](#scaling-and-availability). **Fix:** Sign in again and reconnect. Users, connections, and history are intact in PostgreSQL. **Symptom:** Opening a connection fails with a hostname-resolution error from `guacd`. **Cause:** The connection's hostname is a bare workload name. Short names do not reliably resolve. **Fix:** Edit the connection and set the hostname to the fully qualified form `WORKLOAD_NAME.GVC_NAME.cpln.local`. ## Important Notes * **Create the admin secret before installing** — `admin.secretName` must name an existing dictionary secret with `username` and `password`. A missing secret wedges the deployment silently; see [Prerequisites](#prerequisites) for the one command that shows the reason. * **The admin credentials are first-boot only.** Rotating the secret afterwards does not change your login. Change the password in the Guacamole UI instead. * **`guacadmin` / `guacadmin` is never valid here** — the stock account is replaced by yours before the web application starts. * **Rotating any referenced secret does not restart the workload.** The old value stays in force until you run `cpln workload force-redeployment RELEASE_NAME-guacamole --gvc GVC_NAME`. * **Single replica by design, with no `replicas` knob.** Any restart drops active desktop sessions and signs everyone out; see [Scaling and Availability](#scaling-and-availability). * **Public access is off by default.** Reach the UI over `cpln port-forward` until you deliberately publish it. Access changes take a couple of minutes to take effect. * **`guacd`'s port `4822` is intentionally unpublished** because the protocol daemon is unauthenticated. Only the web application in the same workload can reach it. * **Only RDP, VNC, SSH, and telnet are available** in `guacd:1.6.0`. The Kubernetes protocol is not compiled in. * **Use fully qualified internal names** — `WORKLOAD_NAME.GVC_NAME.cpln.local` — both for reaching Guacamole from other workloads and for the connection targets you configure in it. * **Keep `guacamole.image` and `guacd.image` on the same tag** — the web application and the protocol daemon are versioned together upstream. * **Change `postgres.credentials.password` before installing** and give each release its own `postgres.config.credentialsSecretName` — secret names are org-wide, and a second release on the same name is refused at install. * **Uninstalling deletes the volume set** and every user, connection, and history row in it; your admin secret is yours and survives. ## External References The official Apache Guacamole administrator and user guide Managing users, connections, groups, and permissions Connection parameters for RDP, VNC, SSH, and telnet How Guacamole stores users and connections in PostgreSQL View the source files, default values, and chart definition