Workload Configuration

In order to instrument Google Cloud Run workloads the Upwind Tracer will need to be utilized.

Configuring a workload to be instrumented with the tracer requires embedding the tracer as part of the container image directly at build time.

Prerequisites

Before you begin, you will need an Upwind client ID and client secret to allow the tracer to authenticate to the Upwind Platform. Your workload must also be able to connect to the internet in order to report telemetry to the Upwind Platform.

Value	Description	How to Get
Upwind Client ID	OAuth client ID for backend authentication	Upwind Console → Settings → API Credentials
Upwind Client Secret	OAuth client secret for backend authentication	Upwind Console → Settings → API Credentials

An additional requirement for Cloud Run workloads is that execution environment gen2 is selected in order to be able to utilize ptrace efficiently.

resource "google_cloud_run_v2_service" "workload" {
  template {
    execution_environment = "EXECUTION_ENVIRONMENT_GEN2"
  }
}

Add the Upwind Tracer to your Dockerfile

This step involves:

Adding a build stage.
Copying the Upwind Tracer binary into the workload image.
Setting the entrypoint to run the tracer, which then executes your application.

Below is a simple example of a Dockerfile with these additions:

# syntax=docker/dockerfile:1

# (1) Add the Upwind Tracer image as a build stage.
FROM public.ecr.aws/upwindsecurity/images/tracer:0.7.16 AS upwind-tracer

# (2) Copy the Upwind Tracer binary from the build stage into your workload image.
FROM workload-image

COPY --from=upwind-tracer /var/lib/upwind /var/lib/upwind

# (3) Set the default entrypoint to the Upwind Tracer, and pass the path
# to your application so the tracer can invoke it.
ENTRYPOINT ["/var/lib/upwind/upwind-tracer", "/path/to/your/app"]

If your image already defines an entrypoint/command, replace it with the tracer entrypoint and pass your original entrypoint/command as arguments.

Build and Push Image

After defining and creating your image, you need to push it to Artifact Registry or another supported registry and use it in a Cloud Run Service or Function. See the documentation for Google Cloud Run here.

Configure Tracer to Upwind Platform communication

The tracer pushes telemetry to the Upwind Platform. Configure your Cloud Run service or job with the following environment variables.

env {
  name  = "UPWIND_TRACER_REPORT_TO_BACKEND"
  value = "true"
}

env {
  name  = "UPWIND_TRACER_EXTENDED_SYSCALLS"
  value = "true"
}

env {
  name = "UPWIND_TRACER_AUTH_CLIENT_ID"
  value = {UPWIND_CLIENT_ID}
}

env {
  name = "UPWIND_TRACER_AUTH_CLIENT_SECRET"
  value = {UPWIND_CLIENT_SECRET}
}

In order for the tracer to identify layer 7 traffic (including HTTP requests) in Google Cloud Run, the tracer must monitor an extended set of syscalls, which is enabled by setting the UPWIND_TRACER_EXTENDED_SYSCALLS variable to true.

Handling secrets

Avoid hardcoding UPWIND_TRACER_AUTH_CLIENT_ID and UPWIND_TRACER_AUTH_CLIENT_SECRET directly in Terraform configuration or state. Use Google Cloud Secret Manager to store these values securely.

Using the Upwind Terraform module

Upwind provides a Terraform module that creates the necessary secrets in Google Cloud Secret Manager and manages IAM access for your Cloud Run service accounts.

module "upwind_gcp_cloud_run" {
  source = "https://get.upwind.io/terraform/modules/gcp-cloud-run/gcp-cloud-run-0.1.0.tar.gz"

  project_id           = var.project_id
  upwind_client_id     = var.upwind_client_id
  upwind_client_secret = var.upwind_client_secret
}

The module creates two secrets in Secret Manager (upwind-client-id and upwind-client-secret) and grants the secretAccessor role to your project's default compute service account.

Variable	Required	Default	Description
`project_id`	Yes	—	The GCP project ID
`upwind_client_id`	Yes	—	Upwind client ID (sensitive)
`upwind_client_secret`	Yes	—	Upwind client secret (sensitive)
`accessor_service_accounts`	No	`[]`	Service account emails to grant secret access. Defaults to the project's default compute SA
`labels`	No	`{}`	Labels to apply to the secrets
`resource_prefix`	No	`"upwind"`	Prefix for secret names (e.g. `upwind-client-id`)

Once the module is applied, reference the secrets in your Cloud Run service definition:

env {
  name = "UPWIND_TRACER_AUTH_CLIENT_ID"
  value_source {
    secret_key_ref {
      secret  = module.upwind_gcp_cloud_run.upwind_client_id_secret_name
      version = "latest"
    }
  }
}

env {
  name = "UPWIND_TRACER_AUTH_CLIENT_SECRET"
  value_source {
    secret_key_ref {
      secret  = module.upwind_gcp_cloud_run.upwind_client_secret_name
      version = "latest"
    }
  }
}

Deploy to Cloud Run (example)

Deploy the resulting image to Cloud Run and ensure the service uses the Gen2 execution environment. Environment variables are part of the Cloud Run service configuration, so they are typically set at deploy time (or when updating the service).

gcloud run deploy YOUR_SERVICE_NAME \
  --image YOUR_IMAGE \
  --region YOUR_REGION \
  --execution-environment gen2

Common gotchas

Gen1 vs Gen2: the tracer requires the Gen2 execution environment.
Entrypoint/args: ensure the container entrypoint is upwind-tracer and that it receives the command to start your application.
Missing credentials: if UPWIND_TRACER_AUTH_CLIENT_ID / UPWIND_TRACER_AUTH_CLIENT_SECRET are not set, telemetry will not be reported.

Prerequisites​

Add the Upwind Tracer to your Dockerfile​

Build and Push Image​

Configure Tracer to Upwind Platform communication​

Handling secrets​

Using the Upwind Terraform module​

Deploy to Cloud Run (example)​

Common gotchas​