openlattice-cloudrun

Google Cloud Run compute provider for OpenLattice. Deploys containers as fully managed Cloud Run services, with exec via Cloud Run Jobs and logs via Cloud Logging.

Install

npm install openlattice openlattice-cloudrun

Quick Start

import { OpenLattice } from "openlattice";
import { CloudRunProvider } from "openlattice-cloudrun";

const lattice = new OpenLattice({
  providers: [
    new CloudRunProvider({
      projectId: "my-gcp-project",
      region: "us-central1",
      authMethod: "metadata", // or "service-account" / "token"
    }),
  ],
});

const node = await lattice.provision(
  {
    runtime: { image: "gcr.io/my-project/my-app:latest" },
    cpu: { cores: 1 },
    memory: { sizeGiB: 0.5 },
    network: { ports: [{ port: 8080 }] },
  },
  { id: "agent-1", type: "agent" }
);

const result = await lattice.exec(node.id, ["python", "-c", "print('hello')"]);
console.log(result.stdout);

await lattice.destroy(node.id);

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | projectId | string | required | GCP project ID | | region | string | "us-central1" | Cloud Run region | | authMethod | "metadata" \| "service-account" \| "token" | "metadata" | Authentication method | | serviceAccountKeyPath | string | — | Path to SA key JSON (when authMethod is "service-account") | | accessToken | string | — | Static token (when authMethod is "token"). Also reads GOOGLE_ACCESS_TOKEN env var | | maxInstances | number | 1 | Max instance count per service | | minInstances | number | 0 | Min instances (0 = scale-to-zero) | | concurrency | number | 80 | Request concurrency per instance | | serviceAccount | string | — | Service account email for the Cloud Run service identity | | vpcConnector | string | — | VPC connector name for private networking | | defaultLabels | Record<string, string> | — | Labels applied to all services |

Authentication

Three methods are supported:

Metadata server (default) — for code running on GCP (GCE, GKE, Cloud Run, etc.):

new CloudRunProvider({ projectId: "my-project" })

Service account key — for local development or CI:

new CloudRunProvider({
  projectId: "my-project",
  authMethod: "service-account",
  serviceAccountKeyPath: "/path/to/key.json",
})

Static token — for short-lived scripts or testing:

new CloudRunProvider({
  projectId: "my-project",
  authMethod: "token",
  accessToken: "ya29.a0...",
})

Tokens are cached with a 5-minute expiry buffer and refreshed automatically.

Capabilities

| Capability | Supported | |------------|-----------| | Provision / Exec / Destroy | Yes | | Stop / Start | Yes (via traffic routing) | | Pause / Resume | No | | Snapshots | No | | GPU | No | | Logs | Yes (Cloud Logging, with follow mode) | | Tailscale | No | | File Operations | No | | Persistent Storage | No |

How It Works

Provision

Creates a Cloud Run service via the Admin API v2. Maps ComputeSpec fields to the service template (image, CPU, memory, ports, env, scaling). Configures startup and liveness probes on /health. Polls the long-running operation until the service is ready, then returns the service's HTTPS endpoint.

Exec

Cloud Run services don't support shell exec. Instead, the provider creates a one-off Cloud Run Job using the same container image, runs it, retrieves stdout/stderr from Cloud Logging, then cleans up the job. Supports cwd, env, and timeoutMs options.

Stop / Start

Implemented via traffic routing. Stop patches traffic to 0% (the service still exists but receives no requests). Start restores traffic to 100%.

Logs

Queries the Cloud Logging API for entries matching the service. Supports tail, since, and follow options. Follow mode polls every 2 seconds for new entries.

Cost Estimation

getCost() returns a rough estimate based on Cloud Run per-second pricing for vCPU and memory, computed from the service's resource limits and uptime since creation.

Required GCP Permissions

The authenticated principal needs these IAM roles (or equivalent permissions):

• roles/run.admin — create, update, delete Cloud Run services and jobs
• roles/logging.viewer — read logs from Cloud Logging

Development

npm run build    # Compile TypeScript
npm run test     # Run unit tests (mocked, no GCP needed)

Integration tests require a real GCP project:

CLOUDRUN_PROJECT_ID=my-project CLOUDRUN_ACCESS_TOKEN=ya29... npm run test:integration