@crossdelta/infrastructure 0.9.0 → 0.10.1

package/README.md

@@ -3,17 +3,58 @@
 [![npm version](https://img.shields.io/npm/v/@crossdelta/infrastructure.svg)](https://www.npmjs.com/package/@crossdelta/infrastructure)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-Opinionated Pulumi abstractions for deploying microservices to Kubernetes. Turns per-service config objects into Deployments, Services, Ingress, probes, and secrets.
+Pulumi abstractions that turn per-service config objects into complete Kubernetes deployments. You describe **what** each service needs (ports, env, secrets, health checks), the package handles **how** (Deployments, Services, Ingress, TLS, probes, pull secrets).
 
-## Installation
+**What you skip writing:**
+- Boilerplate K8s YAML / Pulumi resource declarations per service
+- NATS JetStream + cert-manager + NGINX Ingress setup
+- Docker registry secrets, health probes, rolling update strategies
+- Multi-environment concerns (shared cluster, per-stack namespaces)
+
+## Install
 
 ```bash
 npm install @crossdelta/infrastructure @pulumi/pulumi @pulumi/kubernetes
 ```
 
-## Usage
+## End-to-End Example
+
+One `index.ts` that provisions a cluster, runtime, and all services:
+
+```typescript
+import {
+  createDOKSCluster,
+  createVPC,
+  createNamespace,
+  deployRuntime,
+  deployK8sServices,
+  discoverServiceConfigs,
+} from '@crossdelta/infrastructure'
+
+// 1. Cluster
+const vpc = createVPC({ name: 'my-vpc', region: 'fra1' })
+const { provider } = createDOKSCluster({
+  name: 'my-cluster',
+  vpcUuid: vpc.id,
+  nodePool: { name: 'default', size: 's-4vcpu-8gb', nodeCount: 1 },
+})
+createNamespace(provider, 'my-namespace')
+
+// 2. Runtime (toggle what you need)
+const runtime = deployRuntime(provider, 'my-namespace', {
+  nats: { enabled: true, config: { replicas: 1, jetstream: { enabled: true } } },
+  ingress: { enabled: true },
+  certManager: { enabled: true, config: { email: 'ops@example.com' } },
+})
+
+// 3. Services (auto-discovered from infra/services/*.ts)
+const configs = discoverServiceConfigs('services')
+deployK8sServices(provider, 'my-namespace', configs)
+```
+
+## Service Config
 
-### Service config
+Each file in `infra/services/` exports one config. The package derives Deployment, Service, Ingress, Secret, and probes from it:
 
 ```typescript
 import { ports, type K8sServiceConfig } from '@crossdelta/infrastructure'
@@ -21,14 +62,9 @@ import { ports, type K8sServiceConfig } from '@crossdelta/infrastructure'
 const config: K8sServiceConfig = {
   name: 'my-service',
   ports: ports().http(4000).public().build(),
-  replicas: 1,
-  healthCheck: {
-    httpPath: '/health',
-    readinessPath: '/health/ready',
-  },
+  healthCheck: { httpPath: '/health' },
   ingress: { path: '/api', host: 'example.com' },
   env: { DATABASE_URL: dbUrl },
-  containerEnv: { NODE_OPTIONS: '--max-old-space-size=384' },
   secrets: { API_KEY: apiKey },
   resources: {
     requests: { cpu: '50m', memory: '64Mi' },
@@ -39,103 +75,33 @@ const config: K8sServiceConfig = {
 export default config
 ```
 
-### Deploy services
+See `K8sServiceConfig` type for all available fields (replicas, volumes, strategy, containerEnv, etc.).
 
-```typescript
-import { deployK8sServices, discoverServiceConfigs } from '@crossdelta/infrastructure'
+## Shared Cluster (Multi-Stack)
 
-const serviceConfigs = discoverServiceConfigs('services')
-
-deployK8sServices({
-  provider,
-  namespace,
-  serviceConfigs,
-  env: { NATS_URL: natsUrl },
-})
-```
-
-### Deploy runtime components
+When multiple Pulumi stacks share one cluster, use `clusterName`/`vpcName` to pin the DigitalOcean resource name (default appends the stack name):
 
 ```typescript
-import { deployRuntime } from '@crossdelta/infrastructure'
-
-const runtime = deployRuntime(provider, namespace, {
-  nats: { enabled: true, config: { replicas: 1, jetstream: { enabled: true } } },
-  ingress: {
-    enabled: true,
-    config: {
-      nginxConfig: {
-        'proxy-buffer-size': '16k', // Increase for large auth cookies/JWTs
-      },
-    },
-  },
-  certManager: { enabled: true, config: { email: 'ops@example.com' } },
+// Stack A (stage) — owns the cluster
+const { provider, kubeconfig } = createDOKSCluster({
+  name: 'my-cluster',
+  clusterName: 'my-cluster',
+  vpcUuid: vpc.id,
+  nodePool: { name: 'default', size: 's-4vcpu-8gb', nodeCount: 1 },
 })
+export const clusterKubeconfig = kubeconfig
+
+// Stack B (production) — references the shared cluster
+const stageStack = new StackReference('org/project/stage')
+const provider = createK8sProviderFromKubeconfig(
+  'production',
+  stageStack.getOutput('clusterKubeconfig'),
+)
 ```
 
-## K8sServiceConfig
-
-```typescript
-interface K8sServiceConfig {
-  name: string
-  ports: PortConfig
-  replicas?: number
-  resources?: {
-    requests?: { cpu: string; memory: string }
-    limits?: { cpu: string; memory: string }
-  }
-  healthCheck?: {
-    httpPath: string
-    readinessPath?: string       // Falls back to httpPath
-    initialDelaySeconds?: number // Default: 10
-    periodSeconds?: number       // Default: 10
-    failureThreshold?: number    // Default: 3
-  }
-  ingress?: {
-    path: string
-    host?: string
-  }
-  env?: Record<string, pulumi.Input<string>>
-  containerEnv?: Record<string, pulumi.Input<string>>
-  secrets?: Record<string, pulumi.Input<string>>
-  image?: string
-  skip?: boolean
-}
-```
-
-## Fluent Ports API
-
-```typescript
-import { ports } from '@crossdelta/infrastructure'
-
-ports().http(4000).build()                          // Simple HTTP
-ports().http(4000).public().build()                 // Public (ingress)
-ports().grpc(50051).build()                         // gRPC
-ports().http(4000).addHttp(8080, 'metrics').build() // Multiple ports
-```
+## generate-env
 
-| Method | Description |
-|--------|-------------|
-| `.http(port)` | HTTP primary port |
-| `.grpc(port)` | gRPC primary port |
-| `.primary(port, name?)` | Custom primary port |
-| `.add(port, name?, protocol?)` | Additional port |
-| `.addHttp(port, name?)` | Additional HTTP port |
-| `.addGrpc(port, name?)` | Additional gRPC port |
-| `.public()` | Expose via ingress |
-| `.protocol(type)` | Set protocol (TCP, UDP, SCTP) |
-| `.build()` | Build config |
-
-## API Reference
-
-| Function | Description |
-|----------|-------------|
-| `deployRuntime(provider, ns, config)` | Deploy runtime components |
-| `discoverServiceConfigs(dir, opts?)` | Auto-discover service configs from filesystem |
-| `deployK8sServices(opts)` | Deploy services to cluster |
-| `createNamespace(provider, name)` | Create k8s namespace |
-| `createImagePullSecret(...)` | Create registry pull secret |
-| `ports()` | Fluent port builder |
+Generates `.env.local` from Pulumi secrets (default: `stage` stack) and discovered services. Override with `--stack=production` or `--no-pulumi`.
 
 ## License
 

package/bin/generate-env.mjs

@@ -162,12 +162,14 @@ var discoverServices = (servicesDirectory) => {
 };
 var main = async () => {
   const noPulumi = process.argv.includes("--no-pulumi");
+  const stackArg = process.argv.find((arg) => arg.startsWith("--stack="));
+  const stack = stackArg?.split("=")[1] ?? "stage";
   const workspaceRootDirectory = findWorkspaceRoot();
   const infraDirectory = join(workspaceRootDirectory, "infra");
   const servicesDirectory = join(infraDirectory, "services");
   const envLines = ["# Generated .env.local"];
   if (!noPulumi && existsSync(join(infraDirectory, "Pulumi.yaml"))) {
-    const pulumiEntries = await loadPulumiConfig(infraDirectory, "dev");
+    const pulumiEntries = await loadPulumiConfig(infraDirectory, stack);
     if (pulumiEntries.length > 0) {
       envLines.push("", "# Pulumi Secrets");
       envLines.push(...pulumiEntries);

package/bin/generate-env.ts

@@ -3,12 +3,12 @@
  * Generate environment variables for local development.
  *
  * This script:
- * 1. Loads secrets from Pulumi config (dev stack) if available
+ * 1. Loads secrets from Pulumi config (defaults to stage stack) if available
  * 2. Discovers services from infra/services/*.ts (parses files without importing)
  * 3. Generates service URLs and ports for localhost
  * 4. Writes .env.local to the workspace root
  *
- * Usage: generate-env [--no-pulumi]
+ * Usage: generate-env [--stack=<name>] [--no-pulumi]
  */
 import { execSync } from 'node:child_process'
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
@@ -177,13 +177,15 @@ const discoverServices = (servicesDirectory: string): MinimalServiceConfig[] =>
 
 const main = async () => {
   const noPulumi = process.argv.includes('--no-pulumi')
+  const stackArg = process.argv.find((arg) => arg.startsWith('--stack='))
+  const stack = stackArg?.split('=')[1] ?? 'stage'
   const workspaceRootDirectory = findWorkspaceRoot()
   const infraDirectory = join(workspaceRootDirectory, 'infra')
   const servicesDirectory = join(infraDirectory, 'services')
   const envLines: string[] = ['# Generated .env.local']
 
   if (!noPulumi && existsSync(join(infraDirectory, 'Pulumi.yaml'))) {
-    const pulumiEntries = await loadPulumiConfig(infraDirectory, 'dev')
+    const pulumiEntries = await loadPulumiConfig(infraDirectory, stack)
     if (pulumiEntries.length > 0) {
       envLines.push('', '# Pulumi Secrets')
       envLines.push(...pulumiEntries)

package/dist/index.cjs

@@ -1139,7 +1139,7 @@ function createDOKSCluster(config) {
   const stack = pulumi4.getStack();
   const region = config.region ?? "fra1";
   const cluster = new digitalocean.KubernetesCluster(config.name, {
-    name: `${config.name}-${stack}`,
+    name: config.clusterName ?? `${config.name}-${stack}`,
     region,
     version: config.version ?? "1.32.10-do.0",
     vpcUuid: config.vpcUuid,
@@ -1190,7 +1190,7 @@ function createVPC(config) {
   const stack = pulumi5.getStack();
   const region = config.region ?? "fra1";
   return new digitalocean2.Vpc(config.name, {
-    name: `${config.name}-${stack}`,
+    name: config.vpcName ?? `${config.name}-${stack}`,
     region,
     description: config.description ?? `VPC for ${config.name}`,
     ipRange: config.ipRange

package/dist/index.js

@@ -1045,7 +1045,7 @@ function createDOKSCluster(config) {
   const stack = pulumi4.getStack();
   const region = config.region ?? "fra1";
   const cluster = new digitalocean.KubernetesCluster(config.name, {
-    name: `${config.name}-${stack}`,
+    name: config.clusterName ?? `${config.name}-${stack}`,
     region,
     version: config.version ?? "1.32.10-do.0",
     vpcUuid: config.vpcUuid,
@@ -1096,7 +1096,7 @@ function createVPC(config) {
   const stack = pulumi5.getStack();
   const region = config.region ?? "fra1";
   return new digitalocean2.Vpc(config.name, {
-    name: `${config.name}-${stack}`,
+    name: config.vpcName ?? `${config.name}-${stack}`,
     region,
     description: config.description ?? `VPC for ${config.name}`,
     ipRange: config.ipRange

package/dist/runtimes/doks/types.d.ts

@@ -28,8 +28,10 @@ export type Region = digitalocean.Region;
  * ```
  */
 export interface DOKSClusterConfig {
-    /** Cluster name (will be suffixed with stack name) */
+    /** Pulumi resource name (logical, for state tracking) */
     name: string;
+    /** Actual cluster name in DigitalOcean. Defaults to `${name}-${stack}` */
+    clusterName?: string;
     /** DigitalOcean region (defaults to 'fra1') */
     region?: digitalocean.Region | string;
     /** Kubernetes version - use `doctl kubernetes options versions` to list available */
@@ -65,8 +67,10 @@ export interface DOKSClusterConfig {
  * Simplified VPC configuration with stack-aware naming.
  */
 export interface VPCConfig {
-    /** VPC name (will be suffixed with stack name) */
+    /** Pulumi resource name (logical, for state tracking) */
     name: string;
+    /** Actual VPC name in DigitalOcean. Defaults to `${name}-${stack}` */
+    vpcName?: string;
     /** DigitalOcean region (defaults to 'fra1') */
     region?: digitalocean.Region | string;
     /** Optional description */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/infrastructure",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "type": "module",
   "license": "MIT",
   "publishConfig": {