GCP Cloud Run

Prerequisites

  • formae CLI installed on your local machine - see local installation
  • Google Cloud CLI installed and authenticated (gcloud auth login)

Enable the required APIs:

gcloud services enable \
  sqladmin.googleapis.com \
  run.googleapis.com \
  secretmanager.googleapis.com \
  artifactregistry.googleapis.com

Set up the database

The agent needs a persistent database. Cloud SQL for PostgreSQL works well here.

If you already have a Cloud SQL instance, create a database and skip to configure the agent.

Create a Cloud SQL instance with a private IP on the default VPC:

gcloud sql instances create formae-db \
  --database-version=POSTGRES_16 \
  --tier=db-f1-micro \
  --region=<region> \
  --network=default \
  --no-assign-ip

--no-assign-ip disables the public IP. Cloud Run connects through a private VPC path.

Set the postgres password:

gcloud sql users set-password postgres \
  --instance=formae-db \
  --password=<password>

Create the database:

gcloud sql databases create formae \
  --instance=formae-db

Configure the agent

The agent config is stored in Secret Manager and mounted into the container at runtime.

Create a config file (formae.conf.pkl):

amends "formae:/Config.pkl"

agent {
  datastore {
    datastoreType = "postgres"
    postgres {
      host = "/cloudsql/<project-id>:<region>:formae-db"
      user = "postgres"
      password = "<password>"
      database = "formae"
    }
  }
}

The host is a Cloud SQL socket path - Cloud Run's built-in SQL proxy creates a Unix socket at this path.

Create the secret:

gcloud secrets create formae-config \
  --data-file=formae.conf.pkl

Create a service account

gcloud iam service-accounts create formae-agent \
  --display-name="Formae Agent"

Grant the roles it needs:

PROJECT_ID=$(gcloud config get-value project)

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:formae-agent@$PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/editor

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:formae-agent@$PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/cloudsql.client

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:formae-agent@$PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/secretmanager.secretAccessor
  • roles/editor - lets the GCP plugin manage infrastructure resources
  • roles/cloudsql.client - connects to Cloud SQL through the proxy
  • roles/secretmanager.secretAccessor - reads the mounted config secret

Set up Artifact Registry

Cloud Run cannot pull directly from ghcr.io. Create a remote repository that proxies it:

gcloud artifacts repositories create ghcr \
  --repository-format=docker \
  --location=<region> \
  --mode=remote-repository \
  --remote-docker-repo=https://ghcr.io

The formae image becomes available at <region>-docker.pkg.dev/<project-id>/ghcr/platform-engineering-labs/formae.

Deploy the agent

PROJECT_ID=$(gcloud config get-value project)

gcloud run deploy formae-agent \
  --image=<region>-docker.pkg.dev/$PROJECT_ID/ghcr/platform-engineering-labs/formae:latest \
  --region=<region> \
  --port=49684 \
  --no-cpu-throttling \
  --min-instances=1 \
  --max-instances=1 \
  --cpu=1 \
  --memory=1Gi \
  --service-account=formae-agent@$PROJECT_ID.iam.gserviceaccount.com \
  --add-cloudsql-instances=$PROJECT_ID:<region>:formae-db \
  --set-secrets=/config/formae.conf.pkl=formae-config:latest \
  --network=default \
  --subnet=default \
  --vpc-egress=private-ranges-only \
  --command="formae","agent","start","--config","/config/formae.conf.pkl"
  • --add-cloudsql-instances runs the Cloud SQL Auth Proxy as a sidecar, creating the Unix socket the agent connects through
  • --network / --subnet / --vpc-egress gives the container direct VPC egress so the proxy can reach the private IP instance
  • --no-cpu-throttling and --min-instances=1 keep the agent running continuously for discovery and synchronization

Verify

Cloud Run requires authentication by default. Use the built-in proxy to tunnel through:

gcloud run services proxy formae-agent --region=<region> --port=49684

In a separate terminal:

curl -s -o /dev/null -w "%{http_code}" http://localhost:49684/api/v1/health
# 200

Applying formas

The formae CLI runs on your local machine. It evaluates your Pkl files locally and sends the result to the agent API - no files need to be loaded into the container.

With the proxy running, the CLI connects to http://localhost:49684 by default. No additional configuration is needed.

Check connectivity:

formae status agent

Then apply a forma:

formae apply --mode reconcile your-forma.pkl

How authentication works

The formae GCP plugin uses Application Default Credentials (ADC). On Cloud Run, the service account's identity is available automatically through the metadata server - no env vars, no key files, no token refresh to manage.

See the GCP plugin docs for the full credential chain.

Next steps

Head to the quick start or see the configuration docs for available options.