Apache Guacamole on GKE and Cloud SQL

Last reviewed 2023-11-15 UTC

Apache Guacamole offers a fully browser-based way to access remote desktops through Remote Desktop Protocol (RDP), Virtual Network Computing (VNC), and Secure Shell Protocol (SSH) on Compute Engine virtual machines (VMs). Identity-Aware Proxy (IAP) provides access to Guacamole with improved security.

This reference architecture document is intended for server administrators and engineers who want to host Apache Guacamole on Google Kubernetes Engine (GKE) and Cloud SQL. This document assumes you are familiar with deploying workloads to Kubernetes and Cloud SQL for MySQL. This document also assumes you are familiar with Identity and Access Management and Google Compute Engine.


The following diagram shows how a Google Cloud load balancer is configured with IAP, to protect an instance of the Guacamole client running in GKE:

Architecture for Google Cloud load balancer configured with IAP.

This architecture includes the following components:

  • Google Cloud load balancer: Distributes traffic across multiple instances, which reduces the risk of performance issues.
  • IAP: Provides improved security through a custom authentication extension.
  • Guacamole client: Runs in GKE and connects to the guacd backend service.
  • Guacd backend service: Brokers remote desktop connections to one or more Compute Engine VMs.
  • Guacamole database in Cloud SQL: Manages configuration data for Guacamole.
  • Compute Engine instances: VMs hosted on the Google infrastructure.

Design considerations

The following guidelines can help you to develop an architecture that meets your organization's requirements for security, cost, and performance.

Security and compliance

This architecture uses IAP to help protect access to the Guacamole service. Authorized users sign in to the Guacamole instance through a custom IAP authentication extension. For details, see the custom extension in GitHub.

When you add additional users (through the Guacamole user interface), these additional users must have permissions through IAM, with the IAP-secured Web App User role.

The OAuth configuration that this deployment creates is set to internal. Because of this setting, you must use a Google account in the same organization as the one you use to deploy Guacamole. If you use a Google account outside the organization, you receive an HTTP/403 org_internal error.


Google Cloud load balancer and GKE distributes traffic across multiple instances, which helps to reduce the risk of performance issues.


To deploy this architecture, see Deploy Apache Guacamole on GKE and Cloud SQL.

What's Next?