FAQ | This is a LIVE service | Changelog

Skip to content
Snippets Groups Projects

GCP Cloud Run Terraform Module

This module manages the deployment of containerised applications on Cloud Run. It includes the following functionality:

  • Creation of the main Cloud Run service.
  • Creation of a dedicated service account with required IAM bindings.
  • Deployment of an optional load balancer configuration.
  • Deployment of an optional "pre-deployment" Cloud Run job to handle tasks such as database migrations.
  • Deployment of an optional static egress IP address for the Cloud Run service.
  • Configuration of simple uptime checks and SSL certificate expiry alerts.
  • Convenience variables to configure certain aspects of the Cloud Run service which would otherwise be complex, such as mounting Cloud SQL instances.

Cloud Run v2 API

Following release 9.0.0, this module has been refactored to use the Cloud Run v2 API resources exclusively (i.e. google_cloud_run_v2_service). This means that many input variables are now different and updating from a previous version will require some changes to your module definition.

Examples

See the docs/examples.md page for a full list of detailed usage examples.

Pre-deploy Cloud Run Job

The 8.0.0 release introduced the enable_pre_deploy_job variable which, when set to true, creates a Cloud Run job to execute a configurable command before new Cloud Run service revisions are deployed. This is a useful way to run database migrations and other commands which are tightly coupled to the release cadence of the main Cloud Run service.

The pre-deploy job is configured via the pre_deploy_job_* variables which can be found in variables.tf.

For more information on how the pre-deploy Cloud Run job works see the pre-deploy-job.md page.

Requirements

Name Version
terraform ~> 1.3
google >= 4.0
null ~> 3.0

Inputs

Name Description Type Default Required
alerting_notification_channels A list of notification channel IDs to send uptime alerts to. The format for
the channel IDs should be
"projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]".
list(string) [] no
alerting_success_threshold_percent If the percentage of successful uptime checks within the given uptime period
falls below this, an alert will be triggered. Set to 100 to trigger an alert
if any uptime check fails, set to a lower number to tolerate failures without
alerting.

Experience has taught us that uptime checks can fail semi-regularly due to
transient problems outside our control, therefore we allow some leeway before
triggering an alert.
number 75 no
alerting_uptime_period Frequency of uptime checks string "300s" no
alerting_uptime_timeout Timeout for http polling. string "30s" no
allow_unauthenticated_invocations If true, the webapp will allow unauthenticated invocations. If false, the
webapp requires authentication as a Google user with the Cloud Run invoker
permission on the deployment.
bool true no
containers Configure one or more container instances for the service. See
https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#nested_containers
for information on the available arguments.
map(object({
name = optional(string)
image = string
command = optional(list(string))
args = optional(list(string))
env = optional(list(object({
name = string
value = optional(string)
value_source = optional(object({
secret_key_ref = optional(object({
secret = string
version = optional(string, "latest")
}))
}))
})), [])
resources = optional(object({
limits = optional(map(string))
cpu_idle = optional(bool)
startup_cpu_boost = optional(bool)
}))
ports = optional(list(object({
name = optional(string)
container_port = optional(number)
})), [])
volume_mounts = optional(list(object({
name = string
mount_path = string
})), [])
working_dir = optional(string)
liveness_probe = optional(object({
initial_delay_seconds = optional(number)
timeout_seconds = optional(number)
period_seconds = optional(number)
failure_threshold = optional(number)
http_get = optional(object({
path = optional(string)
port = optional(number)
http_headers = optional(list(object({
name = string
value = optional(string)
})), [])
}))
grpc = optional(object({
port = optional(number)
service = optional(string)
}))
}))
startup_probe = optional(object({
initial_delay_seconds = optional(number)
timeout_seconds = optional(number)
period_seconds = optional(number)
failure_threshold = optional(number)
http_get = optional(object({
path = optional(string)
port = optional(number)
http_headers = optional(list(object({
name = string
value = optional(string)
})), [])
}))
tcp_socket = optional(object({
port = number
}))
grpc = optional(object({
port = optional(number)
service = optional(string)
}))
}))
}))
n/a yes
create_ipv6_address Allocate an IPv6 address to the load balancer if var.enable_ipv6 is true. bool false no
description A description for the Cloud Run service. string null no
dns_names DNS names to configure for the web application. Note that DNS records are
_NOT_ created, they are used in the load balancer module to ensure the SSL
certificate is generated with the required SANs. The map's keys are arbitrary
and are only required to avoid errors when the DNS name is a value which
Terraform does not know until after the apply operation.

For example:

{ my_awesome_dns_name = "awesome.example.com" }
map(string) {} no
enable_alerting Enable alerting policies. bool true no
enable_ipv6 Whether to enable IPv6 address on the CDN load-balancer. bool false no
enable_load_balancer Whether to configure a load balancer or use the default run.app generated
hostname.
bool false no
enable_monitoring Optional. If true, create uptime and SSL expiry checks.

Note that this is different from not specifying an alerting email address. If
no alerting email address is specified the uptime checks are still created,
they just don't alert if they fail.
bool false no
enable_pre_deploy_job Configure a Cloud Run Job to be executed before the main Cloud Run service
is deployed. This is useful for running database migrations for example.
bool false no
enable_static_egress_ip Whether to assign a static ip for egress from this cloud run instance. If
enabled, the "vpcaccess.googleapis.com" API must also be enabled on the
project.
bool false no
encryption_key The ID of a customer managed encryption key (CMEK) to use to encrypt this
container image.
string null no
execution_environment The sandbox environment to host this revision. Possible values are
EXECUTION_ENVIRONMENT_GEN1, and EXECUTION_ENVIRONMENT_GEN2.
string "EXECUTION_ENVIRONMENT_GEN1" no
grant_sql_client_role_to_webapp_sa When set to true the roles/cloudsql.client role will be granted to the webapp
service account at the project level to allow it to connect to Cloud SQL.
bool false no
ingress The ingress setting for the Cloud Run service. Possible values are
INGRESS_TRAFFIC_ALL, INGRESS_TRAFFIC_INTERNAL_ONLY, and
INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER.

If var.use_load_balancer == true, the provided var.ingress will be ignored and
the ingress will be set automatically to
"INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER".
string "INGRESS_TRAFFIC_ALL" no
launch_stage The launch stage for the Cloud Run service. Possible values are UNIMPLEMENTED,
PRELAUNCH, EARLY_ACCESS, ALPHA, BETA, GA, and DEPRECATED.
string "GA" no
max_instance_request_concurrency Sets the maximum number of requests that each serving instance can receive. number null no
min_ports_per_vm When using Cloud NAT to provide an egress route, Cloud NAT's minimum ports per
VM can be configured to determine how many concurrent connections can be
established to the same destination IP address and port.
number 64 no
monitoring_path Path component of url to be monitored. string "/" no
monitoring_scoping_project The ID of a Cloud Monitoring scoping project to create monitoring resources
in. If omitted, var.project will be used instead.
string null no
mount_cloudsql_instance Mount a single CloudSQL instance in each container for the service. This value
should be the Cloud SQL instance connection name, for example
"example-devel-e662dd2b:europe-west2:sql-6e1dd60b". This is a convenience
variable to simplify mounting a single Cloud SQL instance. If you require more
control you can define one or more Cloud SQL mounts directly using
var.containers and var.volumes instead.
string null no
name Prefix used to form resource names. string "webapp" no
pre_deploy_job_annotations Map of key/value pairs containing annotations to assign to the pre-deploy Cloud
Run job.
map(string) null no
pre_deploy_job_container Configure the container instance for the pre-deploy job. See
https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_job#nested_containers
for more information on these options.
object({
name = optional(string)
image = optional(string)
command = optional(list(string))
args = optional(list(string))
env = optional(list(object({
name = string
value = optional(string)
value_source = optional(object({
secret_key_ref = optional(object({
secret = string
version = optional(string, "latest")
}))
}))
})), [])
resources = optional(object({
limits = optional(map(string))
}))
ports = optional(list(object({
name = optional(string)
container_port = optional(number)
})), [])
volume_mounts = optional(list(object({
name = string
mount_path = string
})), [])
working_dir = optional(string)
})
null no
pre_deploy_job_encryption_key The ID of a customer managed encryption key (CMEK) to use to encrypt this
container image.
string null no
pre_deploy_job_execution_environment The execution environment to host this task. Possible values are
EXECUTION_ENVIRONMENT_GEN1, and EXECUTION_ENVIRONMENT_GEN2
string "EXECUTION_ENVIRONMENT_GEN2" no
pre_deploy_job_force When true, and only when used in addition to var.pre_deploy_job_trigger, the
pre-deploy Cloud Run job is executed at every terraform apply, regardless of
# the status of var.pre_deploy_job_container.image.
bool false no
pre_deploy_job_labels Map of key/value pairs containing labels to assign to the pre-deploy Cloud Run
job.
map(string) null no
pre_deploy_job_launch_stage The launch stage for the pre-deploy Cloud Run job. Possible values are UNIMPLEMENTED,
PRELAUNCH, EARLY_ACCESS, ALPHA, BETA, GA, and DEPRECATED.
string "GA" no
pre_deploy_job_max_retries Configure the maximum number of retries for the pre-deploy job. number null no
pre_deploy_job_mount_cloudsql_instance Mount a CloudSQL instance in the pre-deploy job container. This is a
convenience variable to simplify mounting a Cloud SQL instance. However, if
you require more control over this you should define it directly in
var.pre_deploy_job_container instead.
string null no
pre_deploy_job_parallelism Specifies the maximum desired number of tasks the execution should run at
given time.
number null no
pre_deploy_job_task_count Specifies the desired number of tasks the execution should run. number null no
pre_deploy_job_timeout Configure a timeout, in seconds, for the pre-deploy job. string null no
pre_deploy_job_trigger When true, the pre-deploy Cloud Run job is executed via a
null_resource-triggered gcloud command whenever Terraform detects that
var.pre_deploy_job_container.image has changed.
bool true no
pre_deploy_job_volumes Configure one or more volumes for the pre-deploy job. See
https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_job#nested_volumes
for more information on these options.
list(object({
name = string
secret = optional(object({
secret = string
default_mode = optional(number)
items = optional(list(object({
path = string
version = optional(string)
mode = optional(number)
})), [])
}))
cloud_sql_instance = optional(object({
instances = optional(list(string))
}))
}))
[] no
pre_deploy_job_vpc_access Configure VPC access for the pre-deploy job. See
https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_job#nested_vpc_access
for more information on these options.
object({
connector = optional(string)
egress = optional(string)
network_interfaces = optional(object({
network = optional(string)
subnetwork = optional(string)
tags = optional(string)
}))
})
null no
project Project containing the webapp. string n/a yes
region Location used to create Cloud Run service and other resources. string n/a yes
revision The unique name for the revision. If this field is omitted, it will be
automatically generated based on the Service name.
string null no
scaling The minimum number of auto-scaled instances defaults to 0, thus, the container
will stop if it doesn't receive requests for a period of time and the
following request will make the container start from cold. This should be
carefully considered for containers that take a significant amount of time
starting from cold.

For a container with N-workers, the maximum number of auto-scaled instances
should be less than 1/N of the maximum connection count for the Cloud SQL
instance.
object({
min_instance_count = optional(number)
max_instance_count = optional(number)
})
null no
service_account_display_name If non-empty, override the default display name of the webapp service account. string "" no
service_account_id A service account is always created for the web application. If non-empty this
variable overrides the default service account id. The default id is formed
from the "name" variable value with "-run" appended.
string "" no
service_annotations Map containing additional annotations to be added to the Cloud Run service
itself.
map(string) {} no
service_labels A set of key/value label pairs to assign to the Cloud Run service. map(string) {} no
session_affinity Enables session affinity. For more information, go to
https://cloud.google.com/run/docs/configuring/session-affinity.
bool null no
sql_instance_project Project containing SQL instance. Defaults to var.project. string null no
ssl_certificates A list of self-links to any custom TLS certificates to add to the load
balancer. Requires that var.use_load_balancer be "true". The self-link is
available as the "self_link" attribute of "google_compute_ssl_certificate"
resources.
list(any) [] no
ssl_policy By default, the google_compute_ssl_policy.default SSL policy is applied to the
load balancer in load_balancer.tf. This sets the SSL profile to MODERN and
restricts TLS to >= 1.2. If a different SSL policy is required, it should be
created outside of this module and its ID passed through using this variable.
string null no
static_egress_ip_cidr_range The cidr range used to create a subnet that this cloud run will use if assigned
a static ip
string "10.124.0.0/28" no
static_egress_ip_subnetwork_id When using an existing VPC Access Connector with the static egress IP
configuration an existing subnetwork must be provided.
string null no
template_annotations Map containing additional annotations to be added to the Cloud Run service
template.
map(string) {} no
template_labels A set of key/value label pairs to assign to the Cloud Run service revision. map(string) {} no
timeout_seconds The maximum duration, in seconds, the instance is allowed for responding to a
request. Maximum is 900s.
string "300s" no
traffic Configure traffic allocation between one or more service revisions.
list(object({
type = optional(string)
revision = optional(string)
percent = optional(number)
tag = optional(string)
}))
[] no
use_ssl_certificates Whether to use the custom TLS certs in var.ssl_certificates for the load
balancer or the Google-managed certs for the specified var.dns_names.
bool false no
volumes Configure one or more volumes for the service. See
https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#nested_volumes
for more information on these options.
list(object({
name = string
secret = optional(object({
secret = string
default_mode = optional(number)
items = optional(list(object({
path = string
version = optional(string)
mode = optional(number)
})), [])
}))
cloud_sql_instance = optional(object({
instances = optional(list(string))
}))
}))
[] no
vpc_access Configure VPC access for the Cloud Run service. For more information on these
options see
https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#nested_vpc_access
object({
connector = optional(string)
egress = optional(string)
network_interfaces = optional(object({
network = optional(string)
subnetwork = optional(string)
tags = optional(string)
}))
})
null no
vpc_access_connector_max_throughput Optional. The maximum throughput of the connector in megabytes per second.
Defaults to 300.
number 300 no

Outputs

Name Description
load_balancer Load balancer for the webapp
network_endpoint_group Network endpoint group for the load balancer.
service Webapp Cloud Run service resource
service_account Service account which service runs as
ssl_policy The ssl_policy object, if one is being created.
static_egress_ip The static egress IP assigned to this cloud run instance. Only populated
if the variable enable_static_egress_ip is true.