@caelo-cms/provisioning 0.10.46 → 0.10.48

package/src/gcloud-runner.test.ts

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The gcloud runners against a fake `gcloud` on PATH: they must never leave
+ * gcloud able to wait on a prompt nobody sees (regression: `admin-domain
+ * enable` hung on gcloud's hidden "install the beta component? (Y/n)").
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gcloud, gcloudEnv } from "./gcloud.js";
+import { runCli } from "./regions.js";
+
+// Echoes the prompt switch, then waits for one line on stdin, like gcloud's
+// "(Y/n)" prompt does. With an open, never-ended stdin this blocks forever.
+const FAKE_GCLOUD = `#!/bin/sh
+echo "prompts=$CLOUDSDK_CORE_DISABLE_PROMPTS"
+read -r answer
+echo "answer=$answer"
+`;
+
+let dir = "";
+const originalPath = process.env.PATH;
+
+beforeAll(() => {
+  dir = mkdtempSync(join(tmpdir(), "caelo-fake-gcloud-"));
+  writeFileSync(join(dir, "gcloud"), FAKE_GCLOUD);
+  chmodSync(join(dir, "gcloud"), 0o755);
+  process.env.PATH = `${dir}:${originalPath ?? ""}`;
+});
+
+afterAll(() => {
+  process.env.PATH = originalPath;
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("gcloud runners never block on a hidden prompt", () => {
+  it("gcloud() disables prompts and closes stdin", async () => {
+    const r = await gcloud(["beta", "run", "domain-mappings", "describe"]);
+    expect(r.stdout).toBe("prompts=1\nanswer=\n");
+  });
+
+  it("gcloud() still feeds stdin when the caller passes it", async () => {
+    const r = await gcloud(["secrets", "versions", "add"], { stdin: "payload\n" });
+    expect(r.stdout).toBe("prompts=1\nanswer=payload\n");
+  });
+
+  it("runCli() disables gcloud prompts and closes stdin", async () => {
+    const r = await runCli("gcloud", ["config", "get-value", "run/region"]);
+    expect(r.stdout).toBe("prompts=1\nanswer=\n");
+  });
+
+  it("gcloudEnv() keeps the caller's environment", () => {
+    expect(gcloudEnv({ HOME: "/home/x" })).toEqual({
+      HOME: "/home/x",
+      CLOUDSDK_CORE_DISABLE_PROMPTS: "1",
+    });
+  });
+});

package/src/gcloud.test.ts

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { type GcloudResult, grantProvisionerRoles, PROVISIONER_ROLE_LIST } from "./gcloud.js";
+
+const ok: GcloudResult = { ok: true, stdout: "", stderr: "", exitCode: 0 };
+const fail = (stderr: string): GcloudResult => ({ ok: false, stdout: "", stderr, exitCode: 1 });
+
+const SA_NOT_YET_VISIBLE =
+  "ERROR: (gcloud.projects.add-iam-policy-binding) INVALID_ARGUMENT: Service account caelo-provisioner@p.iam.gserviceaccount.com does not exist.";
+const PERMISSION_DENIED =
+  "ERROR: (gcloud.projects.add-iam-policy-binding) PERMISSION_DENIED: Policy update access denied.";
+
+/** Fake gcloud: answers each call for `role` from its queue, `ok` once the queue is empty. */
+function fakeGcloud(responses: Record<string, GcloudResult[]>) {
+  const calls: string[] = [];
+  const run = async (args: string[]): Promise<GcloudResult> => {
+    const role = args[args.indexOf("--role") + 1] as string;
+    calls.push(role);
+    return responses[role]?.shift() ?? ok;
+  };
+  return { run, calls };
+}
+
+const noSleep = async () => {};
+
+describe("grantProvisionerRoles", () => {
+  it("binds only the given roles when asked (#696 install-job extras)", async () => {
+    const { run, calls } = fakeGcloud({});
+    const roles = ["roles/iam.roleAdmin", "roles/cloudscheduler.admin"];
+    const result = await grantProvisionerRoles("p", "sa@p", { run, sleep: noSleep, roles });
+    expect(result).toEqual({ granted: 2, failed: [] });
+    expect(calls).toEqual(roles);
+  });
+
+  it("retries a freshly created SA that IAM does not see yet (regression: first role failed right after SA create)", async () => {
+    const first = PROVISIONER_ROLE_LIST[0] as string;
+    const { run, calls } = fakeGcloud({
+      [first]: [fail(SA_NOT_YET_VISIBLE), fail(SA_NOT_YET_VISIBLE)],
+    });
+    const slept: number[] = [];
+
+    const result = await grantProvisionerRoles("p", "sa@p", {
+      run,
+      sleep: async (ms) => {
+        slept.push(ms);
+      },
+      retryDelaysMs: [10, 20, 40],
+    });
+
+    expect(result).toEqual({ granted: PROVISIONER_ROLE_LIST.length, failed: [] });
+    expect(calls.filter((r) => r === first)).toHaveLength(3);
+    expect(slept).toEqual([10, 20]);
+  });
+
+  it("retries concurrent policy changes", async () => {
+    const role = PROVISIONER_ROLE_LIST[1] as string;
+    const { run } = fakeGcloud({
+      [role]: [
+        fail(
+          "ERROR: ABORTED: There were concurrent policy changes. Please retry the whole read-modify-write with exponential backoff.",
+        ),
+      ],
+    });
+
+    const result = await grantProvisionerRoles("p", "sa@p", { run, sleep: noSleep });
+
+    expect(result.failed).toEqual([]);
+  });
+
+  it("does not retry a permission error and reports gcloud's message", async () => {
+    const role = PROVISIONER_ROLE_LIST[0] as string;
+    const { run, calls } = fakeGcloud({
+      [role]: [fail(PERMISSION_DENIED), fail(PERMISSION_DENIED)],
+    });
+
+    const result = await grantProvisionerRoles("p", "sa@p", { run, sleep: noSleep });
+
+    expect(calls.filter((r) => r === role)).toHaveLength(1);
+    expect(result.granted).toBe(PROVISIONER_ROLE_LIST.length - 1);
+    expect(result.failed).toEqual([{ role, error: PERMISSION_DENIED }]);
+  });
+
+  it("gives up after the last retry and reports the last error", async () => {
+    const role = PROVISIONER_ROLE_LIST[0] as string;
+    const { run, calls } = fakeGcloud({
+      [role]: Array.from({ length: 10 }, () => fail(SA_NOT_YET_VISIBLE)),
+    });
+
+    const result = await grantProvisionerRoles("p", "sa@p", {
+      run,
+      sleep: noSleep,
+      retryDelaysMs: [1, 1],
+    });
+
+    expect(calls.filter((r) => r === role)).toHaveLength(3);
+    expect(result.failed).toEqual([{ role, error: SA_NOT_YET_VISIBLE }]);
+  });
+});

package/src/gcloud.ts

@@ -0,0 +1,322 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Thin gcloud shell-out wrapper. The wizard composes high-level
+ * "create the project + link billing + enable APIs + create SA +
+ * grant roles" flows on top of these primitives. No key is ever minted
+ * for the provisioner SA: the operator impersonates it
+ * (provisioner-identity.ts, #696).
+ *
+ * Why shell out instead of using the GCP SDK directly:
+ *   - the user's gcloud auth state IS the auth (no separate
+ *     credentials handling — `gcloud` already knows the user)
+ *   - project create + billing link must happen as the user, NOT as
+ *     a service account (the SA doesn't exist yet at bootstrap time)
+ *   - error messages from gcloud are operator-readable; the SDK's
+ *     gRPC errors aren't
+ */
+
+import { spawn } from "node:child_process";
+
+export interface GcloudResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/**
+ * Environment for every non-interactive gcloud child process.
+ *
+ * `CLOUDSDK_CORE_DISABLE_PROMPTS=1` makes gcloud take the non-interactive
+ * path instead of asking a question nobody can see: our runners capture
+ * gcloud's output, so a "(Y/n)" prompt — e.g. "install the beta component?"
+ * — hung the CLI forever (`admin-domain enable`). With prompts disabled,
+ * gcloud fails fast with its error (or proceeds where the command allows it),
+ * and the caller reports the error. Commands that SHOULD talk to the
+ * operator (`gcloud auth login`) are never run through these runners; the
+ * wizard tells the operator to run them in their own terminal.
+ */
+export function gcloudEnv(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  return { ...base, CLOUDSDK_CORE_DISABLE_PROMPTS: "1" };
+}
+
+/**
+ * Run a gcloud command. Buffered stdout + stderr (max 4 MB each).
+ * Throws on spawn failure but NOT on non-zero exit — caller checks `ok`.
+ * stdin is always ended (after `opts.stdin`, if given), so nothing can wait on it.
+ * `opts.env` replaces this process's environment as the base (prompts stay off).
+ */
+export async function gcloud(
+  args: string[],
+  opts: { stdin?: string; env?: NodeJS.ProcessEnv } = {},
+): Promise<GcloudResult> {
+  return new Promise((resolveResult, reject) => {
+    const child = spawn("gcloud", args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: gcloudEnv(opts.env ?? process.env),
+    });
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    child.stdout.on("data", (chunk: Buffer) => stdout.push(chunk));
+    child.stderr.on("data", (chunk: Buffer) => stderr.push(chunk));
+    child.on("error", (e) => reject(e));
+    child.on("close", (code) =>
+      resolveResult({
+        ok: code === 0,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+        exitCode: code ?? 1,
+      }),
+    );
+    child.stdin.end(opts.stdin);
+  });
+}
+
+/**
+ * Active gcloud account. Returns `null` when no account is logged in
+ * — caller prompts `gcloud auth login`.
+ */
+export async function activeAccount(): Promise<string | null> {
+  const r = await gcloud(["auth", "list", "--format=value(account)", "--filter=status:ACTIVE"]);
+  if (!r.ok) return null;
+  const value = r.stdout.trim();
+  return value.length > 0 ? value : null;
+}
+
+export interface BillingAccount {
+  id: string;
+  displayName: string;
+  open: boolean;
+}
+
+export async function listBillingAccounts(): Promise<BillingAccount[]> {
+  const r = await gcloud(["billing", "accounts", "list", "--format=json"]);
+  if (!r.ok) return [];
+  try {
+    const rows = JSON.parse(r.stdout) as Array<{
+      name: string;
+      displayName: string;
+      open: boolean;
+    }>;
+    return rows.map((row) => ({
+      id: row.name.replace(/^billingAccounts\//, ""),
+      displayName: row.displayName,
+      open: row.open,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+export async function projectExists(projectId: string): Promise<boolean> {
+  const r = await gcloud(["projects", "describe", projectId, "--format=value(projectId)"]);
+  return r.ok && r.stdout.trim() === projectId;
+}
+
+export async function createProject(projectId: string, displayName: string): Promise<GcloudResult> {
+  return gcloud(["projects", "create", projectId, "--name", displayName]);
+}
+
+export async function linkBilling(
+  projectId: string,
+  billingAccountId: string,
+): Promise<GcloudResult> {
+  return gcloud(["billing", "projects", "link", projectId, "--billing-account", billingAccountId]);
+}
+
+const REQUIRED_APIS: readonly string[] = [
+  "compute.googleapis.com",
+  "sqladmin.googleapis.com",
+  "run.googleapis.com",
+  "secretmanager.googleapis.com",
+  "servicenetworking.googleapis.com",
+  "dns.googleapis.com",
+  "storage.googleapis.com",
+  "cloudresourcemanager.googleapis.com",
+  "iam.googleapis.com",
+  "cloudbuild.googleapis.com",
+  "artifactregistry.googleapis.com",
+  "bigquery.googleapis.com",
+  "iap.googleapis.com",
+  // Used by gcp.projects.ServiceIdentity to provision the IAP-managed
+  // service account that forwards authenticated requests to Cloud Run.
+  "serviceusage.googleapis.com",
+  // Hourly run of the operator-access sync job (operator-access.ts).
+  "cloudscheduler.googleapis.com",
+  // signJwt as caelo-mcp: how `staging-domain enable` passes the admin's
+  // IAP (staging-admin.ts, #678) — the same path the MCP shim takes.
+  "iamcredentials.googleapis.com",
+  // #696 — the KMS key Pulumi encrypts the stack's secrets with
+  // (ops-backend.ts; also enabled there for installs that predate this).
+  "cloudkms.googleapis.com",
+];
+
+// v0.3.1 — gcp-firebase provider needs the Firebase Management +
+// Firebase Hosting APIs on top of the gcp baseline. Without these
+// the Pulumi `gcp.firebase.HostingSite` resource fails to create.
+const GCP_FIREBASE_EXTRA_APIS: readonly string[] = [
+  "firebase.googleapis.com",
+  "firebasehosting.googleapis.com",
+];
+
+export async function enableApis(
+  projectId: string,
+  provider: "gcp" | "gcp-firebase" = "gcp",
+): Promise<GcloudResult> {
+  const apis =
+    provider === "gcp-firebase" ? [...REQUIRED_APIS, ...GCP_FIREBASE_EXTRA_APIS] : REQUIRED_APIS;
+  return gcloud(["services", "enable", ...apis, "--project", projectId]);
+}
+
+export async function serviceAccountExists(projectId: string, saEmail: string): Promise<boolean> {
+  const r = await gcloud([
+    "iam",
+    "service-accounts",
+    "describe",
+    saEmail,
+    "--project",
+    projectId,
+    "--format=value(email)",
+  ]);
+  return r.ok && r.stdout.trim() === saEmail;
+}
+
+export async function createServiceAccount(
+  projectId: string,
+  accountId: string,
+  displayName: string,
+): Promise<GcloudResult> {
+  return gcloud([
+    "iam",
+    "service-accounts",
+    "create",
+    accountId,
+    "--display-name",
+    displayName,
+    "--project",
+    projectId,
+  ]);
+}
+
+const PROVISIONER_ROLES: readonly string[] = [
+  "roles/run.admin",
+  "roles/cloudsql.admin",
+  "roles/storage.admin",
+  "roles/secretmanager.admin",
+  "roles/iam.serviceAccountUser",
+  "roles/compute.networkAdmin",
+  "roles/dns.admin",
+  "roles/servicenetworking.networksAdmin",
+  "roles/iam.serviceAccountTokenCreator",
+  "roles/cloudbuild.builds.editor",
+  "roles/artifactregistry.admin",
+  "roles/compute.securityAdmin",
+  "roles/iam.serviceAccountAdmin",
+  "roles/bigquery.admin",
+  "roles/iap.admin",
+  // compute.admin includes RegionNetworkEndpointGroups + URL maps +
+  // BackendService variants the LB needs. compute.networkAdmin alone
+  // doesn't cover NEG create.
+  "roles/compute.admin",
+  // logging.configWriter creates ProjectSink (BigQuery edge logs).
+  "roles/logging.configWriter",
+  // serviceusage.serviceUsageAdmin lets us trigger the IAP managed
+  // service identity (gcp.projects.ServiceIdentity).
+  "roles/serviceusage.serviceUsageAdmin",
+  // v0.3.6 — Firebase Hosting + Firebase project administration
+  // for the gcp-firebase provider variant. The stack's
+  // `gcp.firebase.Project` (which adds Firebase services to a GCP
+  // project) + `gcp.firebase.HostingSite` need these roles.
+  // Granting on gcp installs is a harmless no-op since those
+  // resources aren't created on that stack.
+  "roles/firebase.admin",
+  "roles/firebasehosting.admin",
+  // v0.3.7 — project-level IAM binding admin. Required so the
+  // provisioner SA can grant other SAs roles AT THE PROJECT LEVEL
+  // via `gcp.projects.IAMMember`. The gcp-firebase stack uses
+  // this for `roles/firebasehosting.admin` on the run SA so it
+  // can deploy to Firebase Hosting. Without this role the
+  // provisioner gets a 403 "Policy update access denied" when
+  // creating project-level IAM bindings. Secret/bucket/SA-level
+  // bindings already work via the per-resource admin roles above.
+  "roles/resourcemanager.projectIamAdmin",
+];
+
+/**
+ * IAM errors that clear up on their own within seconds:
+ *   - a service account created moments ago is not yet visible to the
+ *     IAM policy backend ("Service account ... does not exist") — this
+ *     hits the FIRST binding right after `createServiceAccount`
+ *   - Google's service agents write the project policy concurrently
+ *     right after `enableApis` ("There were concurrent policy changes")
+ * Anything else (PERMISSION_DENIED, bad role name) fails immediately.
+ */
+const TRANSIENT_IAM_ERROR =
+  /does not exist|concurrent policy changes|ABORTED|UNAVAILABLE|deadline exceeded/i;
+
+const GRANT_RETRY_DELAYS_MS: readonly number[] = [2_000, 4_000, 8_000, 16_000];
+
+interface RoleGrantFailure {
+  role: string;
+  /** Last gcloud stderr for this role, so the operator sees WHY. */
+  error: string;
+}
+
+/**
+ * Bind every role the GCP stack provisioner SA needs. Idempotent —
+ * gcloud silently no-ops a binding that already exists. Transient IAM
+ * errors are retried with backoff; `opts` exists for tests.
+ */
+export async function grantProvisionerRoles(
+  projectId: string,
+  saEmail: string,
+  opts: {
+    run?: typeof gcloud;
+    sleep?: (ms: number) => Promise<void>;
+    retryDelaysMs?: readonly number[];
+    /** Roles to bind instead of the provisioner's base set (the install job's extras). */
+    roles?: readonly string[];
+  } = {},
+): Promise<{ granted: number; failed: RoleGrantFailure[] }> {
+  const run = opts.run ?? gcloud;
+  const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const retryDelaysMs = opts.retryDelaysMs ?? GRANT_RETRY_DELAYS_MS;
+  let granted = 0;
+  const failed: RoleGrantFailure[] = [];
+  for (const role of opts.roles ?? PROVISIONER_ROLES) {
+    const args = [
+      "projects",
+      "add-iam-policy-binding",
+      projectId,
+      "--member",
+      `serviceAccount:${saEmail}`,
+      "--role",
+      role,
+      "--condition=None",
+      "--quiet",
+    ];
+    let r = await run(args);
+    for (const delay of retryDelaysMs) {
+      if (r.ok || !TRANSIENT_IAM_ERROR.test(r.stderr)) break;
+      await sleep(delay);
+      r = await run(args);
+    }
+    if (r.ok) granted++;
+    else failed.push({ role, error: r.stderr.trim() });
+  }
+  return { granted, failed };
+}
+
+export const REQUIRED_API_LIST = REQUIRED_APIS;
+export const GCP_FIREBASE_EXTRA_API_LIST = GCP_FIREBASE_EXTRA_APIS;
+export const PROVISIONER_ROLE_LIST = PROVISIONER_ROLES;
+
+// v0.3.12 — removed createFirebaseHostingIdentity. The Service
+// Usage GenerateServiceIdentity API doesn't support
+// `firebasehosting.googleapis.com`, and `gcloud beta services
+// identity create` would have returned the same error after a
+// 2-min beta-component download. The SA gets auto-created lazily
+// by Firebase Hosting on first deploy. We grant run.invoker at
+// the project level instead of service level so the binding
+// doesn't require the SA to exist at bind time.

package/src/gcp-names.ts

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Deterministic names of the GCP resources the `gcp` and `gcp-firebase`
+ * Pulumi stacks create. The stacks build these names with the helpers below
+ * and `cms-provision upgrade` addresses the same resources through gcloud, so
+ * the two can never disagree about which bucket, secret or service account
+ * they mean.
+ *
+ * Only names that are fixed strings belong here. Pulumi auto-names (the
+ * random suffix on Cloud Run services, backend buckets, ...) are discovered at
+ * upgrade time instead.
+ *
+ * Pure module — the stacks import it from `dist/`, so it must not pull in
+ * the CLI's dependencies.
+ */
+
+/** The Pulumi stack name the wizard provisions and `upgrade` operates on. */
+export const GCP_STACK_ENV = "production";
+
+/** Account id of the service account external MCP clients sign as (issue #37). */
+export const MCP_IAP_SERVICE_ACCOUNT_ID = "caelo-mcp";
+
+/** Email of the MCP service account in `projectId`. */
+export function mcpIapServiceAccountEmail(projectId: string): string {
+  return `${MCP_IAP_SERVICE_ACCOUNT_ID}@${projectId}.iam.gserviceaccount.com`;
+}
+
+/** `caelo-<env>`: prefix of every stack resource name. */
+export function gcpNamePrefix(env: string): string {
+  return `caelo-${env}`;
+}
+
+/** Account id of the runtime service account admin + gateway run as. */
+export function runServiceAccountId(env: string): string {
+  return `${gcpNamePrefix(env)}-run-sa`;
+}
+
+/** Email of the runtime service account admin + gateway run as. */
+export function runServiceAccountEmail(projectId: string, env: string): string {
+  return `${runServiceAccountId(env)}@${projectId}.iam.gserviceaccount.com`;
+}
+
+/**
+ * Account id of the service account the gateway runs as. Separate from the
+ * admin's so the public-facing gateway can read only the secrets it needs
+ * (stack-contract.ts `SERVICE_SECRET_ENV`), never the KEK or the admin-only
+ * secrets.
+ */
+export function gatewayServiceAccountId(env: string): string {
+  return `${gcpNamePrefix(env)}-gateway-sa`;
+}
+
+/** Email of the service account the gateway runs as. */
+export function gatewayServiceAccountEmail(projectId: string, env: string): string {
+  return `${gatewayServiceAccountId(env)}@${projectId}.iam.gserviceaccount.com`;
+}
+
+/**
+ * Account id of the `gcp` stack's static-publisher service account. Account
+ * ids max out at 30 chars, so the env is shortened.
+ */
+export function staticPublisherServiceAccountId(env: string): string {
+  const short = env === "production" ? "prod" : env === "staging" ? "stg" : "dev";
+  return `caelo-${short}-publisher`;
+}
+
+/** Globally unique GCS bucket name the stacks give each bucket. */
+export function gcpBucketName(
+  projectId: string,
+  env: string,
+  bucket: "media" | "static" | "staging",
+): string {
+  return `${projectId}-${gcpNamePrefix(env)}-${bucket}`;
+}
+
+/** Secret Manager secret id for one of the stack's runtime secrets. */
+export function gcpSecretId(env: string, name: string): string {
+  return `${gcpNamePrefix(env)}-${name}`;
+}
+
+/** Cloud Run job that keeps Google IAP operator access in sync (operator-access.ts). */
+export function operatorAccessJobName(env: string): string {
+  return `${gcpNamePrefix(env)}-operator-access-sync`;
+}
+
+/** Full resource name of the operator-access sync job, as the admin's env carries it. */
+export function operatorAccessJobResource(projectId: string, region: string, env: string): string {
+  return `projects/${projectId}/locations/${region}/jobs/${operatorAccessJobName(env)}`;
+}
+
+/**
+ * Account id of the sync job's own service account — the only principal that
+ * may change the admin's IAP binding and the caelo-mcp token-creator binding.
+ */
+export function operatorAccessServiceAccountId(env: string): string {
+  return `${gcpNamePrefix(env)}-opaccess`;
+}
+
+/** Email of the sync job's service account. */
+export function operatorAccessServiceAccountEmail(projectId: string, env: string): string {
+  return `${operatorAccessServiceAccountId(env)}@${projectId}.iam.gserviceaccount.com`;
+}
+
+/** Cloud Scheduler job that runs the sync job hourly (self-healing). */
+export function operatorAccessScheduleName(env: string): string {
+  return `${gcpNamePrefix(env)}-operator-access-hourly`;
+}
+
+/**
+ * Cloud Run job that installs Caelo releases from the admin (epic #696):
+ * the admin may only start it, without overrides (upgrader-setup.ts).
+ */
+export function upgraderJobName(env: string): string {
+  return `${gcpNamePrefix(env)}-upgrader`;
+}
+
+/** Full resource name of the upgrader job, as the admin's env carries it. */
+export function upgraderJobResource(projectId: string, region: string, env: string): string {
+  return `projects/${projectId}/locations/${region}/jobs/${upgraderJobName(env)}`;
+}
+
+/**
+ * Account id of the upgrader job's own service account: may roll the two
+ * Cloud Run services, run the migration job and back up Cloud SQL, never
+ * change IAM, service accounts or secrets (upgrader-setup.ts).
+ */
+export function upgraderServiceAccountId(env: string): string {
+  return `${gcpNamePrefix(env)}-upgrader`;
+}
+
+/** Email of the upgrader job's service account. */
+export function upgraderServiceAccountEmail(projectId: string, env: string): string {
+  return `${upgraderServiceAccountId(env)}@${projectId}.iam.gserviceaccount.com`;
+}