Skip to content

A Terraform module for provisioning and installing Boundary Enterprise Controller on Google Compute Engine as described in HashiCorp Validated Designs

License

Notifications You must be signed in to change notification settings

hashicorp/terraform-google-boundary-enterprise-controller-hvd

Boundary Enterprise Controller HVD on GCP GCE

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.

Prerequisites

General

  • Terraform CLI >= 1.9 installed on workstations.
  • Git CLI 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).

Google

  • GCP Project Created
  • Following APIs enabled
    • dns.googleapis.com
    • secretmanager.googleapis.com
    • compute.googleapis.com
    • servicenetworking.googleapis.com
    • cloudkms.googleapis.com
    • networkservices.googleapis.com

Networking

  • 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

Secrets Manager

  • 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.

Compute

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

Usage

  1. Create/configure/validate the applicable prerequisites.

  2. 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.

  3. 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 sandbox environment, and one for their production environment. This is recommended, but not required.

  4. (Optional) Uncomment and update the gcs remote state backend configuration provided in the backend.tf file 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.

  5. Populate your own custom values into the terraform.tfvars.example file that was provided, and remove the .example file extension such that the file is now named terraform.tfvars.

  6. Navigate to the directory of your newly created Terraform configuration for your Boundary Controller deployment, and run terraform init, terraform plan, and terraform apply.

  7. After your terraform apply finishes 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 -f argument is to follow the logs as they append in real-time, and is optional. You may remove the -f for 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!
  8. 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
  9. 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

  10. Use the terraform-google-boundary-worker-hvd module to deploy ingress, egress, etc workers as needed.

Docs

Below are links to docs pages related to deployment customizations and day 2 operations of your Boundary Controller instance.

Module support

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.

Requirements

Name Version
terraform ~> 1.9
google ~> 5.39
google-beta ~> 5.39
random ~> 3.6

Providers

Name Version
cloudinit n/a
google ~> 5.39
google-beta ~> 5.39
random ~> 3.6

Resources

Name Type
google-beta_google_project_service_identity.cloud_sql_sa resource
google-beta_google_sql_database_instance.boundary resource
google_compute_address.api resource
google_compute_address.cluster resource
google_compute_firewall.allow_9200 resource
google_compute_firewall.allow_9201 resource
google_compute_firewall.allow_iap resource
google_compute_firewall.allow_ssh resource
google_compute_firewall.health_checks resource
google_compute_forwarding_rule.api resource
google_compute_forwarding_rule.cluster resource
google_compute_global_address.postgres_private_ip resource
google_compute_health_check.boundary_auto_healing resource
google_compute_instance_template.boundary resource
google_compute_region_backend_service.api resource
google_compute_region_backend_service.cluster resource
google_compute_region_health_check.api resource
google_compute_region_health_check.cluster resource
google_compute_region_instance_group_manager.boundary resource
google_compute_region_target_tcp_proxy.cluster resource
google_dns_record_set.boundary resource
google_kms_crypto_key.bsr resource
google_kms_crypto_key.recovery resource
google_kms_crypto_key.root resource
google_kms_crypto_key.worker resource
google_kms_crypto_key_iam_binding.cloud_sql_sa_postgres_cmek resource
google_kms_crypto_key_iam_binding.gcp_project_gcs_cmek resource
google_kms_crypto_key_iam_member.created_bsr_operator resource
google_kms_crypto_key_iam_member.created_bsr_viewer resource
google_kms_crypto_key_iam_member.created_recovery_operator resource
google_kms_crypto_key_iam_member.created_recovery_viewer resource
google_kms_crypto_key_iam_member.created_root_operator resource
google_kms_crypto_key_iam_member.created_root_viewer resource
google_kms_crypto_key_iam_member.created_worker_operator resource
google_kms_crypto_key_iam_member.created_worker_viewer resource
google_kms_crypto_key_iam_member.existing_bsr_operator resource
google_kms_crypto_key_iam_member.existing_bsr_viewer resource
google_kms_crypto_key_iam_member.existing_recovery_operator resource
google_kms_crypto_key_iam_member.existing_recovery_viewer resource
google_kms_crypto_key_iam_member.existing_root_operator resource
google_kms_crypto_key_iam_member.existing_root_viewer resource
google_kms_crypto_key_iam_member.existing_worker_operator resource
google_kms_crypto_key_iam_member.existing_worker_viewer resource
google_kms_key_ring.kms resource
google_secret_manager_secret_iam_member.boundary_cert resource
google_secret_manager_secret_iam_member.boundary_license resource
google_secret_manager_secret_iam_member.boundary_privkey resource
google_secret_manager_secret_iam_member.ca_bundle resource
google_service_account.boundary resource
google_service_account.bsr resource
google_service_account_key.boundary resource
google_service_account_key.bsr resource
google_sql_database.boundary resource
google_sql_user.boundary resource
google_storage_bucket.bsr resource
google_storage_bucket_iam_member.bsr_object_admin resource
google_storage_bucket_iam_member.bsr_reader resource
google_storage_hmac_key.bsr resource
random_id.gcs_key_ring_suffix resource
random_id.gcs_suffix resource
random_id.postgres_suffix resource
cloudinit_config.boundary_cloudinit data source
google_client_config.default data source
google_compute_image.boundary data source
google_compute_network.vpc data source
google_compute_subnetwork.subnet data source
google_compute_zones.up data source
google_dns_managed_zone.boundary data source
google_kms_crypto_key.bsr data source
google_kms_crypto_key.bsr_key data source
google_kms_crypto_key.postgres data source
google_kms_crypto_key.recovery data source
google_kms_crypto_key.root data source
google_kms_crypto_key.worker data source
google_kms_key_ring.bsr_gcs data source
google_kms_key_ring.kms data source
google_kms_key_ring.postgres data source
google_project.current data source
google_secret_manager_secret_version.boundary_database_password data source
google_storage_project_service_account.project data source

Inputs

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)
[
"0.0.0.0/0"
]
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)
[
"0.0.0.0/0"
]
no
cidr_ingress_ssh_allow CIDR ranges to allow SSH traffic inbound to Boundary instance(s) via IAP tunnel. list(string)
[
"10.0.0.0/16"
]
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({
query_insights_enabled = bool
query_plans_per_minute = number
query_string_length = number
record_application_tags = bool
record_client_address = bool
})
{
"query_insights_enabled": false,
"query_plans_per_minute": 5,
"query_string_length": 1024,
"record_application_tags": false,
"record_client_address": false
}
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({
day = number
hour = number
update_track = string
})
{
"day": 7,
"hour": 0,
"update_track": "stable"
}
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

Outputs

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.

About

A Terraform module for provisioning and installing Boundary Enterprise Controller on Google Compute Engine as described in HashiCorp Validated Designs

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Packages

No packages published