Terraform¶

Helmless provides a Terraform shell for your application container, which you can then use in your Terraform code to link the application container to the underlying infrastructure. It does this by using the lifecycle > ignore_changes block of the Terraform resource, ignoring all fields that are managed by Helmless.

You can either use the Helmless modules directly or create your own shell.

Helmless Cloud Run Service Terraform Module¶

The Helmless Cloud Run Service Terraform Module is a Terraform module that is used to create a shell for your application container. It is located in the helmless/google-cloudrun-service-terraform-module repository.

module "github_federation" {
  source              = "github.com/helmless/google-workload-identity-federation-terraform-module?ref=v0.1.0"
  id                  = "github"
  github_organization = "helmless"
}

module "cloudrun_service" {
  # source = "github.com/helmless/google-cloudrun-service-terraform-module?ref=v0.1.2" # x-release-please-version
  source = "../"
  name   = "example-service"

  create_service_account = true
  deployment_accounts    = ["${module.github_federation.repository_principal_set_id_prefix}/example-repository"]
}

The workload identity federation is used to securely connect Github Actions to GCP and give it the necessary permissions to deploy the application container. See below or in the CI/CD documentation for more details.

Creating your own shell¶

If you don't want to use the Helmless Cloud Run Service Terraform Module, you can create your own shell by using the lifecycle > ignore_changes block of the Terraform resource.

resource "google_cloud_run_v2_service" "cloud_run_service" {
  ...
  # This will make the app pipeline with Helmless the authoritive source of truth for the service.
  lifecycle {
    ignore_changes = [
      binary_authorization,
      client,
      client_version,
      description,
      ingress,
      labels,
      launch_stage,
      template,
      traffic,
    ]
  }
}

A module for the job is in progress, for now you can use the same approach and make the module yourself. Contributions are welcome!

resource "google_cloud_run_v2_job" "cloud_run_job" {
  ...
  lifecycle {
    ignore_changes = [
      binary_authorization,
      client,
      client_version,
      labels,
      launch_stage,
      location,
      template,
    ]
  }
}

Workload Identity Federation¶

To allow your Github organization to access your GCP organization, you need to setup Github Workload Identity Federation once somewhere in a project of your organization.

To make this as easy as possible, we created a small Terraform module that can be used to setup the necessary resources in your GCP project.

Deploy it however you deploy your infrastructure and make sure to update the github_organization variable to match your Github organization.

workload-identity.tf

module "github_federation" {
  source              = "github.com/helmless/google-workload-identity-federation-terraform-module?ref=v0.1.0"
  github_organization = "helmless"
}

Applying this module you will get:

a workload identity pool (1)
a workload identity provider for your Github repository (2)
- that only allows repositories in your Github organization to authenticate with the workload identity pool

A workload identity pool is a container for your workload identities. It uses the google_iam_workload_identity_pool Terraform resource.
A workload identity provider is a reference to the Github OIDC identity provider. It uses the google_iam_workload_identity_pool_provider Terraform resource and is scoped to only allow tokens issued by Github and from repositories in your specified organization.

Creating Cloud Run Services with IAM¶

After setting up the workload identity federation, you can create the individual Cloud Run services and grant your Github repositories the necessary permissions to deploy to them.

principalSet

The principalSet is similar to a serviceAccount but is tightly coupled to a workload identity pool. It is the safest way to grant permissions to a repository. You can use this for more than just Cloud Run, it can be used for almost any resource in GCP. The helmless/google-workload-identity-federation-terraform-module//repository sub module takes care of creating the somewhat complicated format of the principalSet for you.

cloudrun.tf

locals {
  github_organization = "helmless"
  repositories = [
    "helmless",
    "google-cloudrun-action",
    "google-cloudrun-charts"
  ]
}

module "workload_identity" {
  for_each = toset(local.repositories)
  source   = "github.com/helmless/google-workload-identity-federation-terraform-module//repository?ref=v0.2.0"

  repository = "${local.github_organization}/${each.key}" # (1)
}

module "cloudrun_service_e2e_test" {
  source = "github.com/helmless/google-cloudrun-service-terraform-module?ref=v0.1.2"

  name   = "full-service" # (2)
  region = "europe-west1"

  deployment_accounts    = values(module.workload_identity).*.principal_set # (3)
  create_service_account = true # (4)

  deletion_protection = false
}

Use your own github_organization and repositories to create the correct principalSet for your repositories.
This name must match the name in the values.yaml of your Helmless deployment.
The deployment account is a list of repository principals that will be granted the roles/run.admin role on the Cloud Run service in order to deploy it. In a real scenario this will just be one repository.
By default the module will create a new service account just for the Cloud Run service. This is best practice as it allows you to scope the permissions to the individual service account. You must set the serviceAccountName in your values.yaml to use this.

Project wide permissions¶

You can also grant your repositories project wide permissions to create and deploy Cloud Run services. This is more permissive and should only be used in a development environment or for dynamic creation of feature branch deployments for example. By default Helmless will create the Cloud Run service if it doesn't exist yet.

cloud_deploy.tf

locals {
  repositories = [
    "helmless",
    "google-cloudrun-action",
    "google-cloudrun-charts",
    "google-cloudrun-example"
  ]
}

data "google_project" "project" {}

module "principal_set" {
  for_each = toset(local.repositories)
  source   = "github.com/helmless/google-workload-identity-federation-terraform-module//repository?ref=v0.2.0"

  repository = "${local.github_organization}/${each.key}" # (1)
}

resource "google_project_iam_member" "run_admin" {
  for_each = toset(local.repositories)
  project  = data.google_project.project.project_id
  role     = "roles/run.admin"
  member   = module.principal_set[each.key].principal_set # (2)
}

resource "google_service_account_iam_member" "cloud_run_service_account_user" {
  for_each = toset(local.repositories)

  service_account_id = "projects/${data.google_project.project.project_id}/serviceAccounts/${data.google_project.project.number}-compute@developer.gserviceaccount.com" # (3)
  role               = "roles/iam.serviceAccountUser"
  member             = module.principal_set[each.key].principal_set # (4)
}

Use your own github_organization and repositories to create the correct principalSet for your repositories.
This grants every repository listed above the roles/run.admin role in the whole GCP project.
This is the default Cloud Run service account used if no specific service account is specified in the values.yaml.
The roles/iam.serviceAccountUser is required by Cloud Run to deploy the service.

Success

You have now setup the necessary resources to allow your Github repository to access your GCP project and to deploy your container to Google Cloud Run.