This document describes how you deployApache Guacamole on GKE and Cloud SQL.

These instructions are intended for server administrators and engineers who wantto host Guacamole on GKE and Cloud SQL. The documentassumes you are familiar with deploying workloads to Kubernetesand Cloud SQL for MySQL. We recommend that you be familiar with Identity and Access Management andGoogle Compute Engine as well.

Architecture

The following diagram shows how a Google Cloud load balancer isconfigured with IAP, to protect an instance of the Guacamoleclient running in GKE:

The Guacamole client connects to the guacd backend service, which brokers remotedesktop connections to one or more Compute Engine VMs. The scripts alsodeploy a Cloud SQL instance to manage configuration data for Guacamole.

For details, seeApache Guacamole on GKE and Cloud SQL.

Objectives

• Deploy the infrastructure by using Terraform.
• Create a Guacamole database in Cloud SQL.
• Deploy Guacamole to a GKE Cluster by using Skaffold.
• Test a connection to a VM through Guacamole.

Costs

In this document, you use the following billable components of Google Cloud:

• Compute Engine
• GKE
• Cloud SQL
• Artifact Registry

To generate a cost estimate based on your projected usage, use thepricing calculator.

When you finish the tasks that are described in this document, you can avoid continued billing by deleting the resources that you created. For more information, seeClean up.

Before you begin

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Verify that billing is enabled for your Google Cloud project.

3. Enable the Resource Manager, Service Usage, Artifact Registry, and Compute Engine APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

   Enable the APIs

4. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

Deploy the infrastructure

In this section, you use Terraform to deploy the following resources:

• Virtual Private Cloud
• A firewall rule
• A GKE cluster
• An Artifact Registry repository
• Cloud SQL for MySQL
• A VM for managing the MySQL database
• Service accounts

The Terraform configuration also enablesthe use of IAP in your project.

1. In Cloud Shell, clone the GitHub repository:

   gitclonehttps://github.com/GoogleCloudPlatform/guacamole-on-gcp.git

2. Deploy the required infrastructure by using Terraform:

   cdguacamole-on-gcp/tf-infraunsetGOOGLE_CLOUD_QUOTA_PROJECTterraforminit-upgradeterraformapply

3. Follow the instructions to enter your Google Cloud project ID.

4. To approve Terraform's request to deploy resources to your project,enteryes.

   Deploying all resources takes several minutes to complete.

Deploy the Guacamole database

In this section, you create the Guacamole database and tables inCloud SQL for MySQL, and populate the database with the administrator userinformation.

1. In Cloud Shell, set environment variables and find thedatabase root password:

   cd..sourcebin/read-tf-output.sh

   Make a note of the database root password; you need it in the followingsteps.

   The script reads output variables from the Terraform run and sets thefollowing environment variables, which are used throughout this procedure:

   CLOUD_SQL_INSTANCEZONEREGIONDB_MGMT_VMPROJECT_IDGKE_CLUSTERGUACAMOLE_URLSUBNET

2. Copy thecreate-schema.sql andinsert-admin-user.sql script filesto the database management VM, and then connect to the VM:

   gcloudcomputescp\--tunnel-through-iap\--zone=$ZONE\create-schema.sql\insert-admin-user.sql\$DB_MGMT_VM:gcloudcomputessh$DB_MGMT_VM\--zone=$ZONE\--tunnel-through-iap

   A console session to the Database Management VM through Cloud Shellis now established.

3. Install MySQL client tools:

   sudoapt-getupdatesudoapt-getinstall-ymariadb-client

4. Connect to Cloud SQL and create the database. When promptedfor a password, use the root password you noted earlier in this section.

   exportCLOUD_SQL_PRIVATE_IP=$(curlhttp://metadata.google.internal/computeMetadata/v1/instance/attributes/cloud_sql_ip-H"Metadata-Flavor: Google")mysql-h$CLOUD_SQL_PRIVATE_IP-uroot-p

5. Grant the database user permissions over the newly created database:

   CREATEDATABASEguacamole;USEguacamole;GRANTSELECT,INSERT,UPDATE,DELETEONguacamole.*TO'guac-db-user';FLUSHPRIVILEGES;SOURCEcreate-schema.sql;SOURCEinsert-admin-user.sql;quit

6. After the MySQL commands finish running, exit the VM SSH session:

   exit

Deploy Guacamole to GKE by using Skaffold

In this section, you deploy the Guacamole application tothe GKE cluster, by usingSkaffold.Skaffold handles the workflow for building, pushing, and deploying the Guacamoleimages to the GKE clusters.

1. In Cloud Shell, deploy the GKE configurationby using terraform:

   cdtf-k8sterraforminit-upgradeterraformapply-parallelism=1

2. Get credentials for the GKE cluster:

   gcloudcontainerclustersget-credentials\--region$REGION$GKE_CLUSTER

3. Run Skaffold from the root of the cloned git repository:

   cd..skaffold--default-repo$REGION-docker.pkg.dev/$PROJECT_ID/guac-reporun

   The Skaffold tool builds container images for Guacamole throughGoogle Cloud Build (the command line includes a flag that specifies which repository to push theimages to). The tool also runs akustomize step to generate Kubernetes ConfigMaps and Secrets based on the output ofthe Terraform run.

4. Verify that the certificate was provisioned:

   kubectlget-wmanagedcertificates/guacamole-client-cert\-nguacamole\-ojsonpath="{.spec.domains[0]} is {.status.domainStatus[0].status}"

   Provisioning the certificate can take up to 60 minutes to complete.

5. Once the certificate is provisioned, you can visit your URL in a browser.

   1. View the URL from the terraform output:

      echo$GUACAMOLE_URL

   2. In a browser window, enter the URL that you got in the previous step.

   3. When IAP prompts you, sign in with your Googlecredentials.

      After you sign in, you are logged into Guacamole with administrativeprivileges, based on theinsert-admin-user.sql script you ran previouslyin this procedure.

      Note: The OAuth configuration created by this procedure is set tointernal.This means you must use a Google Account in the same organization as theone you used to deploy Guacamole in this procedure; otherwise, you receiveanHTTP/403 org_internal error. If your browser session is already signedinto a different Google Account, try connecting to the URL in an incognitomode tab.

You can now add additional users based on their email address through theGuacamole user interface. For details, seeAdministration in the Guacamole documentation.These additional users also require permissions through GoogleIAM, with theIAP-secured Web App User role.

Test a connection to a VM

After you deploy, configure, and successfully sign in to Guacamole, you cancreate a Windows VM and connect to the newly created VM through Guacamole.

Create a VM

1. In Cloud Shell, create a Windows VM to test connections to:

   exportTEST_VM=windows-vmgcloudcomputeinstancescreate$TEST_VM\--project=$PROJECT_ID\--zone=$ZONE\--machine-type=n1-standard-1\--subnet=$SUBNET\--no-address\--image-family=windows-2019\--image-project=windows-cloud\--boot-disk-size=50GB\--boot-disk-type=pd-standard\—-shielded-secure-boot

   After running the command, you may need to wait a few minutes for Windows tofinish initializing, before you proceed to the next step.

2. Reset the Windows password for the VM you just created:

   gcloudcomputereset-windows-password$TEST_VM\--user=admin\--zone=$ZONE

Add a new connection to the VM

1. In a browser window, enter the Guacamole instance URL fromDeploy Guacamole to GKE using Skaffold, and then sign in through IAP.
2. In the Guacamole UI, click your username, and then clickSettings.
3. Under theConnections tab, clickNew Connection.
   1. In theName field, enter a name for the connection.
   2. In theLocation field, enter the location for the connection.
   3. From theProtocol drop-down list, selectRDP.

4. UnderNetwork, in theHostname field, enter the name of the VMyou created,windows-vm.

   Your project DNS resolves this hostname to the instance's internal IP address.

   Note: If you choose to create your VM in a different zone than yourGuacamole GKE cluster, you need to fully qualify theVM name. For details, seeInternal DNS.

5. In theAuthentication section, set the following fields:

   1. Username:admin
   2. Password: the password you got when you reset the password for the VM
   3. Security mode:NLA (Network Level Authentication)

   4. Ignore server certificate: select the checkbox

      Compute Engine Windows VMs are provisioned with a self-signedcertificate for Remote Desktop Services, so you need to instructGuacamole to ignore certificate validation issues.

6. ClickSave.

7. Click your username, and selectHome.

8. Click the connection you just created to test connectivity.After a few seconds, you should see the desktop of the VM instance.

For more details on configuring Guacamole, see theApache Guacamole Manual.

Clean up

To avoid incurring charges to your Google Cloud account for the resources usedin this procedure, either delete the project that contains the resources, or keepthe project and delete the individual resources.

Delete the project

Caution: Deleting a project has the following effects:
• Everything in the project is deleted. If you used an existing project for the tasks in this document, when you delete it, you also delete any other work you've done in the project.
• Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as anappspot.com URL, delete selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple architectures, tutorials, or quickstarts, reusing projects can help you avoid exceeding project quota limits.

1. In the Google Cloud console, go to theManage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then clickDelete.
3. In the dialog, type the project ID, and then clickShut down to delete the project.

Delete the new resources

As an alternative to deleting the entire project, you can delete the individualresources created during this procedure. Note that the OAuth Consent Screenconfiguration cannot be removed from a project, only modified.

• In Cloud Shell, use terraform to delete the resources:

  cd~/guacamole-on-gcp/tf-k8sterraformdestroycd~/guacamole-on-gcp/tf-infraterraformdestroygcloudcomputeinstancesdelete$TEST_VM–-zone=$ZONE

What's next

• Review the GKE guidance onHardening your cluster's security.
• ReviewEncrypt secrets at the application layer to learn how to boost security for secrets, such as database credentials andOAuth credentials.
• ReviewIAM Conditions to learn how to provide more granular control over user access to Guacamole.
• Understand more about how IAP integration works byreviewing the custom authentication provider in theGitHub repository.
• For more reference architectures, diagrams, and best practices, explore theCloud Architecture Center.

Contributors

Author:Richard Grime | Principal Architect, UK Public Sector

Other contributors:

• Aaron Lind | Solution Engineer, Application Innovation
• Eyal Ben Ivri | Cloud Solutions Architect
• Ido Flatow | Cloud Solutions Architect