@caelo-cms/provisioning 0.11.0 → 0.11.1

package/src/cdn-copy.ts

@@ -11,13 +11,12 @@
  *           respects the long TTL.
  *   - Azure → Front Door purge + warm endpoint.
  *
- * The redeploy-orchestrator's `cdnCopyTick()` (currently a no-op for
- * cloud installs) drains the per-asset CDN-pin queue using the adapter
- * registered for the active provider.
+ * A worker that drains the per-asset CDN-pin queue (none ships yet) uses
+ * the adapter registered for the active provider.
  *
  * Each provider's stack publishes a `CdnCopyAdapter` instance via its
  * Pulumi outputs (the actual implementation is dynamically imported by
- * the orchestrator at runtime so `@caelo-cms/provisioning` doesn't pull in
+ * that worker at runtime so `@caelo-cms/provisioning` doesn't pull in
  * `@aws-sdk/...`/`@google-cloud/...`/`@azure/...` as static deps). The
  * interface defined here is the only thing both sides agree on.
  */

package/src/cpu-idle.test.ts

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Cloud Run CPU allocation. A missing `cpuIdle` in the v2 API means
+ * always-on CPU once `resources` is set, so both stacks ran the admin and
+ * the gateway billed around the clock. The stacks now set it from
+ * SERVICE_CPU_IDLE, and an upgrade moves existing installs there.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { SERVICE_CPU_IDLE } from "./stack-contract.js";
+import { liveCpuIdle, planCpuIdle } from "./stack-converge.js";
+
+const described = (annotations?: Record<string, string>) =>
+  JSON.stringify({ spec: { template: { metadata: annotations ? { annotations } : {} } } });
+
+describe("liveCpuIdle", () => {
+  it("reads the revision's cpu-throttling annotation", () => {
+    expect(liveCpuIdle(described({ "run.googleapis.com/cpu-throttling": "false" }))).toBe(false);
+    expect(liveCpuIdle(described({ "run.googleapis.com/cpu-throttling": "true" }))).toBe(true);
+  });
+
+  it("treats a missing annotation as Cloud Run's default, request-based CPU", () => {
+    expect(liveCpuIdle(described())).toBe(true);
+    expect(liveCpuIdle(described({ "autoscaling.knative.dev/maxScale": "5" }))).toBe(true);
+  });
+});
+
+describe("planCpuIdle", () => {
+  it("moves an always-on service to request-based CPU", () => {
+    expect(planCpuIdle(false, true)).toEqual({
+      ok: true,
+      flags: ["--cpu-throttling"],
+      changes: ["CPU: always allocated → only during requests"],
+    });
+  });
+
+  it("changes nothing when the service already matches", () => {
+    expect(planCpuIdle(true, true)).toEqual({ ok: true, flags: [], changes: [] });
+    expect(planCpuIdle(false, false)).toEqual({ ok: true, flags: [], changes: [] });
+  });
+
+  it("never switches a service to always-on CPU", () => {
+    expect(planCpuIdle(true, false)).toEqual({ ok: true, flags: [], changes: [] });
+  });
+});
+
+describe("the stacks set cpuIdle", () => {
+  it("the gateway runs request-billed", () => {
+    expect(SERVICE_CPU_IDLE.gateway).toBe(true);
+  });
+
+  for (const provider of ["gcp", "gcp-firebase"]) {
+    it(`${provider} takes cpuIdle from the contract`, () => {
+      const stack = readFileSync(
+        resolve(import.meta.dir, `../stacks/${provider}/index.ts`),
+        "utf8",
+      );
+      expect(stack).toContain("cpuIdle: SERVICE_CPU_IDLE[args.serviceName]");
+    });
+  }
+});

package/src/stack-contract.ts

@@ -620,6 +620,25 @@ export function gatewayEnvContract<V>(inputs: RuntimeEnvInputs<V>): CloudRunEnvV
  */
 export const GATEWAY_TIMEOUT_SECONDS = 3600;
 
+/**
+ * Whether each Cloud Run service gets CPU only while it handles a request
+ * (Cloud Run's request-based billing, `cpuIdle: true`) or for its whole
+ * lifetime (`false`, instance-based billing). Set explicitly: the v2 API
+ * reads a missing `cpuIdle` as `false` as soon as a service declares
+ * `resources`, which is how both services ran with always-on CPU without
+ * anyone choosing it — billed for every idle minute an instance stayed up.
+ *
+ * The gateway only does work inside requests. The admin still runs its
+ * background work (Tier 5: audit worker, importer, plugin cron, GC) on
+ * in-process timers that need CPU between requests.
+ */
+export const SERVICE_CPU_IDLE: Readonly<Record<CloudRunSlug, boolean>> = {
+  // FIXME(issue #1140): true once the admin's background work no longer
+  // depends on CPU between requests (jobs, scheduler, plugin host).
+  admin: false,
+  gateway: true,
+};
+
 /** Admin env var naming the Secret Manager secret the Owner writes the Google sign-in client to. */
 export const OPERATOR_OAUTH_CLIENT_STORE_ENV = "CAELO_OPERATOR_OAUTH_CLIENT_STORE";
 

package/src/stack-converge.ts

@@ -25,6 +25,8 @@
  *   - {@link planSecretFiles} / {@link planRequestTimeout} (#806): the
  *     gateway's secret file (the remote-MCP OAuth client) and its request
  *     timeout, in the same `services update`.
+ *   - {@link planCpuIdle}: request-based CPU where the contract wants it
+ *     (`SERVICE_CPU_IDLE`), in the same `services update`.
  */
 
 import { removeDefaultFirewallRules } from "./default-firewall.js";
@@ -1152,6 +1154,35 @@ export function planRequestTimeout(live: number | null, desired: number): RollAd
   };
 }
 
+/**
+ * Whether a described service gets CPU only during requests. Cloud Run keeps
+ * the setting in the `run.googleapis.com/cpu-throttling` revision
+ * annotation; a missing annotation is Cloud Run's default, throttled.
+ */
+export function liveCpuIdle(serviceJson: string): boolean {
+  const svc = JSON.parse(serviceJson) as {
+    spec?: { template?: { metadata?: { annotations?: Record<string, string> } } };
+  };
+  return (
+    svc.spec?.template?.metadata?.annotations?.["run.googleapis.com/cpu-throttling"] !== "false"
+  );
+}
+
+/**
+ * `--cpu-throttling` when the contract wants request-based CPU and the
+ * service still runs always-on. Never the other way: always-on CPU is
+ * billed around the clock, so a service the operator already moved to
+ * request-based CPU keeps it.
+ */
+export function planCpuIdle(live: boolean, desired: boolean): RollAdditionsPlan {
+  if (!desired || live) return { ok: true, flags: [], changes: [] };
+  return {
+    ok: true,
+    flags: ["--cpu-throttling"],
+    changes: ["CPU: always allocated → only during requests"],
+  };
+}
+
 /**
  * The single `gcloud run services update` that rolls a service to a new
  * image, its run SA and its env changes, so all land in one new revision.

package/src/upgrade/app-roll.ts

@@ -32,6 +32,7 @@ import {
   type CloudRunEnvVar,
   GATEWAY_TIMEOUT_SECONDS,
   RETIRED_SECRET_FILES,
+  SERVICE_CPU_IDLE,
   SERVICE_SECRET_FILES,
 } from "../stack-contract.js";
 import {
@@ -42,10 +43,12 @@ import {
   type LiveVolumes,
   liveContainerEnv,
   liveContainerMemory,
+  liveCpuIdle,
   liveTimeoutSeconds,
   liveVolumes,
   planAdminMemory,
   planContractEnv,
+  planCpuIdle,
   planMediaVolume,
   planRequestTimeout,
   planSecretFiles,
@@ -105,6 +108,8 @@ export interface ServicePlan {
   readonly liveVolumes: LiveVolumes;
   /** Request timeout now, in seconds (null = Cloud Run's default). */
   readonly liveTimeout: number | null;
+  /** Whether the service gets CPU only during requests now. */
+  readonly liveCpuIdle: boolean;
 }
 
 /** A service plan plus the changes its roll applies. */
@@ -113,7 +118,8 @@ export interface RollPlan extends ServicePlan {
   readonly envChanges: readonly EnvChange[];
   /**
    * #553 — e.g. `--memory=2Gi` when the admin runs below the stack default;
-   * #806 — `--timeout=3600` when the gateway runs below its contract timeout.
+   * #806 — `--timeout=3600` when the gateway runs below its contract timeout;
+   * `--cpu-throttling` when the contract wants request-based CPU.
    */
   readonly resourceFlags: readonly string[];
   readonly resourceChanges: readonly string[];
@@ -203,6 +209,7 @@ export async function planAppRoll(
       liveMemory: liveContainerMemory(json),
       liveVolumes: liveVolumes(json),
       liveTimeout: liveTimeoutSeconds(json),
+      liveCpuIdle: liveCpuIdle(json),
     });
   }
   const env = planEnv(install, services, {});
@@ -264,14 +271,17 @@ export async function planAppRoll(
       s.slug === "gateway" ? planRequestTimeout(s.liveTimeout, GATEWAY_TIMEOUT_SECONDS) : null;
     const memoryFlags = memory?.ok ? memory.flags : [];
     const timeoutFlags = timeout?.ok ? timeout.flags : [];
+    const cpu = planCpuIdle(s.liveCpuIdle, SERVICE_CPU_IDLE[s.slug]);
+    const cpuFlags = cpu.ok ? cpu.flags : [];
     return {
       ...s,
       envFlags: env.services[s.slug].flags,
       envChanges: env.services[s.slug].changes,
-      resourceFlags: [...memoryFlags, ...timeoutFlags],
+      resourceFlags: [...memoryFlags, ...timeoutFlags, ...cpuFlags],
       resourceChanges: [
         ...memoryFlags.map((f) => `${s.liveMemory ?? "(default)"} → ${f}`),
         ...(timeout?.ok ? timeout.changes : []),
+        ...(cpu.ok ? cpu.changes : []),
       ],
       volumeFlags: [...(s.slug === "admin" ? media.flags : []), ...secretFiles[s.slug].flags],
       volumeChanges: [...(s.slug === "admin" ? media.changes : []), ...secretFiles[s.slug].changes],

package/src/upgrade/upgrade.test.ts

@@ -50,7 +50,8 @@ const secretRef = (name: string, secret: string) => ({
 
 /**
  * A described service, as `gcloud run services describe --format=json`
- * returns it. `ingress`: the service-level setting (#732).
+ * returns it. `ingress`: the service-level setting (#732). Always-on CPU,
+ * as every install the stacks created before `cpuIdle` was set runs.
  */
 const serviceJson = (image: string, env: unknown[], ingress = "all") =>
   JSON.stringify({
@@ -59,6 +60,7 @@ const serviceJson = (image: string, env: unknown[], ingress = "all") =>
       template: {
         metadata: {
           annotations: {
+            "run.googleapis.com/cpu-throttling": "false",
             "run.googleapis.com/network-interfaces": JSON.stringify([
               { network: "caelo-production-vpc", subnetwork: "caelo-production-subnet" },
             ]),
@@ -698,6 +700,20 @@ describe("upgradeGcpInstall — converge, then app-roll", () => {
     expect(calls.filter((c) => /^run services update /.test(c))).toHaveLength(2);
   });
 
+  it("moves the gateway to request-based CPU in its image roll; the admin keeps its CPU", async () => {
+    const events: string[] = [];
+    const { deps, calls } = upgradeDeps(events);
+    expect(await upgradeGcpInstall(TARGET, deps)).toBe(true);
+    const rolls = calls.filter((c) =>
+      /^run services update \S+ --region europe-west1 .*--image/.test(c),
+    );
+    const admin = rolls.find((c) => c.startsWith(`run services update ${ADMIN} `)) ?? "";
+    const gateway = rolls.find((c) => c.startsWith(`run services update ${GATEWAY} `)) ?? "";
+    expect(gateway).toContain("--cpu-throttling");
+    expect(admin).not.toContain("cpu-throttling");
+    expect(calls.filter((c) => /^run services update /.test(c))).toHaveLength(2);
+  });
+
   it("#806 — on gcp, routes the discovery paths and adds the Cloud Armor rule before the roll", async () => {
     const events: string[] = [];
     const urlMap = {

package/src/wizards/gcp-cost.ts

@@ -91,13 +91,16 @@ export function estimateGcpCost(inputs: CostEstimateInputs): {
     },
     {
       name: `Cloud Run admin (${adminMemory})`,
+      // FIXME(issue #1140): ~$1 once the admin runs request-billed CPU
+      // (SERVICE_CPU_IDLE). Until then each editing session is billed for
+      // as long as the instance stays up, ~15 minutes past its last request.
       monthlyUsd:
         inputs.adminMinInstances === 0
-          ? 1
+          ? 7
           : Math.round(1 + inputs.adminMinInstances * perMinInstanceUsd),
       notes:
         inputs.adminMinInstances === 0
-          ? "scale-to-zero; ~$1/mo light editorial use"
+          ? "scale-to-zero, CPU always allocated while running; ~$7/mo light editorial use"
           : `${inputs.adminMinInstances} min-instance${inputs.adminMinInstances > 1 ? "s" : ""} (no cold start)`,
     },
     {

package/stacks/gcp/index.ts

@@ -48,6 +48,7 @@ import {
   type RuntimeSecret,
   remoteMcpIdentityStackEnv,
   runtimeSecretBindings,
+  SERVICE_CPU_IDLE,
   STATIC_CDN_POLICY,
   secretFileVolumesTemplate,
 } from "../../dist/stack-contract.js";
@@ -738,7 +739,11 @@ function cloudRunService(args: CloudRunArgs): gcp.cloudrunv2.Service {
               ...(args.mediaVolume?.volumeMounts ?? []),
               ...secretFileVolumesTemplate(args.serviceName, env).volumeMounts,
             ],
-            resources: { limits: { cpu: "1", memory: args.memory } },
+            // Explicit: a missing cpuIdle means always-on CPU (stack-contract.ts).
+            resources: {
+              limits: { cpu: "1", memory: args.memory },
+              cpuIdle: SERVICE_CPU_IDLE[args.serviceName],
+            },
           },
         ],
         vpcAccess: {

package/stacks/gcp-firebase/index.ts

@@ -53,6 +53,7 @@ import {
   type RuntimeSecret,
   remoteMcpIdentityStackEnv,
   runtimeSecretBindings,
+  SERVICE_CPU_IDLE,
   secretFileVolumesTemplate,
 } from "../../dist/stack-contract.js";
 
@@ -598,7 +599,11 @@ function cloudRunService(args: CloudRunArgs): gcp.cloudrunv2.Service {
               ...(args.mediaVolume?.volumeMounts ?? []),
               ...secretFileVolumesTemplate(args.serviceName, env).volumeMounts,
             ],
-            resources: { limits: { cpu: "1", memory: args.memory } },
+            // Explicit: a missing cpuIdle means always-on CPU (stack-contract.ts).
+            resources: {
+              limits: { cpu: "1", memory: args.memory },
+              cpuIdle: SERVICE_CPU_IDLE[args.serviceName],
+            },
           },
         ],
         vpcAccess: {