Skip to main content
Version: 5.9.x

Setup on Google Cloud Platform


The instructions assume you have terraform installed on your machine, or use some automation like Atlantis to run apply for you.

Minimum supported versions for Workflows terraform code:

  • Terraform >= 1.4
  • Kubernetes Provider >= 2.0.1
  • Helm Provider >= 2.9.0
  • Google Provider >= 4.63.1

Enable required services

Enable the following APIs in your project:

You may need to wait a short while for the changes to propagate.

Setup a NAT

Your project's network requires a NAT in order for our runners to talk to the CI provider. If you don't already have one, you can use this terraform to set one up:

data "google_compute_network" "default" {
name = "default"

resource "google_compute_router" "router" {
name = "router"
network =

bgp {
asn = 64514

resource "google_compute_router_nat" "nat" {
name = "router-nat"
router =
nat_ip_allocate_option = "AUTO_ONLY"
source_subnetwork_ip_ranges_to_nat = "ALL_SUBNETWORKS_ALL_IP_RANGES"

Select a GCP Image

Aspect Workflows runs on GCE instances, not Kubernetes pods. Therefore the base image uses an GCP Image.

Select an image from Aspect's pre-built images.


In a later setup stage, we'll discuss how to build a custom GCP image if required to green up your build.

This bit of terraform can be used to locate the image at plan/apply-time:

data "google_compute_image" "runner_image" {
project = "my-project"
name = "my-workflows-runner-v1"

Add the terraform module

Our terraform module is currently delivered in a GCS bucket. You add it to your existing Terraform setup.

Here's an example:
module "aspect_workflows" {
# Replace 5.x.x with an actual version:
source = "gcs::"

# Ask us to generate a customer ID for your organization and input it here
customer_id = "MyCorp"

network =
subnetwork =

# Replace XXX with one of gha, cci, buildkite
hosts = ["XXX"]

k8s_cluster = {
node_count = 3
machine_type = "e2-highmem-4"

remote = {
cache_size_gb = 384
cache_shards = 3
replicate_cache = false
load_balancer_replicas = 2

resource_types = {
"default" = {
machine_type = "n1-standard-4"
image_id =

bk_runner_groups = {
default = {
max_runners = 10
resource_type = "default"
agent_idle_timeout_min = 90


Run terraform apply, or use whatever automation you already use for your Infrastructure-as-code such as Atlantis.

Increase quotas


New GCP projects start with a quota on the maximum number of CPUs which is usually too low and will prevent more than a handful of runners from starting up.

To request an increase, visit the quotas page for your project and request an increase on the number of CPUs allowed in your region.

How many CPUs you request depends on the runner machine_type you use. For example, if you use n1-standard-4 (4 vCPUs) runners and have a maximum of 10 agents, you'll want at least 40 CPUs just for the runners.

Leave an additional buffer for nodes that run in the Kubernetes cluster. Currently the cluster uses e2-medium instances (2 vCPUs), and the number of nodes is controlled by cluster_standard_node_count.

Next steps

Continue by choosing which CI platform you plan to interact with, and follow the corresponding installation steps.