@cyc-seattle/platform 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+# platform
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pulumi stacks for CYC Community Sailing Center's shared Google Cloud platform: the things no single
+app owns. The apps that run on it live in their own repos, such as
+[isthmia](https://github.com/cyc-seattle/isthmia).
+
+## Stacks
+
+| Stack                           | Holds                                                                                                                                                                                                   | Applied by                                                                                                        |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| [`bootstrap`](stacks/bootstrap) | Service accounts and project IAM, the Pulumi state buckets and KMS keys, and the org's GitHub repos and settings                                                                                        | A human with project Owner and `gh` `admin:org`. Never CI.                                                        |
+| [`cloud`](stacks/cloud)         | The VPC, the cluster subnet and its Cloud NAT, the private services peering, the prod and dev Cloud SQL instances, the DNS zones, and Artifact Registry                                                 | `deploy-runner`, from Actions after approval. A deployer, with `mise run deploy`, when breaking glass.            |
+| [`cluster`](stacks/cluster)     | The GKE Autopilot cluster, the shared Gateway, its address, certificates, and DNS records, the `dev` namespace with its RBAC, quota, and network policy, and each environment's `platform/outputs.json` | `deploy-runner`, from Actions after approval. A deployer, with `mise run deploy`, when breaking glass.            |
+| [`smoke`](stacks/smoke)         | One `WebService` in dev, at `smoke.dev.cycsail.team`, for the integration tests                                                                                                                         | `deploy-dev`, from Actions on every PR. A deployer, with `PULUMI_STACK=dev mise run deploy`, when breaking glass. |
+
+## @cyc-seattle/platform
+
+`src/` is the `@cyc-seattle/platform` package, which the stacks here and the apps' stacks import:
+
+- `getPlatformOutputs()` reads an environment's `platform/outputs.json` from its state bucket. The
+  `cluster` stack writes it. Dev stacks can't read prod's backend, so this replaces a
+  StackReference for platform values (cyc-seattle/isthmia#215).
+- `clusterProvider(platform)` builds a Kubernetes provider for the cluster. Its kubeconfig runs
+  `gke-gcloud-auth-plugin` with Application Default Credentials, so Pulumi must run under mise,
+  where `mise run install` puts the plugin on `PATH`.
+- `WebService` runs an HTTP service behind the environment's Gateway, with secure defaults. Its pods
+  get no IAM; grant roles to its `member`, a Workload Identity principal.
+- `enableService` enables a Google Cloud API.
+
+`mise run build` builds it into `dist/`, which is all it publishes.
+
+## Setup
+
+[mise](https://mise.jdx.dev/) provides the tools.
+
+```sh
+mise trust
+mise run install
+mise run auth-adc
+```
+
+`mise run auth-adc` logs Application Default Credentials in as your own account. Pulumi uses them
+for GCP and for the state bucket. [docs/manual-setup.md](docs/manual-setup.md) lists the access a
+deployer needs first.
+
+## Deploy
+
+### From Actions
+
+`.github/workflows/pull-request.yml` deploys through the org's reusable `deploy.yml`, which
+authenticates with Workload Identity Federation and stores no credentials. Each job runs in a
+GitHub environment that holds its identity and state bucket:
+
+| Event          | Jobs, in order                                                                            |
+| -------------- | ----------------------------------------------------------------------------------------- |
+| Pull request   | `ci`, then `dev`: `mise run deploy` as `deploy-dev`, then `mise run integration`          |
+| Push to `main` | `ci`, `dev`, then `prod-preview`, then `prod`, which waits for the `maintainers` approval |
+
+`prod-preview` runs `mise run preview` as `deploy-runner` and writes the diff to the job summary.
+`prod` runs `mise run deploy` on the same commit once approved. A PR from a fork gets no OIDC token,
+so its `dev` job is skipped.
+
+`PULUMI_STACK` picks what the tasks run (`scripts/each-stack`): `dev` is `smoke`, and `prod` is
+`cloud`, then `cluster`. `integration` is dev only.
+
+`bootstrap` is never deployed from Actions (cyc-seattle/isthmia#118). It holds the identities that
+CI assumes, and a human with project Owner and `gh` `admin:org` applies it with the tasks below.
+
+### From a laptop
+
+Local deploys stay as the break-glass path. A deployer applies with the same tasks:
+
+```sh
+mise run preview-bootstrap
+mise run deploy-bootstrap
+mise run preview
+mise run deploy
+PULUMI_STACK=dev mise run deploy
+```
+
+`mise run deploy` applies `cloud`, then `cluster`. Prod stacks read `cloud`'s outputs through a
+StackReference. Dev stacks can't read prod state, so `cluster` writes each environment's platform
+values to `platform/outputs.json` in that environment's state bucket.
+
+`bootstrap`'s GitHub provider uses `gh auth token`, so log `gh` in as a cyc-seattle org owner with
+the `admin:org` scope: `gh auth refresh -h github.com -s admin:org`. Deploys refresh first, so they
+delete a label added by hand.
+
+## State
+
+Each environment's state lives in its own bucket, `gs://cyc-admin-scripts-pulumi-<stack>`, with its
+secrets encrypted by the `state-<stack>` KMS key. `stacks/bootstrap/state.ts` creates both.
+`mise.toml` picks the bucket from `PULUMI_STACK`, which defaults to `prod`, so stack names are
+`organization/<project>/<stack>`. It sets `GOOGLE_APPLICATION_CREDENTIALS` to the shared `.gcloud/`
+login only when it isn't already set, so Actions' credentials win.
+
+`bootstrap`'s own state lives in the bucket it creates. Both the bucket and the key are protected.
+
+## Development
+
+```sh
+mise run ci
+```
+
+Runs the type check, Prettier, ESLint, and the unit tests. Tests mock Pulumi with
+`pulumi.runtime.setMocks` and never call a live API.
+
+```sh
+mise run integration
+```
+
+Runs the Gherkin scenarios in `features/` against dev, after `PULUMI_STACK=dev mise run deploy`. They run as
+whatever identity Application Default Credentials hold. The isolation scenarios expect `deploy-dev`,
+so as a human, log Application Default Credentials in with `--impersonate-service-account` first.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { clusterProvider, type ClusterProviderArgs } from "./kubernetes";
+export { getPlatformOutputs, parsePlatformOutputs, platformOutputsSchema, readPlatformOutputs, stateBucket, type PlatformOutputs, type PlatformOutputsArgs, } from "./outputs";
+export { enableService } from "./services";
+export { WebService, type WebServiceArgs } from "./web-service";

package/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebService = exports.enableService = exports.stateBucket = exports.readPlatformOutputs = exports.platformOutputsSchema = exports.parsePlatformOutputs = exports.getPlatformOutputs = exports.clusterProvider = void 0;
+var kubernetes_1 = require("./kubernetes");
+Object.defineProperty(exports, "clusterProvider", { enumerable: true, get: function () { return kubernetes_1.clusterProvider; } });
+var outputs_1 = require("./outputs");
+Object.defineProperty(exports, "getPlatformOutputs", { enumerable: true, get: function () { return outputs_1.getPlatformOutputs; } });
+Object.defineProperty(exports, "parsePlatformOutputs", { enumerable: true, get: function () { return outputs_1.parsePlatformOutputs; } });
+Object.defineProperty(exports, "platformOutputsSchema", { enumerable: true, get: function () { return outputs_1.platformOutputsSchema; } });
+Object.defineProperty(exports, "readPlatformOutputs", { enumerable: true, get: function () { return outputs_1.readPlatformOutputs; } });
+Object.defineProperty(exports, "stateBucket", { enumerable: true, get: function () { return outputs_1.stateBucket; } });
+var services_1 = require("./services");
+Object.defineProperty(exports, "enableService", { enumerable: true, get: function () { return services_1.enableService; } });
+var web_service_1 = require("./web-service");
+Object.defineProperty(exports, "WebService", { enumerable: true, get: function () { return web_service_1.WebService; } });

package/dist/kubernetes.d.ts

@@ -0,0 +1,19 @@
+import * as k8s from "@pulumi/kubernetes";
+import * as pulumi from "@pulumi/pulumi";
+import type { PlatformOutputs } from "./outputs";
+export interface ClusterProviderArgs {
+    /**
+     * Keeps a kubeconfig that is unknown or changes, such as during a cluster update, from replacing
+     * the provider and with it every Kubernetes resource it manages.
+     */
+    clusterIdentifier?: pulumi.Input<string>;
+}
+/**
+ * A Kubernetes provider for the environment's cluster. Its kubeconfig runs gke-gcloud-auth-plugin
+ * with Application Default Credentials, so it is the same on every run, unlike one that embeds an
+ * access token. The plugin must be on PATH: `mise run install` adds it. The cluster stack passes
+ * only the endpoint, because it writes the rest.
+ */
+export declare function clusterProvider(platform: pulumi.Input<{
+    clusterEndpoint: pulumi.Input<PlatformOutputs["clusterEndpoint"]>;
+}>, name?: string, opts?: pulumi.CustomResourceOptions, args?: ClusterProviderArgs): k8s.Provider;

package/dist/kubernetes.js

@@ -0,0 +1,69 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clusterProvider = clusterProvider;
+const k8s = __importStar(require("@pulumi/kubernetes"));
+const pulumi = __importStar(require("@pulumi/pulumi"));
+/**
+ * A Kubernetes provider for the environment's cluster. Its kubeconfig runs gke-gcloud-auth-plugin
+ * with Application Default Credentials, so it is the same on every run, unlike one that embeds an
+ * access token. The plugin must be on PATH: `mise run install` adds it. The cluster stack passes
+ * only the endpoint, because it writes the rest.
+ */
+function clusterProvider(platform, name = "cluster", opts, args = {}) {
+    // The DNS-based endpoint serves a publicly trusted certificate, so the kubeconfig needs no CA.
+    const kubeconfig = pulumi.output(platform).clusterEndpoint.apply((endpoint) => JSON.stringify({
+        apiVersion: "v1",
+        kind: "Config",
+        clusters: [{ name: "cluster", cluster: { server: `https://${endpoint}` } }],
+        users: [
+            {
+                name: "user",
+                user: {
+                    exec: {
+                        apiVersion: "client.authentication.k8s.io/v1beta1",
+                        command: "gke-gcloud-auth-plugin",
+                        args: ["--use_application_default_credentials"],
+                        installHint: "Run `mise run install`, and run Pulumi under mise.",
+                        provideClusterInfo: true,
+                    },
+                },
+            },
+        ],
+        contexts: [{ name: "cluster", context: { cluster: "cluster", user: "user" } }],
+        "current-context": "cluster",
+    }));
+    return new k8s.Provider(name, { kubeconfig, clusterIdentifier: args.clusterIdentifier }, opts);
+}

package/dist/outputs.d.ts

@@ -0,0 +1,34 @@
+import * as pulumi from "@pulumi/pulumi";
+import { z } from "zod";
+export declare const platformOutputsSchema: z.ZodObject<{
+    project: z.ZodString;
+    projectNumber: z.ZodString;
+    region: z.ZodString;
+    cluster: z.ZodString;
+    clusterEndpoint: z.ZodString;
+    namespace: z.ZodString;
+    gateway: z.ZodObject<{
+        name: z.ZodString;
+        namespace: z.ZodString;
+    }, z.core.$strip>;
+    domain: z.ZodString;
+    sqlConnectionName: z.ZodString;
+    registry: z.ZodString;
+}, z.core.$strip>;
+/** One environment's platform values: where its cluster, Gateway, database, and registry are. */
+export type PlatformOutputs = z.infer<typeof platformOutputsSchema>;
+export declare const outputsObject = "platform/outputs.json";
+/** The state bucket of an environment, as `stacks/bootstrap/state.ts` names it. */
+export declare function stateBucket(project: string, environment: string): string;
+/** Parses and validates the outputs file's text. `source` names the file in error messages. */
+export declare function parsePlatformOutputs(text: string, source: string): PlatformOutputs;
+export interface PlatformOutputsArgs {
+    /** The environment, which names the state bucket. Defaults to the stack's name. */
+    environment?: string;
+    /** The project that holds the state bucket. Defaults to `gcp:project`. */
+    project?: string;
+}
+/** Reads this environment's platform values from its state bucket. Most programs want `getPlatformOutputs`. */
+export declare function readPlatformOutputs(args?: PlatformOutputsArgs): Promise<PlatformOutputs>;
+/** Reads this environment's platform values from its state bucket. */
+export declare function getPlatformOutputs(args?: PlatformOutputsArgs): pulumi.Output<PlatformOutputs>;

package/dist/outputs.js

@@ -0,0 +1,98 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.outputsObject = exports.platformOutputsSchema = void 0;
+exports.stateBucket = stateBucket;
+exports.parsePlatformOutputs = parsePlatformOutputs;
+exports.readPlatformOutputs = readPlatformOutputs;
+exports.getPlatformOutputs = getPlatformOutputs;
+const gcp = __importStar(require("@pulumi/gcp"));
+const pulumi = __importStar(require("@pulumi/pulumi"));
+const zod_1 = require("zod");
+// The cluster stack writes this object to each environment's state bucket, because a StackReference
+// can't cross from a dev stack into prod's backend (cyc-seattle/isthmia#215).
+exports.platformOutputsSchema = zod_1.z.object({
+    project: zod_1.z.string().min(1),
+    projectNumber: zod_1.z.string().regex(/^\d+$/),
+    region: zod_1.z.string().min(1),
+    cluster: zod_1.z.string().min(1),
+    clusterEndpoint: zod_1.z.string().min(1),
+    namespace: zod_1.z.string().min(1),
+    gateway: zod_1.z.object({ name: zod_1.z.string().min(1), namespace: zod_1.z.string().min(1) }),
+    domain: zod_1.z.string().min(1),
+    sqlConnectionName: zod_1.z.string().min(1),
+    registry: zod_1.z.string().min(1),
+});
+exports.outputsObject = "platform/outputs.json";
+/** The state bucket of an environment, as `stacks/bootstrap/state.ts` names it. */
+function stateBucket(project, environment) {
+    return `${project}-pulumi-${environment}`;
+}
+/** Parses and validates the outputs file's text. `source` names the file in error messages. */
+function parsePlatformOutputs(text, source) {
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`${source} is not valid JSON: ${e.message}`);
+    }
+    const result = exports.platformOutputsSchema.safeParse(json);
+    if (!result.success) {
+        throw new Error(`${source} doesn't hold the platform outputs:\n${zod_1.z.prettifyError(result.error)}`);
+    }
+    return result.data;
+}
+/** Reads this environment's platform values from its state bucket. Most programs want `getPlatformOutputs`. */
+async function readPlatformOutputs(args = {}) {
+    const project = args.project ?? new pulumi.Config("gcp").require("project");
+    const bucket = stateBucket(project, args.environment ?? pulumi.getStack());
+    const source = `gs://${bucket}/${exports.outputsObject}`;
+    let content;
+    try {
+        ({ content } = await gcp.storage.getBucketObjectContent({ bucket, name: exports.outputsObject }));
+    }
+    catch (e) {
+        throw new Error(`Can't read ${source}. The cluster stack writes it.\n${e.message}`);
+    }
+    if (!content) {
+        throw new Error(`${source} is empty. The cluster stack writes it.`);
+    }
+    return parsePlatformOutputs(content, source);
+}
+/** Reads this environment's platform values from its state bucket. */
+function getPlatformOutputs(args = {}) {
+    return pulumi.output(readPlatformOutputs(args));
+}

package/dist/services.d.ts

@@ -0,0 +1,8 @@
+import * as gcp from "@pulumi/gcp";
+/**
+ * Enables a Google Cloud API, memoized so repeated calls for the same API return the same resource.
+ * Returns the {@link gcp.projects.Service} so the resources that need the API can `dependsOn` it and
+ * therefore be created only after it is enabled. Enable each API from the file that uses it, rather
+ * than maintaining a central list.
+ */
+export declare function enableService(service: string): gcp.projects.Service;

package/dist/services.js

@@ -0,0 +1,57 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enableService = enableService;
+const gcp = __importStar(require("@pulumi/gcp"));
+const enabled = new Map();
+/**
+ * Enables a Google Cloud API, memoized so repeated calls for the same API return the same resource.
+ * Returns the {@link gcp.projects.Service} so the resources that need the API can `dependsOn` it and
+ * therefore be created only after it is enabled. Enable each API from the file that uses it, rather
+ * than maintaining a central list.
+ */
+function enableService(service) {
+    const existing = enabled.get(service);
+    if (existing) {
+        return existing;
+    }
+    const svc = new gcp.projects.Service(`enable-${service}`, {
+        service,
+        // Leave the API enabled if the resource is torn down — other things may rely on it.
+        disableOnDestroy: false,
+    });
+    enabled.set(service, svc);
+    return svc;
+}

package/dist/web-service.d.ts

@@ -0,0 +1,41 @@
+import * as k8s from "@pulumi/kubernetes";
+import * as pulumi from "@pulumi/pulumi";
+import type { PlatformOutputs } from "./outputs";
+type Probe = k8s.types.input.core.v1.Probe;
+export interface WebServiceArgs {
+    /** The environment's platform values, from `getPlatformOutputs`. */
+    platform: pulumi.Input<PlatformOutputs>;
+    /** The environment's cluster, from `clusterProvider`. Required, so it never uses a local kubeconfig. */
+    provider: k8s.Provider;
+    /** The public hostname. It must be in the environment's domain. */
+    hostname: string;
+    image: pulumi.Input<string>;
+    /** The port the container serves HTTP on. */
+    port: number;
+    requests: {
+        cpu: pulumi.Input<string>;
+        memory: pulumi.Input<string>;
+    };
+    /** An HTTP GET probe. The load balancer's health check uses the same path. */
+    readinessProbe: Probe & {
+        httpGet: pulumi.Input<k8s.types.input.core.v1.HTTPGetAction>;
+    };
+    livenessProbe?: Probe;
+    env?: pulumi.Input<k8s.types.input.core.v1.EnvVar>[];
+    replicas?: number;
+    /** Needed when the image's user is a name, which `runAsNonRoot` can't check. */
+    runAsUser?: number;
+}
+/** Returns `hostname` if it is the environment's domain or a name under it, and throws otherwise. */
+export declare function checkHostname(hostname: string, domain: string): string;
+/**
+ * An HTTP service behind the environment's shared Gateway: a Deployment, a Service, an HTTPRoute, a
+ * Kubernetes ServiceAccount, and a HealthCheckPolicy. Its pods get no IAM; grant roles to `member`.
+ */
+export declare class WebService extends pulumi.ComponentResource {
+    /** The pods' Workload Identity principal, for IAM grants. */
+    readonly member: pulumi.Output<string>;
+    readonly url: pulumi.Output<string>;
+    constructor(name: string, args: WebServiceArgs, opts?: pulumi.ComponentResourceOptions);
+}
+export {};

package/dist/web-service.js

@@ -0,0 +1,153 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebService = void 0;
+exports.checkHostname = checkHostname;
+const k8s = __importStar(require("@pulumi/kubernetes"));
+const pulumi = __importStar(require("@pulumi/pulumi"));
+/** Returns `hostname` if it is the environment's domain or a name under it, and throws otherwise. */
+function checkHostname(hostname, domain) {
+    const host = hostname.toLowerCase();
+    const base = domain.toLowerCase();
+    if (host !== base && !host.endsWith(`.${base}`)) {
+        throw new Error(`Hostname ${hostname} isn't in the environment's domain, ${domain}.`);
+    }
+    return hostname;
+}
+/**
+ * An HTTP service behind the environment's shared Gateway: a Deployment, a Service, an HTTPRoute, a
+ * Kubernetes ServiceAccount, and a HealthCheckPolicy. Its pods get no IAM; grant roles to `member`.
+ */
+class WebService extends pulumi.ComponentResource {
+    /** The pods' Workload Identity principal, for IAM grants. */
+    member;
+    url;
+    constructor(name, args, opts) {
+        super("cyc-seattle:platform:WebService", name, {}, opts);
+        // The types already require these, but a JavaScript caller or a cast can skip them.
+        if (!args.requests?.cpu || !args.requests?.memory) {
+            throw new Error(`WebService "${name}" needs CPU and memory requests.`);
+        }
+        if (!args.readinessProbe?.httpGet) {
+            throw new Error(`WebService "${name}" needs an HTTP readiness probe.`);
+        }
+        const platform = pulumi.output(args.platform);
+        const namespace = platform.namespace;
+        // A bad hostname fails the HTTPRoute's registration, so preview fails before anything applies.
+        const hostname = platform.domain.apply((domain) => checkHostname(args.hostname, domain));
+        // The namespace is the environment's name.
+        const spot = namespace.apply((ns) => ns === "dev");
+        const labels = { "app.kubernetes.io/name": name };
+        const metadata = { name, namespace, labels };
+        const child = { parent: this, provider: args.provider };
+        const serviceAccount = new k8s.core.v1.ServiceAccount(name, { metadata, automountServiceAccountToken: false }, child);
+        new k8s.apps.v1.Deployment(name, {
+            metadata,
+            spec: {
+                replicas: args.replicas ?? 1,
+                selector: { matchLabels: labels },
+                template: {
+                    metadata: { labels },
+                    spec: {
+                        serviceAccountName: serviceAccount.metadata.name,
+                        automountServiceAccountToken: false,
+                        // Autopilot schedules a pod with this selector on Spot capacity.
+                        nodeSelector: spot.apply((s) => (s ? { "cloud.google.com/gke-spot": "true" } : {})),
+                        securityContext: {
+                            runAsNonRoot: true,
+                            seccompProfile: { type: "RuntimeDefault" },
+                            ...(args.runAsUser !== undefined && { runAsUser: args.runAsUser, runAsGroup: args.runAsUser }),
+                        },
+                        containers: [
+                            {
+                                name,
+                                image: args.image,
+                                ports: [{ name: "http", containerPort: args.port }],
+                                resources: { requests: args.requests },
+                                readinessProbe: args.readinessProbe,
+                                ...(args.livenessProbe && { livenessProbe: args.livenessProbe }),
+                                ...(args.env && { env: args.env }),
+                                securityContext: {
+                                    allowPrivilegeEscalation: false,
+                                    readOnlyRootFilesystem: true,
+                                    capabilities: { drop: ["ALL"] },
+                                },
+                            },
+                        ],
+                    },
+                },
+            },
+        }, child);
+        const service = new k8s.core.v1.Service(name, {
+            metadata,
+            spec: {
+                selector: labels,
+                ports: [{ name: "http", port: 80, targetPort: "http" }],
+            },
+        }, child);
+        new k8s.apiextensions.CustomResource(name, {
+            apiVersion: "gateway.networking.k8s.io/v1",
+            kind: "HTTPRoute",
+            metadata,
+            spec: {
+                parentRefs: [{ name: platform.gateway.name, namespace: platform.gateway.namespace }],
+                hostnames: [hostname],
+                rules: [{ backendRefs: [{ name: service.metadata.name, port: 80 }] }],
+            },
+        }, child);
+        // Without it, the load balancer checks `/` on the serving port, which an app may not answer.
+        new k8s.apiextensions.CustomResource(name, {
+            apiVersion: "networking.gke.io/v1",
+            kind: "HealthCheckPolicy",
+            metadata,
+            spec: {
+                default: {
+                    config: {
+                        type: "HTTP",
+                        httpHealthCheck: {
+                            portSpecification: "USE_SERVING_PORT",
+                            requestPath: pulumi.output(args.readinessProbe.httpGet).apply((get) => get?.path ?? "/"),
+                        },
+                    },
+                },
+                targetRef: { group: "", kind: "Service", name: service.metadata.name },
+            },
+        }, child);
+        this.member = pulumi.interpolate `principal://iam.googleapis.com/projects/${platform.projectNumber}/locations/global/workloadIdentityPools/${platform.project}.svc.id.goog/subject/ns/${namespace}/sa/${serviceAccount.metadata.name}`;
+        this.url = pulumi.interpolate `https://${hostname}/`;
+        this.registerOutputs({ member: this.member, url: this.url });
+    }
+}
+exports.WebService = WebService;

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@cyc-seattle/platform",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Pulumi components for CYC's shared Google Cloud platform: WebService, the platform outputs reader, and the stacks that build the platform",
+  "author": "CYC Community Sailing Center",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/cyc-seattle/platform#readme",
+  "bugs": {
+    "url": "https://github.com/cyc-seattle/platform/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyc-seattle/platform.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@10.34.6",
+  "prettier": "@cyc-seattle/ts-config/prettier",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "pnpm run build"
+  },
+  "dependencies": {
+    "zod": "4.6.7"
+  },
+  "peerDependencies": {
+    "@pulumi/gcp": "^8",
+    "@pulumi/kubernetes": "^4",
+    "@pulumi/pulumi": "^3"
+  },
+  "devDependencies": {
+    "@amiceli/vitest-cucumber": "7.0.0",
+    "@cyc-seattle/ts-config": "^0.1.2",
+    "@pulumi/command": "1.2.1",
+    "@pulumi/gcp": "8.41.1",
+    "@pulumi/github": "6.15.0",
+    "@pulumi/kubernetes": "4.34.2",
+    "@pulumi/pulumi": "3.264.0",
+    "@types/js-yaml": "4.0.9",
+    "@types/node": "^22.19.1",
+    "eslint": "^9.39.5",
+    "google-auth-library": "^11.3.0",
+    "js-yaml": "^5.4.3",
+    "prettier": "^3.9.10",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.11"
+  }
+}