@caelo-cms/provisioning 0.10.55 → 0.10.58

package/dist/converge-job-setup.js

@@ -0,0 +1,228 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Set up (and converge) the converge job on a Google Cloud install (`gcp`,
+ * `gcp-firebase`), #819. Run by the wizard (laptop, Cloud Shell or the
+ * install job) after migrations and by every converge — `cms-provision
+ * upgrade` and the converge job itself — so the job always runs the ops
+ * image of the release the install last converged to.
+ *
+ * What it is. A release that raises the infrastructure contract
+ * (infra-contract.ts) needs rights the upgrader job deliberately lacks:
+ * IAM bindings, service accounts, secrets. Until #819 that meant the Owner
+ * ran the upgrade from a terminal with their own Google account. The
+ * converge job runs the very same upgrade (upgrade/upgrade.ts: backup,
+ * converge, roll, health check, rollback, records) from inside the
+ * install's project, as the install's existing `caelo-provisioner` service
+ * account — the account the install job already runs `pulumi up` as and
+ * that already holds every right a converge needs (gcloud.ts
+ * PROVISIONER_ROLES). No new privileged identity is created.
+ *
+ * Trust boundary — the same shape as the upgrader job (upgrader-setup.ts)
+ * and the operator-access job. The admin's runtime service account gets
+ * exactly two roles, both on this one job:
+ *
+ *   - `roles/run.jobsExecutor`: `run.jobs.run` WITHOUT
+ *     `run.jobs.runWithOverrides` — it may start the job, never change its
+ *     image, command, args or env (cloud.google.com/run/docs/reference/iam/roles);
+ *   - `roles/run.viewer`: read its executions (the page's "Continue" for a
+ *     run that died, and the dead-run check).
+ *
+ * The job takes no input but the database: its only input is the request
+ * row's target version. It fetches that release's manifest from the FIXED
+ * registry, verifies its signature with cosign, refuses a downgrade or a
+ * release below `minFromVersion`, and then runs only that release's signed
+ * ops image, pinned by the digest the manifest names (converge-job.ts). So a
+ * compromised admin can at most make the install converge to a newer
+ * signed Caelo release — what the Owner's click does anyway.
+ *
+ * What the provisioner gets here, on top of what it holds since install:
+ *
+ *   - {@link INSTALL_JOB_ROLES} (the operator-access step of a converge
+ *     creates a custom role and a Cloud Scheduler job, and the job's lines
+ *     must reach Cloud Logging) — what an install-job install already
+ *     grants; not an escalation, the provisioner holds projectIamAdmin;
+ *   - a Cloud SQL IAM database login that is a member of `platform_updater`
+ *     only (migration 0267): it reads its request and writes the timeline,
+ *     nothing else in the database.
+ */
+import { ensureCloudSqlIamUser } from "./cloudsql-iam-user.js";
+import { gcloud as defaultGcloud } from "./gcloud.js";
+import { realSleep, runWithRetry } from "./gcloud-retry.js";
+import { convergeJobName, runServiceAccountEmail } from "./gcp-names.js";
+import { INSTALL_JOB_ROLES } from "./install-job.js";
+import { provisionerServiceAccountEmail } from "./provisioner-identity.js";
+import { opsBucketName } from "./state-backend.js";
+import { UPGRADER_DB_ROLE } from "./upgrader-setup.js";
+/**
+ * The job's task timeout in minutes, and the lease on the state lock it
+ * holds (state-lock-lease.ts): after it, Cloud Run has killed the run and a
+ * new execution resumes from the checkpoint. A converge plus a roll takes
+ * 10–20 minutes; the live 0.10.51 run needed 7 before its roll.
+ */
+export const CONVERGE_TASK_TIMEOUT_MINUTES = 60;
+/**
+ * Exactly what the admin's runtime service account may do on the converge
+ * job — start it (no overrides) and read its runs. The setup grants these
+ * two and nothing else; the tests assert it.
+ */
+export const CONVERGE_ADMIN_ROLES = ["roles/run.jobsExecutor", "roles/run.viewer"];
+/**
+ * The job's entry point and its one argument. `caelo-converge-job`
+ * (packages/provisioning/ops/caelo-converge-job, installed by
+ * Dockerfile.ops) refuses every other argument and starts the job with a
+ * scrubbed environment, so even an execution override could not turn the
+ * provisioner's job into `destroy` or point gcloud/Pulumi elsewhere
+ * (#883 review). Nobody holds run.jobs.runWithOverrides on it anyway.
+ */
+export const CONVERGE_JOB_ENTRYPOINT = "caelo-converge-job";
+export const CONVERGE_JOB_COMMAND = "converge-job";
+/** Resources: the converge runs gcloud + Pulumi's Node language host for the stack pin. */
+const JOB_CPU = "2";
+const JOB_MEMORY = "4Gi";
+/**
+ * The `gcloud run jobs deploy` argv of the converge job: the ops image by
+ * digest, the provisioner as its identity, no env and no secrets, the one
+ * fixed subcommand. Exported for the tests that pin the boundary.
+ */
+export function convergeJobDeployArgs(target) {
+    return [
+        "run",
+        "jobs",
+        "deploy",
+        convergeJobName(target.env),
+        `--image=${target.opsImageRef}`,
+        `--region=${target.region}`,
+        `--project=${target.projectId}`,
+        `--service-account=${provisionerServiceAccountEmail(target.projectId)}`,
+        `--network=${target.network}`,
+        `--subnet=${target.subnet}`,
+        "--vpc-egress=private-ranges-only",
+        `--command=${CONVERGE_JOB_ENTRYPOINT}`,
+        `--args=${CONVERGE_JOB_COMMAND}`,
+        // No env and no secrets on the job, whatever an earlier deploy set.
+        "--clear-env-vars",
+        "--clear-secrets",
+        "--tasks=1",
+        // A retry would start a second converge inside the same execution; a
+        // killed run is resumed by starting the job again (checkpointed).
+        "--max-retries=0",
+        `--task-timeout=${CONVERGE_TASK_TIMEOUT_MINUTES}m`,
+        `--cpu=${JOB_CPU}`,
+        `--memory=${JOB_MEMORY}`,
+        "--labels=caelo-role=converge",
+        "--quiet",
+    ];
+}
+/** Ensure the converge job and everything it needs. Never throws for a gcloud failure. */
+export async function ensureConvergeJob(target, deps = {}) {
+    const run = deps.run ?? defaultGcloud;
+    const sleep = deps.sleep ?? realSleep;
+    const retry = (args) => runWithRetry(run, sleep, args);
+    const { projectId, region, env } = target;
+    const project = `--project=${projectId}`;
+    const provisioner = provisionerServiceAccountEmail(projectId);
+    const member = `serviceAccount:${provisioner}`;
+    const adminMember = `serviceAccount:${runServiceAccountEmail(projectId, env)}`;
+    const job = convergeJobName(env);
+    const bucket = opsBucketName(projectId);
+    const done = [];
+    const fail = (step, r) => ({
+        ok: false,
+        done,
+        error: `${step}: ${r.stderr.trim()}`,
+    });
+    if (!/@sha256:[0-9a-f]{64}$/.test(target.opsImageRef)) {
+        return {
+            ok: false,
+            done,
+            error: `the converge job's image must be pinned by digest, got ${target.opsImageRef}`,
+        };
+    }
+    // The job attaches the install from its ops bucket and keeps its
+    // checkpoints there; an install whose state is on a laptop has neither.
+    const bucketCheck = await run([
+        "storage",
+        "buckets",
+        "describe",
+        `gs://${bucket}`,
+        project,
+        "--format=value(name)",
+    ]);
+    if (!bucketCheck.ok) {
+        return {
+            ok: false,
+            done,
+            error: `the ops bucket gs://${bucket} is not there (${bucketCheck.stderr.trim()}). Move the install's state into its own project first: cms-provision state migrate`,
+        };
+    }
+    // The job's identity is the install's provisioner — never created here:
+    // an install without one (installed before it existed) keeps converging
+    // from a terminal.
+    const describe = await run([
+        "iam",
+        "service-accounts",
+        "describe",
+        provisioner,
+        project,
+        "--format=value(email)",
+    ]);
+    if (!describe.ok) {
+        return {
+            ok: false,
+            done,
+            reason: "no-provisioner",
+            error: `this install has no ${provisioner} service account (${describe.stderr.trim()}), which the converge job runs as. Updates that change the cloud setup keep running from a terminal (Settings → Updates shows the command).`,
+        };
+    }
+    // 1. What a converge run as the provisioner needs beyond the install roles.
+    for (const role of INSTALL_JOB_ROLES) {
+        const r = await retry([
+            "projects",
+            "add-iam-policy-binding",
+            projectId,
+            `--member=${member}`,
+            `--role=${role}`,
+            "--condition=None",
+            "--quiet",
+            "--format=none",
+        ]);
+        if (!r.ok)
+            return fail(`grant the provisioner ${role}`, r);
+        done.push(`provisioner: ${role} on the project`);
+    }
+    // 2. Its database login: the request row and the timeline, nothing else.
+    const sqlUser = await ensureCloudSqlIamUser(run, {
+        projectId,
+        env,
+        serviceAccountEmail: provisioner,
+        databaseRole: UPGRADER_DB_ROLE,
+    });
+    done.push(...sqlUser.done);
+    if (!sqlUser.ok)
+        return { ok: false, done, error: sqlUser.error };
+    // 3. The job itself.
+    const deploy = await run(convergeJobDeployArgs(target));
+    if (!deploy.ok)
+        return fail(`deploy job ${job}`, deploy);
+    done.push(`job ${job} (${target.opsImageRef.split("@")[1]?.slice(0, 19)}...)`);
+    // 4. The admin may start it (no overrides) and read its runs — nothing else.
+    for (const role of CONVERGE_ADMIN_ROLES) {
+        const r = await retry([
+            "run",
+            "jobs",
+            "add-iam-policy-binding",
+            job,
+            `--region=${region}`,
+            project,
+            `--member=${adminMember}`,
+            `--role=${role}`,
+            "--quiet",
+            "--format=none",
+        ]);
+        if (!r.ok)
+            return fail(`grant the admin ${role} on ${job}`, r);
+        done.push(`admin: ${role} on ${job}`);
+    }
+    return { ok: true, done };
+}
+//# sourceMappingURL=converge-job-setup.js.map

package/dist/converge-job-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"converge-job-setup.js","sourceRoot":"","sources":["../src/converge-job-setup.ts"],"names":[],"mappings":"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"}

package/dist/converge-job.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The converge job (#819): installs a signed Caelo release that changes the
+ * install's cloud setup (raises the infrastructure contract), from inside
+ * the install's own project, started by the Owner's Update + password in
+ * Settings → Updates. It runs as the install's `caelo-provisioner` account
+ * (converge-job-setup.ts has the trust boundary); the upgrader job, which
+ * only rolls images, keeps every other release.
+ *
+ * One job, two stages, told apart by the release this code belongs to:
+ *
+ *   Stage 1 — the job still runs the ops image of the INSTALLED release.
+ *     It claims the request, reads install.json from the ops bucket,
+ *     fetches the target's release manifest from the FIXED registry and
+ *     verifies its signature (release-manifest.ts), and decides
+ *     (upgrader-assess.ts, `route: "converge"`): no downgrade, nothing
+ *     below minFromVersion, no automatic converge. Then it verifies the
+ *     target's ops image, points this job at it BY DIGEST and starts a new
+ *     execution, handing the request over to it. It changes nothing else:
+ *     the converge logic always comes from the release it installs.
+ *
+ *   Stage 2 — the job runs the TARGET release's ops image (its own
+ *     version is the request's). It verifies the manifest again, checks
+ *     that the image it runs is the one the manifest signs, takes the
+ *     install's state lock (#815; the upgrader job and the terminal
+ *     `upgrade` take the same one, so they exclude each other), and runs
+ *     the very upgrade the terminal runs (upgrade/upgrade.ts): backup →
+ *     converge + app-roll → deep health check, rollback on failure →
+ *     install.json + the infrastructure contract → the request's end.
+ *
+ * Resume. Every stage-2 fact a successor must not recompute (the backup,
+ * the revisions that served before, the release it judges from) is in the
+ * checkpoint (converge-checkpoint.ts). A killed execution leaves its
+ * request `running`; starting the job again (the page's "Continue", or
+ * any new request for the same release) adopts it once Cloud Run says the
+ * old execution has ended, and resumes from the checkpoint.
+ *
+ * Inputs. The job takes no argument and no env: the request row (a
+ * version), install.json in the ops bucket (which the admin cannot write)
+ * and the signed manifest decide everything. All side effects come in
+ * through {@link ConvergeJobDeps}, so the run is tested against fakes;
+ * converge-job-gcp.ts wires the real ones and `@caelo-cms/platform-updater`
+ * the database (`caelo-ops converge-job`).
+ */
+import type { ConvergeCheckpoint } from "./converge-checkpoint.js";
+import { type ExecutionState } from "./install-job.js";
+import type { InstallMetadata } from "./install-state.js";
+import { type ReleaseManifest, type ReleaseManifestResult } from "./release-manifest.js";
+import type { UpgradeCheckpoint } from "./upgrade/upgrade.js";
+import { type ClaimedUpdate, type UpdateQueue, type UpgraderRunResult } from "./upgrader-job.js";
+import { type EventReporter, type JobLog } from "./upgrader-reporter.js";
+/** What the converge claim found. */
+export interface ConvergeClaim {
+    readonly request: ClaimedUpdate;
+    /**
+     * The request was already running: stage 1 handed it to this run, or a
+     * run that died left it. Fresh claims (pending → running) are false.
+     */
+    readonly resume: boolean;
+    /** The execution the request names now (after a fresh claim: this one). */
+    readonly execution: string | null;
+}
+/** The converge job's view of the database (the platform_updater role). */
+export interface ConvergeQueue extends Omit<UpdateQueue, "claim"> {
+    /**
+     * End runs that died long ago (stale), then return the running converge
+     * request, or claim the oldest pending one.
+     */
+    claimConverge(execution: string | null): Promise<ConvergeClaim | null>;
+    /**
+     * Point running request `requestId` at execution `to` — or at none
+     * (`null`: released for the next run to adopt) — only while it still
+     * names `from`. Resolves false when another run got there first.
+     */
+    handover(requestId: string, from: string | null, to: string | null): Promise<boolean>;
+}
+/** How stage 2's upgrade ended (upgrade/upgrade.ts, seen from the job). */
+export type ConvergeUpgradeOutcome = {
+    readonly ok: true;
+    /** Every converge step succeeded and the new contract is recorded. */
+    readonly converged: boolean;
+} | {
+    readonly ok: false;
+    /** Traffic went back to the revisions that served before. */
+    readonly rolledBack: boolean;
+    /** The new release serves but install.json could not record it (#860). */
+    readonly unrecorded: boolean;
+};
+export interface ConvergeJobDeps {
+    readonly queue: ConvergeQueue;
+    /** From the metadata server — never from env or argv. */
+    readonly projectId: string;
+    /** This Cloud Run execution; null outside Cloud Run. */
+    readonly execution: string | null;
+    /** The Caelo release this code belongs to (CAELO_VERSION of the image). */
+    readonly ownVersion: string;
+    /** fetchVerifiedReleaseManifest against the fixed registry. */
+    readonly fetchManifest: (version: string) => Promise<ReleaseManifestResult>;
+    /** install.json as the ops bucket holds it NOW (null when absent) — never cached. */
+    readonly readInstall: () => InstallMetadata | null;
+    /** Verify the cosign signature of the release image `slug@digest`. */
+    readonly verifyImage: (slug: "ops", digest: string) => Promise<boolean>;
+    /** The digest of the image this execution runs (from Cloud Run); null when unreadable. */
+    readonly ownImageDigest: () => Promise<string | null>;
+    /** Point this job at the ops image with `digest` (its identity, command and args stay). */
+    readonly pointJobAt: (digest: string) => Promise<{
+        readonly ok: true;
+    } | {
+        readonly ok: false;
+        readonly error: string;
+    }>;
+    /** Start a new execution of this job; returns its name. */
+    readonly startJob: () => Promise<{
+        readonly ok: true;
+        readonly execution: string;
+    } | {
+        readonly ok: false;
+        readonly error: string;
+    }>;
+    /** Where an execution of this job stands (Cloud Run). */
+    readonly executionState: (execution: string) => Promise<ExecutionState>;
+    /**
+     * Take the install's state lock (#815); returns its release. Throws
+     * StateLockHeldError when a live run holds it, any other error when it
+     * cannot be taken or judged.
+     */
+    readonly lockState: (onBreak: (message: string) => void) => () => void;
+    readonly readCheckpoint: () => ConvergeCheckpoint | null;
+    readonly writeCheckpoint: (checkpoint: ConvergeCheckpoint) => void;
+    /** Stage 2: the terminal's upgrade (upgrade/upgrade.ts) to `manifest`, as this account. */
+    readonly upgrade: (input: {
+        readonly manifest: ReleaseManifest;
+        readonly reporter: EventReporter;
+        readonly resume: UpgradeCheckpoint | undefined;
+        readonly onCheckpoint: (checkpoint: UpgradeCheckpoint) => void;
+    }) => Promise<ConvergeUpgradeOutcome>;
+    readonly now: () => Date;
+    readonly log: JobLog;
+}
+/** Run the converge job once. Never throws; see the file comment. */
+export declare function runConvergeJob(deps: ConvergeJobDeps): Promise<UpgraderRunResult>;
+//# sourceMappingURL=converge-job.d.ts.map

package/dist/converge-job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"converge-job.d.ts","sourceRoot":"","sources":["../src/converge-job.ts"],"names":[],"mappings":"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"}