Terraform module aligned with HashiCorp Validated Designs (HVD) to deploy Boundary Enterprise Controller(s) on Google Cloud Platform (GCP) using Compute Engine instances. This module is designed to work with the complimentary Boundary Enterprise Worker HVD on GCP GCE module.
- Terraform CLI
>= 1.9installed on workstations. GitCLI and Visual Studio Code editor installed on workstations are strongly recommended.- Google account that Boundary will be hosted in with permissions to provision these resources via Terraform CLI.
- (Optional) Google GCS for GCS Remote State backend that will solely be used to stand up the Boundary infrastructure via Terraform CLI (Community Edition).
- GCP Project Created
- Following APIs enabled
- dns.googleapis.com
- secretmanager.googleapis.com
- compute.googleapis.com
- servicenetworking.googleapis.com
- cloudkms.googleapis.com
- networkservices.googleapis.com
- Google VPC
- Subnet
- Proxy Subnet with purpose set to
REGIONAL_MANAGED_PROXY - Private Service Access Configured
- Firewall rules will be created with this Module. If that is not possible (shared VPC) then the firewall rules in this module will need to be created in the shared VPC
- Boundary Network connectivity
- Boundary license file - raw contents of Boundary license file (
*.hclic) (ex:cat boundary.hclic) - Google SQL (PostgreSQL) database password - random characters stored as plaintext secret.
- Boundary TLS certificate - file in PEM format, base64-encoded into a string, and stored as a plaintext secret.
- Boundary TLS certificate private key - file in PEM format, base64-encoded into a string, and stored as a plaintext secret.
- TLS CA bundle - file in PEM format, base64-encoded into a string, and stored as a plaintext secret.
📝 Note: see the Boundary cert rotation docs for instructions on how to base64-encode the certificates with proper formatting.
One of the following mechanisms for shell access to Boundary VM instances:
- Ability to enable Google IAP (this module supports this via a boolean input variable).
- SSH key and user
-
Create/configure/validate the applicable prerequisites.
-
Nested within the examples directory are subdirectories that contain ready-made Terraform configurations of example scenarios for how to call and deploy this module. To get started, choose an example scenario. If you are not sure which example scenario to start with, then we recommend starting with the default example.
-
Copy all of the Terraform files from your example scenario of choice into a new destination directory to create your root Terraform configuration that will manage your Boundary deployment. If you are not sure where to create this new directory, it is common for us to see users create an
environments/directory at the root of this repo, and then a subdirectory for each Boundary instance deployment, like so:. └── environments ├── production │ ├── backend.tf │ ├── main.tf │ ├── outputs.tf │ ├── terraform.tfvars │ └── variables.tf └── sandbox ├── backend.tf ├── main.tf ├── outputs.tf ├── terraform.tfvars └── variables.tf📝 Note: in this example, the user will have two separate Boundary deployments; one for their
sandboxenvironment, and one for theirproductionenvironment. This is recommended, but not required. -
(Optional) Uncomment and update the gcs remote state backend configuration provided in the
backend.tffile with your own custom values. While this step is highly recommended, it is technically not required to use a remote backend config for your Boundary deployment. -
Populate your own custom values into the
terraform.tfvars.examplefile that was provided, and remove the.examplefile extension such that the file is now namedterraform.tfvars. -
Navigate to the directory of your newly created Terraform configuration for your Boundary Controller deployment, and run
terraform init,terraform plan, andterraform apply. -
After your
terraform applyfinishes successfully, you can monitor the installation progress by connecting to your Boundary VM instance shell via SSH or Google IAP and observing the cloud-init (user_data) logs:Higher-level logs:
tail -f /var/log/boundary-cloud-init.log
Lower-level logs:
journalctl -xu cloud-final -f
📝 Note: the
-fargument is to follow the logs as they append in real-time, and is optional. You may remove the-ffor a static view.The log files should display the following message after the cloud-init (user_data) script finishes successfully:
[INFO] boundary_custom_data script finished successfully! -
Once the cloud-init script finishes successfully, while still connected to the VM via SSH you can check the status of the boundary service:
sudo systemctl status boundary
-
After the Boundary Controller is deployed the Boundary system will be partially initialized. To complete the initialization process and setup an initial auth method, username and password, please use the terraform-boundary-bootstrap-hvd module
-
Use the terraform-google-boundary-worker-hvd module to deploy ingress, egress, etc workers as needed.
Below are links to docs pages related to deployment customizations and day 2 operations of your Boundary Controller instance.
- Deployment Customizations
- Upgrading Boundary version
- Rotating Boundary TLS/SSL certificates
- Updating/modifying Boundary configuration settings
- Authenticate to Boundary Cluster with Boundary CLI
This open source software is maintained by the HashiCorp Technical Field Organization, independently of our enterprise products. While our Support Engineering team provides dedicated support for our enterprise offerings, this open source software is not included.
- For help using this open source software, please engage your account team.
- To report bugs/issues with this open source software, please open them directly against this code repository using the GitHub issues feature.
Please note that there is no official Service Level Agreement (SLA) for support of this software as a HashiCorp customer. This software falls under the definition of Community Software/Versions in your Agreement. We appreciate your understanding and collaboration in improving our open source projects.
| Name | Version |
|---|---|
| terraform | ~> 1.9 |
| ~> 5.39 | |
| google-beta | ~> 5.39 |
| random | ~> 3.6 |
| Name | Version |
|---|---|
| cloudinit | n/a |
| ~> 5.39 | |
| google-beta | ~> 5.39 |
| random | ~> 3.6 |
| Name | Description | Type | Default | Required |
|---|---|---|---|---|
| additional_package_names | List of additional repository package names to install | set(string) |
[] |
no |
| api_load_balancing_scheme | Determines whether API load balancer is internal-facing or external-facing. | string |
"internal" |
no |
| boundary_database_name | Name of boundary PostgreSQL database to create. | string |
"boundary" |
no |
| boundary_database_password_secret_version | Name of PostgreSQL database password secret to retrieve from GCP Secret Manager. | string |
null |
no |
| boundary_database_user | Name of boundary PostgreSQL database user to create. | string |
"boundary" |
no |
| boundary_fqdn | Fully qualified domain name of boundary instance. This name should resolve to the load balancer IP address and will be what clients use to access boundary. | string |
n/a | yes |
| boundary_license_secret_id | ID of Secrets Manager secret for Boundary license file. | string |
n/a | yes |
| boundary_tls_ca_bundle_secret_id | ID of Secrets Manager secret for private/custom TLS Certificate Authority (CA) bundle in PEM format. Secret must be stored as a base64-encoded string. | string |
null |
no |
| boundary_tls_cert_secret_id | ID of Secrets Manager secret for Boundary TLS certificate in PEM format. Secret must be stored as a base64-encoded string. | string |
n/a | yes |
| boundary_tls_disable | Boolean to disable TLS for boundary. | bool |
false |
no |
| boundary_tls_privkey_secret_id | ID of Secrets Manager secret for Boundary TLS private key in PEM format. Secret must be stored as a base64-encoded string. | string |
n/a | yes |
| boundary_version | Version of Boundary to install. | string |
"0.17.1+ent" |
no |
| bsr_gcs_force_destroy | Boolean indicating whether to allow force destroying the TFE GCS bucket. GCS bucket can be destroyed if it is not empty when true. |
bool |
false |
no |
| bsr_gcs_kms_key_name | Name of Cloud KMS customer managed encryption key (CMEK) to use for TFE GCS bucket encryption. | string |
null |
no |
| bsr_gcs_kms_key_ring_name | Name of Cloud KMS key ring that contains KMS customer managed encryption key (CMEK) to use for TFE GCS bucket encryption. Geographic location (region) of the key ring must match the location of the TFE GCS bucket. | string |
null |
no |
| bsr_gcs_location | Location of TFE GCS bucket to create. | string |
"US" |
no |
| bsr_gcs_storage_class | Storage class of TFE GCS bucket. | string |
"MULTI_REGIONAL" |
no |
| bsr_gcs_uniform_bucket_level_access | Boolean to enable uniform bucket level access on TFE GCS bucket. | bool |
true |
no |
| bsr_gcs_versioning_enabled | Boolean to enable versioning on TFE GCS bucket. | bool |
true |
no |
| bsr_key_name | Name of an existing KMS BSR key to use for Boundary | string |
null |
no |
| cidr_ingress_9200_allow | CIDR ranges to allow 9200 traffic inbound to Boundary instance(s). This is for Boundary Clients using the Boundary API. | list(string) |
[ |
no |
| cidr_ingress_9201_allow | CIDR ranges to allow 9201 traffic inbound to Boundary instance(s). This is for Boundary Ingress Workers accessing the Boundary Controller(s). | list(string) |
[ |
no |
| cidr_ingress_ssh_allow | CIDR ranges to allow SSH traffic inbound to Boundary instance(s) via IAP tunnel. | list(string) |
[ |
no |
| cloud_dns_managed_zone | Zone name to create Boundary Cloud DNS record in if create_cloud_dns_record is set to true. |
string |
null |
no |
| common_labels | Common labels to apply to GCP resources. | map(string) |
{} |
no |
| create_bsr_key | Boolean to create a KMS BSR key for Boundary. | bool |
false |
no |
| create_cloud_dns_record | Boolean to create Google Cloud DNS record for boundary_fqdn resolving to load balancer IP. cloud_dns_managed_zone is required when true. |
bool |
false |
no |
| create_key_ring | Boolean to create a KMS key ring for Boundary. | bool |
true |
no |
| create_recovery_key | Boolean to create a KMS recovery key for Boundary. | bool |
true |
no |
| create_root_key | Boolean to create a KMS root key for Boundary. | bool |
true |
no |
| create_worker_key | Boolean to create a KMS worker key for Boundary. | bool |
true |
no |
| disk_size_gb | Size in Gigabytes of root disk of Boundary instance(s). | number |
50 |
no |
| enable_iap | (Optional bool) Enable https://cloud.google.com/iap/docs/using-tcp-forwarding#console, defaults to true. |
bool |
true |
no |
| enable_session_recording | Boolean to enable session recording in Boundary. | bool |
false |
no |
| friendly_name_prefix | Friendly name prefix used for uniquely naming resources. This should be unique across all deployments | string |
n/a | yes |
| image_name | VM image for Boundary instance(s). | string |
"ubuntu-2404-noble-amd64-v20240607" |
no |
| image_project | ID of project in which the resource belongs. | string |
"ubuntu-os-cloud" |
no |
| initial_delay_sec | The number of seconds that the managed instance group waits before it applies autohealing policies to new instances or recently recreated instances | number |
300 |
no |
| instance_count | Target size of Managed Instance Group for number of Boundary instances to run. Only specify a value greater than 1 if enable_active_active is set to true. |
number |
1 |
no |
| key_ring_location | Location of KMS key ring. If not set, the region of the Boundary deployment will be used. | string |
null |
no |
| key_ring_name | Name of an existing KMS Key Ring to use for Boundary | string |
null |
no |
| machine_type | (Optional string) Size of machine to create. Default n2-standard-4 from https://cloud.google.com/compute/docs/machine-resource. |
string |
"n2-standard-4" |
no |
| postgres_availability_type | Availability type of Cloud SQL PostgreSQL instance. | string |
"REGIONAL" |
no |
| postgres_backup_start_time | HH:MM time format indicating when daily automatic backups of Cloud SQL for PostgreSQL should run. Defaults to 12 AM (midnight) UTC. | string |
"00:00" |
no |
| postgres_disk_size | Size in GB of PostgreSQL disk. | number |
50 |
no |
| postgres_insights_config | Configuration settings for Cloud SQL for PostgreSQL insights. | object({ |
{ |
no |
| postgres_key_name | Name of KMS Key to use for Cloud SQL for PostgreSQL encryption. | string |
null |
no |
| postgres_key_ring_name | Name of KMS Key Ring that contains KMS key to use for Cloud SQL for PostgreSQL database encryption. Geographic location of key ring must match location of database instance. | string |
null |
no |
| postgres_kms_cmek_name | Name of Cloud KMS customer managed encryption key (CMEK) to use for Cloud SQL for PostgreSQL database instance. | string |
null |
no |
| postgres_kms_keyring_name | Name of Cloud KMS Key Ring that contains KMS key to use for Cloud SQL for PostgreSQL. Geographic location (region) of key ring must match the location of the boundary Cloud SQL for PostgreSQL database instance. | string |
null |
no |
| postgres_machine_type | Machine size of Cloud SQL PostgreSQL instance. | string |
"db-custom-4-16384" |
no |
| postgres_maintenance_window | Optional maintenance window settings for the Cloud SQL for PostgreSQL instance. | object({ |
{ |
no |
| postgres_ssl_mode | Indicates whether to enforce TLS/SSL connections to the Cloud SQL for PostgreSQL instance. | string |
"ENCRYPTED_ONLY" |
no |
| postgres_version | PostgreSQL version to use. | string |
"POSTGRES_16" |
no |
| project_id | ID of GCP Project to create resources in. | string |
n/a | yes |
| recovery_key_name | Name of an existing KMS recovery key to use for Boundary | string |
null |
no |
| region | Region of GCP Project to create resources in. | string |
n/a | yes |
| root_key_name | Name of an existing KMS root key to use for Boundary | string |
null |
no |
| subnet_name | Existing VPC subnetwork for Boundary instance(s) and optionally Boundary frontend load balancer. | string |
n/a | yes |
| vpc | Existing VPC network to deploy Boundary resources into. | string |
n/a | yes |
| vpc_project_id | ID of GCP Project where the existing VPC resides if it is different than the default project. | string |
null |
no |
| worker_key_name | Name of an existing KMS worker key to use for Boundary | string |
null |
no |
| Name | Description |
|---|---|
| api_lb_ip_address | IP Address of the API Load Balancer. |
| boundary_fqdn | boundary_fqdn input. |
| boundary_url | URL of Boundary application based on boundary_fqdn input. |
| bsr_bucket_name | Name of the Google Cloud Storage bucket. |
| bsr_cloud_storage_endpoint_url | Google Cloud Storage endpoint URL. |
| bsr_hmac_key_access_id | Value of the Google Cloud Storage HMAC key access id. |
| bsr_hmac_key_secret | Value of the Google Cloud Storage HMAC key access id. |
| cluster_lb_ip_address | IP Address of the API Load Balancer. |
| created_boundary_bsr_key_name | Name of the created Boundary BSR KMS key. |
| created_boundary_keyring_name | Name of the created Boundary KMS key ring. |
| created_boundary_recovery_key_name | Name of the created Boundary recovery KMS key. |
| created_boundary_root_key_name | Name of the created Boundary root KMS key. |
| created_boundary_worker_key_name | Name of the created Boundary worker KMS key. |
| gcp_db_instance_ip | Cloud SQL DB instance IP. |
| google_sql_database_instance_id | ID of Cloud SQL DB instance. |
| provided_boundary_bsr_key_name | Name of the provided Boundary BSR KMS key. |
| provided_boundary_keyring_name | Name of the Provided Boundary KMS key ring. |
| provided_boundary_recovery_key_name | Name of the Provided Boundary recovery KMS key. |
| provided_boundary_root_key_name | Name of the Provided Boundary root KMS key. |
| provided_boundary_worker_key_name | Name of the Provided Boundary worker KMS key. |