Admin: Add GCP IaC (OpenTofu + Helm) deployment guide based on egovhealthcare/gcp_template (via create-page on MediaWiki MCP Server)

2026-09-02T08:17:52Z

Add GCP IaC (OpenTofu + Helm) deployment guide based on egovhealthcare/gcp_template (via create-page on MediaWiki MCP Server)

New page

{{Doc header
|type=guide
|domain=deployment
|title=Deploying Care with the GCP template
|order=2
}}

This guide covers deploying Care on Google Cloud using the '''[https://github.com/egovhealthcare/gcp_template gcp_template]''' repository — an infrastructure-as-code template built with '''OpenTofu''' and '''Helm'''. It provisions the entire platform (network, cluster, databases, storage, encryption keys) and then installs Care and its supporting services as Helm releases.

This is the '''recommended''' path for new GCP deployments. It replaces the older click-through console workflow described in [[Deployment/Providers/Gcp/Deploying Care on GKE|Deploying Care on GKE]], which relied on manually created resources, Cloud Source Repositories, and the <code>infra_template</code> manifests.

{{Note|1=The repository is the source of truth. Variable names, defaults, and chart values change over time — always check the repository's <code>README.md</code>, <code>environments/sample.tfvars</code>, and root <code>variables.tf</code> against the version you are deploying.}}

== What the template provisions ==

The template is split into four OpenTofu modules, each with its own state and its own <code>Makefile</code>.

{| class="wikitable"
|-
! Module
! Purpose
|-
| <code>pre-infra/</code>
| Project bootstrap — enables the required Google Cloud APIs and optionally creates the Cloud DNS zone.
|-
| <code>infra/</code>
| The core platform — VPC and subnets, the GKE cluster and node pools, Cloud SQL for PostgreSQL, Cloud Storage buckets, Cloud Armor, Workload Identity Federation for GitHub, an optional jump host, and optional Scribe credentials.
|-
| <code>KMS/</code>
| The KMS key ring and the customer-managed encryption keys used to encrypt Cloud Storage buckets and other resources.
|-
| <code>deploy/</code>
| The Kubernetes layer — namespace, Secrets and ConfigMaps, and the Helm releases for every application.
|}

Two further directories support these modules: <code>helm_charts/</code> holds the in-repo Helm charts, and <code>environments/</code> holds the sanitised tfvars template. Helper scripts for synchronising configuration with Secret Manager live in <code>scripts/</code>.

=== Applications installed by the deploy module ===

{| class="wikitable"
|-
! Chart
! What it runs
|-
| <code>care_be</code>
| The Care backend — the API deployment, the Celery worker, the Celery beat scheduler, and a database migration job. Includes optional HPAs for the API and the worker.
|-
| <code>care_fe</code>
| The Care frontend, served as a container behind the gateway.
|-
| <code>gateway</code>
| The Gateway API resources, the cert-manager <code>ClusterIssuer</code> and <code>Certificate</code>, the HTTP-to-HTTPS redirect, and the GCP gateway policy.
|-
| <code>redis</code>
| Redis, used as the Celery broker and the cache.
|-
| <code>metabase</code>
| Metabase, backed by its own Cloud SQL instance.
|-
| <code>dcm4chee</code>
| Optional. The DICOM stack — dcm4chee-arc, OpenLDAP, an nginx proxy, and the OHIF viewer. Enabled with <code>enable_dicom</code>.
|}

'''cert-manager''' itself is installed from the upstream Jetstack chart with the Gateway API integration enabled, so certificates are issued directly against the Gateway.

== Prerequisites ==

* '''OpenTofu''' and '''Helm''' installed locally.
* The '''Google Cloud SDK''' (<code>gcloud</code>), authenticated against the target project.
* A GCP project with billing enabled, and a project number.
* A '''GCS bucket''' to hold the OpenTofu remote state.
* Permission to read and write Secret Manager secrets in the project.
* Domain names for the frontend, the API, and (if used) Metabase and DICOM.

== Configuration ==

All configuration is supplied as a single tfvars file per environment. The canonical template is <code>environments/sample.tfvars</code>; the source of truth for every variable is the root <code>variables.tf</code>.

Real environment files are '''never committed'''. They live in Secret Manager under the naming convention <code>tofu-tfvars-<env></code>, and each module's <code>Makefile</code> pulls the file down at runtime before planning or applying.

{{Note|1=Only sanitised samples belong in the repository. Treat <code>environments/<env>.tfvars</code> on your workstation as a transient artefact.}}

=== Required environment variables ===

Set these before running any <code>make</code> target:

{| class="wikitable"
|-
! Variable
! Description
|-
| <code>PROJECT_ID</code>
| The GCP project ID. May also be supplied as <code>TF_VAR_project_id</code>.
|-
| <code>ENV_NAME</code>
| The environment name. May also be supplied as <code>TF_VAR_environment</code> or <code>TF_VAR_env_name</code>.
|-
| <code>BACKEND_BUCKET</code>
| The GCS bucket holding the OpenTofu state.
|}

<syntaxhighlight lang="bash">export BACKEND_BUCKET="<your-state-bucket>"
export PROJECT_ID="<your-gcp-project-id>"
export ENV_NAME="<environment-name>"</syntaxhighlight>

=== Preparing the tfvars file ===

# Copy the template: <code>cp environments/sample.tfvars environments/<env>.tfvars</code>
# Edit the values for your environment.
# Push it to Secret Manager so the modules can retrieve it:

<syntaxhighlight lang="bash">cd pre-infra
make push-tfvars PROJECT_ID=<gcp-project> ENV_NAME=<env></syntaxhighlight>

Override the default file path with <code>LOCAL_TFVARS_FILE=<path></code> if your file lives elsewhere.

=== Key configuration groups ===

The tfvars file is organised into the following groups. See <code>environments/sample.tfvars</code> for the full annotated template.

{| class="wikitable"
|-
! Group
! Notable variables
|-
| Environment identity
| <code>region</code>, <code>project_id</code>, <code>project_number</code>, <code>zones</code>, <code>zone</code>, <code>org</code>, <code>app</code>, <code>environment</code>
|-
| Domains and DNS
| <code>web_domain_name</code>, <code>api_domain_name</code>, <code>metabase_domain_name</code>, <code>dicom_domain_name</code>, <code>enable_dns_zone</code>, <code>dns_zone_domain</code>
|-
| Cluster
| <code>node_pools</code> (machine type, counts, disk, node locations, private nodes), <code>cluster_name</code>
|-
| Networking
| <code>database_subnets</code>, <code>gke_subnets</code>, <code>gke_pods_range</code>, <code>gke_services_range</code>, <code>proxy_only_subnet_cidr</code>
|-
| Databases
| <code>cloudsql_tier</code>, <code>cloudsql_disk_size</code>, <code>cloudsql_read_replica_count</code>, <code>cloudsql_read_replica_tier</code>, <code>metabase_cloudsql_tier</code>
|-
| Feature toggles
| <code>enable_dicom</code>, <code>enable_cloud_armor</code>, <code>enable_github_wif</code>, <code>enable_scribe</code>, <code>enable_jumphost</code>, <code>enable_legacy_ingress</code>, <code>enable_local_cors</code>
|-
| Applications
| <code>helm_config</code> — image repository and tag per service, plus the API and Celery worker autoscaling settings
|-
| Secrets and config
| <code>jwks_base64</code>, <code>additional_secrets</code>, <code>additional_config_map_data</code>
|-
| TLS
| <code>external_tls_cert</code>, <code>external_tls_key</code>, <code>external_tls_base_domains</code>
|}

{{Tip|1=Domain variables are '''lists''', even when you only have one hostname — <code>web_domain_name = ["app.example.org"]</code>. Cloud SQL sizing values are numbers, not quoted strings.}}

=== Node pools ===

Node pools are configured as a list of objects. Each entry sets the machine type, the autoscaling bounds, the disk size, the zones the pool spans, and whether the nodes are private.

<syntaxhighlight lang="hcl">node_pools = [
{
name = "default"
machine_type = "e2-standard-2"
min_count = 1
max_count = 2
preemptible = false
disk_size_gb = 100
node_locations = "asia-south1-a,asia-south1-b"
enable_private_nodes = true
},
]</syntaxhighlight>

=== Application images and autoscaling ===

<code>helm_config</code> selects the image for each service and controls the horizontal pod autoscalers on the Care backend. Autoscaling is CPU-based and scales on requests, so it only behaves sensibly when resource requests are set.

<syntaxhighlight lang="hcl">helm_config = {
care_backend = {
repository = "asia-south1-docker.pkg.dev/example-project/staging/care"
tag = "latest"
# api_autoscaling_enabled = true
# api_autoscaling_min_replicas = 2
# api_autoscaling_max_replicas = 6
# api_autoscaling_target_cpu = 80
}
care_frontend = {
repository = "asia-south1-docker.pkg.dev/example-project/staging/care_fe"
tag = "latest"
}
metabase = {
repository = "metabase/metabase"
tag = "v0.63.13"
}
redis = {
repository = "redis"
tag = "8-alpine"
}
}</syntaxhighlight>

=== TLS certificates ===

By default, cert-manager issues certificates for every configured hostname through the Gateway. If you already hold a wildcard certificate, supply it with <code>external_tls_cert</code>, <code>external_tls_key</code>, and <code>external_tls_base_domains</code>. cert-manager continues to issue certificates for any hostname the wildcard does not cover.

The deploy module also creates a self-signed placeholder certificate so the Gateway can come up before cert-manager has issued the real one.

== Deploying ==

Modules must be applied '''in order'''. The <code>deploy/</code> module reads remote state outputs from both <code>infra/</code> and <code>KMS/</code>, so those must exist first.

# <code>pre-infra/</code>
# <code>infra/</code>
# <code>KMS/</code>
# <code>deploy/</code>

{{Note|1=Confirm the module ordering against the <code>README.md</code> in the revision you are deploying. The relationship between <code>infra/</code> and <code>KMS/</code> has been revised, and the correct order depends on whether the infra module consumes KMS keys directly.}}

=== Per-module commands ===

Each module exposes the same targets. Run them from inside the module directory:

<syntaxhighlight lang="bash">make init BACKEND_BUCKET=<state-bucket>
make pull-tfvars PROJECT_ID=<gcp-project> ENV_NAME=<env>
make plan PROJECT_ID=<gcp-project> ENV_NAME=<env> BACKEND_BUCKET=<state-bucket>
make deploy PROJECT_ID=<gcp-project> ENV_NAME=<env> BACKEND_BUCKET=<state-bucket></syntaxhighlight>

<code>make plan</code> and <code>make deploy</code> both run <code>pull-tfvars</code> first, so the plan always reflects what is currently in Secret Manager. <code>make deploy</code> is interactive unless you pass <code>AUTO_APPROVE=true</code>.

Two further targets are available: <code>make lint</code> formats the OpenTofu files recursively, and <code>make destroy</code> tears the module down.

=== A full first deployment ===

<syntaxhighlight lang="bash">export BACKEND_BUCKET="<state-bucket>"
export PROJECT_ID="<gcp-project>"
export ENV_NAME="<env>"

cd pre-infra
make init BACKEND_BUCKET=$BACKEND_BUCKET
make plan PROJECT_ID=$PROJECT_ID ENV_NAME=$ENV_NAME BACKEND_BUCKET=$BACKEND_BUCKET
make deploy PROJECT_ID=$PROJECT_ID ENV_NAME=$ENV_NAME BACKEND_BUCKET=$BACKEND_BUCKET

cd ../infra
make init BACKEND_BUCKET=$BACKEND_BUCKET
make plan PROJECT_ID=$PROJECT_ID ENV_NAME=$ENV_NAME BACKEND_BUCKET=$BACKEND_BUCKET
make deploy PROJECT_ID=$PROJECT_ID ENV_NAME=$ENV_NAME BACKEND_BUCKET=$BACKEND_BUCKET

cd ../KMS
make init BACKEND_BUCKET=$BACKEND_BUCKET
make plan PROJECT_ID=$PROJECT_ID ENV_NAME=$ENV_NAME BACKEND_BUCKET=$BACKEND_BUCKET
make deploy PROJECT_ID=$PROJECT_ID ENV_NAME=$ENV_NAME BACKEND_BUCKET=$BACKEND_BUCKET

cd ../deploy
make init BACKEND_BUCKET=$BACKEND_BUCKET
make plan PROJECT_ID=$PROJECT_ID ENV_NAME=$ENV_NAME BACKEND_BUCKET=$BACKEND_BUCKET
make deploy PROJECT_ID=$PROJECT_ID ENV_NAME=$ENV_NAME BACKEND_BUCKET=$BACKEND_BUCKET</syntaxhighlight>

=== After the first apply ===

# Read the Gateway's external IP address from the cluster and create DNS '''A''' records for each hostname pointing at it.
# Wait for cert-manager to replace the placeholder certificate with an issued one.
# Confirm the migration job for the Care backend completed successfully before treating the deployment as live.

== Releasing a new version ==

Application releases are configuration changes, not infrastructure changes. To roll out a new Care build:

# Update the <code>tag</code> for the relevant service under <code>helm_config</code> in your environment's tfvars.
# Push the updated file to Secret Manager with <code>make push-tfvars</code>.
# Run <code>make plan</code> and then <code>make deploy</code> from the <code>deploy/</code> module.

Only the <code>deploy/</code> module needs to run — the platform modules are untouched.

The backend Helm chart annotates its pods with checksums of the rendered Secret and ConfigMap, so a change to configuration triggers a rollout automatically rather than leaving pods running with stale values.

== Operational notes ==

* '''Never commit real tfvars.''' Secret Manager is the only place environment configuration should live.
* '''Plan before every apply.''' <code>make plan</code> runs with <code>-lock=false</code>, so it is safe to run alongside other readers, but it will not protect you from a concurrent apply.
* '''Helm history is capped''' at ten revisions per release, which bounds how far back <code>helm rollback</code> can go.
* '''Legacy naming overrides''' exist for most resources (<code>cluster_name</code>, <code>vpc_network_name</code>, <code>namespace_name</code>, and others) so an existing deployment can be adopted into the template without renaming live infrastructure. Leave them unset for a greenfield deployment and let the naming convention apply.
* '''The jump host''' is optional and controlled by <code>enable_jumphost</code>. It takes its SSH keys from <code>jumphost_ssh_keys</code>. Disable it if you reach the cluster another way.

== See also ==

* [[Deployment/Providers/Gcp|Google Cloud overview]] — choosing between the deployment options on GCP.
* [[Deployment/Providers/Gcp/Deploying Care on GKE|Deploying Care on GKE]] — the earlier console-driven workflow.
* [[Deployment/Kubernetes/Reference architecture|Kubernetes reference architecture]] — the provider-agnostic production setup.
* [[Deployment/Security/Data security|Data security]] — security practices that apply to every deployment.

{{Navbox deployment}}

{{Related}}

Deployment/Providers/Gcp/Deploying Care with the GCP template - Revision history

Admin: Add GCP IaC (OpenTofu + Helm) deployment guide based on egovhealthcare/gcp_template (via create-page on MediaWiki MCP Server)