@intentius/chant-lexicon-gcp 0.124.38 → 0.124.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gcp",
-  "version": "0.124.38",
+  "version": "0.124.39",
   "description": "Google Cloud lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -76,6 +76,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.38"
+    "@intentius/chant": "^0.124.39"
   }
 }

package/src/api/read-client.ts

@@ -98,6 +98,28 @@ export function mapperForKind(kind: string): ResourceMapper | undefined {
  * build a URL — the same input the applier hands it. Returns the parsed body,
  * or throws {@link GcpReadError} carrying the status.
  */
+/**
+ * The URL a read of this resource GETs: the applier's own `plan().getUrl`, so
+ * a health read's sub-calls (`getHealth`) land on the same resource path.
+ * Throws a {@link GcpReadError} when the declared spec can't produce one,
+ * which is a hole, never an absence.
+ */
+export function readUrl(client: GcpReadClientOptions, kind: string, name: string, declared?: Record<string, unknown>): string {
+  const mapper = mapperForKind(kind);
+  if (!mapper) throw new GcpReadError(`no REST mapper for kind ${kind}`);
+  const base = (client.endpoint ?? mapper.defaultHost).replace(/\/$/, "");
+  const resource: GcpResource = {
+    kind,
+    metadata: { name },
+    spec: (declared?.spec as Record<string, unknown> | undefined) ?? declared ?? {},
+  };
+  try {
+    return mapper.plan(resource, { base, project: client.project, ...(client.manifest ? { manifest: client.manifest } : {}) }).getUrl;
+  } catch (err) {
+    throw new GcpReadError(`could not build a read URL for ${kind}/${name}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 export async function getResource(
   client: GcpReadClientOptions,
   kind: string,
@@ -128,14 +150,7 @@ export async function getResource(
       throw new GcpReadError(`could not read ${kind}/${name}: ${err instanceof Error ? err.message : String(err)}`);
     }
   } else {
-    let getUrl: string;
-    try {
-      getUrl = mapper.plan(resource, ctx).getUrl;
-    } catch (err) {
-      // A mapper that cannot plan from the declared spec cannot produce a URL, so
-      // there is nothing to read — a hole, never an absence.
-      throw new GcpReadError(`could not build a read URL for ${kind}/${name}: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const getUrl = readUrl(client, kind, name, declared);
     try {
       res = await http("GET", getUrl);
     } catch (err) {

package/src/composites/catalog.ts

@@ -175,6 +175,12 @@ export const compositeCatalog: CompositeEntry[] = [
         "required": false,
         "description": "Environment variables."
       },
+      {
+        "name": "serviceAccount",
+        "type": "string",
+        "required": false,
+        "description": "Service account the service runs as: an email, or the account id of an IAMServiceAccount in the project."
+      },
       {
         "name": "labels",
         "type": "Record<string, string>",
@@ -955,6 +961,59 @@ export const compositeCatalog: CompositeEntry[] = [
       }
     ]
   },
+  {
+    "name": "PrivateEgressNetwork",
+    "lexicon": "gcp",
+    "description": "Create a PrivateEgressNetwork composite.",
+    "bundles": [
+      "Subnetwork",
+      "VPCNetwork"
+    ],
+    "params": [
+      {
+        "name": "name",
+        "type": "string",
+        "required": true,
+        "description": "Name prefix: the network is `<name>-vpc`, its subnet `<name>-apps`."
+      },
+      {
+        "name": "region",
+        "type": "string",
+        "required": true,
+        "description": "GCP region of the subnet."
+      },
+      {
+        "name": "subnetCidr",
+        "type": "string",
+        "required": true,
+        "description": "IP CIDR range of the subnet."
+      },
+      {
+        "name": "privateIpGoogleAccess",
+        "type": "boolean",
+        "required": false,
+        "description": "Enable private Google access on the subnet (default: true)."
+      },
+      {
+        "name": "labels",
+        "type": "Record<string, string>",
+        "required": false,
+        "description": "Additional labels."
+      },
+      {
+        "name": "namespace",
+        "type": "string",
+        "required": false,
+        "description": "Namespace for all resources."
+      },
+      {
+        "name": "defaults",
+        "type": "{ vpc?: Partial<ConstructorParameters<typeof VPCNetwork>[0]>; subnet?: Partial<ConstructorParameters<typeof Subnetwor...",
+        "required": false,
+        "description": "Per-member defaults for customizing individual resources."
+      }
+    ]
+  },
   {
     "name": "PrivateService",
     "lexicon": "gcp",
@@ -1033,6 +1092,134 @@ export const compositeCatalog: CompositeEntry[] = [
       }
     ]
   },
+  {
+    "name": "PublicCloudRun",
+    "lexicon": "gcp",
+    "description": "Create a PublicCloudRun composite.",
+    "bundles": [
+      "BackendService",
+      "CloudRunService",
+      "ComputeAddress",
+      "ForwardingRule",
+      "GCPServiceAccount",
+      "IAMPolicyMember",
+      "ManagedSSLCertificate",
+      "RegionNetworkEndpointGroup",
+      "TargetHTTPProxy",
+      "TargetHTTPSProxy",
+      "URLMap"
+    ],
+    "params": [
+      {
+        "name": "name",
+        "type": "string",
+        "required": true,
+        "description": "Name prefix every resource is named with."
+      },
+      {
+        "name": "image",
+        "type": "string",
+        "required": true,
+        "description": "Container image."
+      },
+      {
+        "name": "region",
+        "type": "string",
+        "required": true,
+        "description": "GCP region of the service and its network endpoint group."
+      },
+      {
+        "name": "projectId",
+        "type": "string",
+        "required": false,
+        "description": "GCP project, as `projectRef.external` (default: GCP.ProjectId, resolved from GCP_PROJECT_ID at build)."
+      },
+      {
+        "name": "vpc",
+        "type": "{ name: string }",
+        "required": true,
+        "description": "VPC the service's egress goes into, such as a PrivateEgressNetwork's `vpc`."
+      },
+      {
+        "name": "subnet",
+        "type": "{ name: string }",
+        "required": true,
+        "description": "Subnet the service's egress goes into, such as a PrivateEgressNetwork's `subnet`."
+      },
+      {
+        "name": "vpcEgress",
+        "type": "string",
+        "required": false,
+        "description": "Egress sent through the VPC: \"PRIVATE_RANGES_ONLY\" or \"ALL_TRAFFIC\" (default: \"PRIVATE_RANGES_ONLY\")."
+      },
+      {
+        "name": "port",
+        "type": "number",
+        "required": false,
+        "description": "Port the container listens on (default: 8080)."
+      },
+      {
+        "name": "frontendPort",
+        "type": "number",
+        "required": false,
+        "description": "Port the HTTP forwarding rule listens on (default: 80)."
+      },
+      {
+        "name": "minInstanceCount",
+        "type": "number",
+        "required": false,
+        "description": "Minimum instances (default: 0)."
+      },
+      {
+        "name": "maxInstanceCount",
+        "type": "number",
+        "required": false,
+        "description": "Maximum instances (default: 100)."
+      },
+      {
+        "name": "env",
+        "type": "Array<{ name: string; value: string }>",
+        "required": false,
+        "description": "Environment variables."
+      },
+      {
+        "name": "serviceAccount",
+        "type": "string",
+        "required": false,
+        "description": "An existing service account to run as: an email, or the account id of an IAMServiceAccount in the project."
+      },
+      {
+        "name": "domains",
+        "type": "string[]",
+        "required": false,
+        "description": "Domains for a Google-managed certificate."
+      },
+      {
+        "name": "securityPolicy",
+        "type": "string",
+        "required": false,
+        "description": "Name of a ComputeSecurityPolicy (Cloud Armor) attached to the backend service."
+      },
+      {
+        "name": "labels",
+        "type": "Record<string, string>",
+        "required": false,
+        "description": "Additional labels."
+      },
+      {
+        "name": "namespace",
+        "type": "string",
+        "required": false,
+        "description": "Namespace for all resources."
+      },
+      {
+        "name": "defaults",
+        "type": "{ runtime?: Partial<ConstructorParameters<typeof GCPServiceAccount>[0]>; service?: Record<string, unknown>; publicAcc...",
+        "required": false,
+        "description": "Per-member defaults for customizing individual resources."
+      }
+    ]
+  },
   {
     "name": "PubSubPipeline",
     "lexicon": "gcp",

package/src/composites/cloud-run-lb.test.ts

@@ -0,0 +1,93 @@
+import { describe, test, expect } from "vitest";
+import { PrivateEgressNetwork } from "./private-egress-network";
+import { PublicCloudRun } from "./public-cloud-run";
+
+/** Helper to extract props from a Declarable member. */
+function p(member: unknown): Record<string, any> {
+  return (member as any).props;
+}
+
+/** The metadata.name a `{ name }` reference resolves to: a literal, or another member's name attribute. */
+function refName(ref: { name: unknown }): unknown {
+  const value = ref.name as any;
+  return value?.parent?.deref ? p(value.parent.deref()).metadata.name : value;
+}
+
+const net = { vpc: { name: "web-vpc" }, subnet: { name: "web-apps" } };
+const base = { name: "web", projectId: "proj", region: "us-central1", image: "img:1", ...net };
+
+describe("PrivateEgressNetwork (#4263)", () => {
+  test("a custom-mode VPC and one subnet in the region", () => {
+    const { vpc, subnet } = PrivateEgressNetwork({ name: "web", region: "us-central1", subnetCidr: "10.10.0.0/24" });
+    expect(p(vpc).metadata.name).toBe("web-vpc");
+    expect(p(vpc).autoCreateSubnetworks).toBe(false);
+    expect(p(vpc).routingMode).toBe("REGIONAL");
+    expect(p(subnet).metadata.name).toBe("web-apps");
+    expect(p(subnet).region).toBe("us-central1");
+    expect(p(subnet).ipCidrRange).toBe("10.10.0.0/24");
+    expect(p(subnet).privateIpGoogleAccess).toBe(true);
+  });
+});
+
+describe("PublicCloudRun (#4263)", () => {
+  test("creates its own service account and runs the service as it", () => {
+    const r = PublicCloudRun(base);
+    expect(p(r.runtime).metadata.name).toBe("web-run");
+    expect(p(r.service).metadata.name).toBe("web-site");
+    expect(refName(p(r.service).template.serviceAccountRef)).toBe("web-run");
+    expect(p(r.service).projectRef).toEqual({ external: "proj" });
+    expect(p(r.publicAccess).member).toBe("allUsers");
+  });
+
+  test("an existing serviceAccount creates no account", () => {
+    const r = PublicCloudRun({ ...base, serviceAccount: "x@o.iam.gserviceaccount.com" });
+    expect(r.runtime).toBeUndefined();
+    expect(p(r.service).template.serviceAccountRef).toEqual({ external: "x@o.iam.gserviceaccount.com" });
+  });
+
+  test("Direct VPC egress into the subnet for private ranges", () => {
+    const r = PublicCloudRun(base);
+    expect(p(r.service).template.vpcAccess).toEqual({
+      egress: "PRIVATE_RANGES_ONLY",
+      networkInterfaces: [{ networkRef: { name: "web-vpc" }, subnetworkRef: { name: "web-apps" } }],
+    });
+  });
+
+  test("the load balancer chain: NEG, backend, URL map, HTTP proxy, address, rule", () => {
+    const r = PublicCloudRun(base);
+    expect(p(r.neg).networkEndpointType).toBe("SERVERLESS");
+    expect(refName(p(r.neg).cloudRun.serviceRef)).toBe("web-site");
+    expect(p(r.backend).loadBalancingScheme).toBe("EXTERNAL_MANAGED");
+    expect(p(r.backend).healthChecks).toBeUndefined();
+    expect(refName(p(r.backend).backend[0].group.networkEndpointGroupRef)).toBe("web-neg");
+    expect(refName(p(r.urlMap).defaultService.backendServiceRef)).toBe("web-backend");
+    expect(refName(p(r.proxy).urlMapRef)).toBe("web-map");
+    expect(p(r.address).location).toBe("global");
+    expect(p(r.rule).portRange).toBe("80");
+    expect(refName(p(r.rule).ipAddress.addressRef)).toBe("web-ip");
+    expect(refName(p(r.rule).target.targetHTTPProxyRef)).toBe("web-proxy");
+    expect(r.certificate).toBeUndefined();
+  });
+
+  test("port sets the container, frontendPort the HTTP rule", () => {
+    const r = PublicCloudRun({ ...base, port: 3000, frontendPort: 8080 });
+    expect(p(r.service).template.containers[0].ports[0].containerPort).toBe(3000);
+    expect(p(r.rule).portRange).toBe("8080");
+  });
+
+  test("domains add a managed certificate and HTTPS, and HTTP redirects", () => {
+    const r = PublicCloudRun({ ...base, domains: ["example.com"] });
+    expect(p(r.certificate).managed.domains).toEqual(["example.com"]);
+    expect(refName(p(r.httpsProxy).urlMapRef)).toBe("web-map");
+    expect(refName(p(r.httpsProxy).sslCertificates[0])).toBe("web-cert");
+    expect(p(r.httpsRule).portRange).toBe("443");
+    expect(refName(p(r.httpsRule).target.targetHTTPSProxyRef)).toBe("web-https-proxy");
+    expect(p(r.redirectMap).defaultUrlRedirect.httpsRedirect).toBe(true);
+    expect(refName(p(r.proxy).urlMapRef)).toBe("web-redirect");
+  });
+
+  test("securityPolicy attaches to the backend service", () => {
+    const r = PublicCloudRun({ ...base, securityPolicy: "edge" });
+    expect(refName(p(r.backend).securityPolicyRef)).toBe("edge");
+  });
+});

package/src/composites/index.ts

@@ -32,3 +32,7 @@ export { GkeCrdbRegion } from "./gke-crdb-region";
 export type { GkeCrdbRegionConfig, GkeCrdbRegionNodeConfig } from "./gke-crdb-region";
 export { GpuNodePool } from "./gpu-node-pool";
 export type { GpuNodePoolProps, GpuNodePoolTaint } from "./gpu-node-pool";
+export { PrivateEgressNetwork } from "./private-egress-network";
+export type { PrivateEgressNetworkProps } from "./private-egress-network";
+export { PublicCloudRun } from "./public-cloud-run";
+export type { PublicCloudRunProps } from "./public-cloud-run";

package/src/composites/private-egress-network.ts

@@ -0,0 +1,82 @@
+/**
+ * PrivateEgressNetwork composite: a custom-mode VPC with one subnet a service sends its egress into.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { VPCNetwork, Subnetwork } from "../generated";
+
+export interface PrivateEgressNetworkProps {
+  /** Name prefix: the network is `<name>-vpc`, its subnet `<name>-apps`. */
+  name: string;
+  /** GCP region of the subnet. */
+  region: string;
+  /** IP CIDR range of the subnet. */
+  subnetCidr: string;
+  /** Enable private Google access on the subnet (default: true). */
+  privateIpGoogleAccess?: boolean;
+  /** Additional labels. */
+  labels?: Record<string, string>;
+  /** Namespace for all resources. */
+  namespace?: string;
+  /** Per-member defaults for customizing individual resources. */
+  defaults?: {
+    vpc?: Partial<ConstructorParameters<typeof VPCNetwork>[0]>;
+    subnet?: Partial<ConstructorParameters<typeof Subnetwork>[0]>;
+  };
+}
+
+/**
+ * Create a PrivateEgressNetwork composite.
+ *
+ * @example
+ * ```ts
+ * import { PrivateEgressNetwork } from "@intentius/chant-lexicon-gcp";
+ *
+ * const { vpc, subnet } = PrivateEgressNetwork({
+ *   name: "web",
+ *   region: "us-central1",
+ *   subnetCidr: "10.10.0.0/24",
+ * });
+ * ```
+ */
+export const PrivateEgressNetwork = Composite((props: PrivateEgressNetworkProps) => {
+  const {
+    name,
+    region,
+    subnetCidr,
+    privateIpGoogleAccess = true,
+    labels: extraLabels = {},
+    namespace,
+    defaults: defs,
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  const vpc = new VPCNetwork(mergeDefaults({
+    metadata: {
+      name: `${name}-vpc`,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "network" },
+    },
+    autoCreateSubnetworks: false,
+    routingMode: "REGIONAL",
+  } as Record<string, unknown>, defs?.vpc));
+
+  const subnet = new Subnetwork(mergeDefaults({
+    metadata: {
+      name: `${name}-apps`,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "subnet" },
+    },
+    region,
+    ipCidrRange: subnetCidr,
+    privateIpGoogleAccess,
+    networkRef: { name: vpc.name },
+  } as Record<string, unknown>, defs?.subnet));
+
+  return { vpc, subnet };
+}, "PrivateEgressNetwork");