@crossdelta/infrastructure 0.11.0 → 0.11.2

package/README.md

@@ -3,23 +3,52 @@
 [![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)
 
-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).
+Opinionated Pulumi library for deploying microservices to **DigitalOcean Kubernetes (DOKS)**. You describe each service as a typed config object, the package generates Deployments, Services, Ingress, Secrets, health probes, and rolling update strategies.
 
-**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)
+Built for teams running TypeScript microservices on DOKS with NATS JetStream, GHCR, and Pulumi. If that's your stack, this saves real boilerplate. If not, you're probably better off with plain Pulumi or Helm.
+
+## When to use this
+
+- You deploy multiple TypeScript services to a **DigitalOcean** Kubernetes cluster
+- You use **Pulumi** (not Terraform, not Helm-only) for infrastructure
+- You want one config object per service instead of ~150 lines of K8s resource declarations
+- You need NATS JetStream, NGINX Ingress, cert-manager, or Caddy as a reverse proxy
+
+## When NOT to use this
+
+- **AWS/GCP/Azure**: Only DOKS is implemented. EKS/AKS/GKE are not supported.
+- **Terraform or plain Helm**: This is Pulumi-only.
+- **Non-opinionated setups**: The package makes choices for you (Helm chart versions, deployment strategies, DO-specific annotations). If you need full control, use Pulumi directly.
+- **Single-service projects**: The overhead isn't worth it for one service.
 
 ## Install
 
 ```bash
 npm install @crossdelta/infrastructure @pulumi/pulumi @pulumi/kubernetes
+# For DOKS cluster creation:
+npm install @pulumi/digitalocean
+# For NATS stream deployment (optional):
+npm install @crossdelta/cloudevents
 ```
 
-## End-to-End Example
+## What's included
+
+| Module | What it does |
+|--------|-------------|
+| **Cluster** | `createDOKSCluster()`, `createVPC()`, `createK8sProviderFromKubeconfig()` |
+| **Workloads** | `deployK8sService()`, `deployK8sServices()`, `createNamespace()`, `createImagePullSecret()` |
+| **NGINX Ingress** | `deployNginxIngress()` via Helm (chart v4.11.3) |
+| **cert-manager** | `deployCertManager()` via Helm (chart v1.16.2) |
+| **NATS** | `deployNats()` via Helm (chart v1.2.6), `buildNatsUrl()` |
+| **Caddy** | `deployCaddy()`, `generateCaddyfile()` for reverse proxy with on-demand TLS |
+| **Streams** | `collectStreamDefinitions()`, `deployStreams()`, `materializeStreams()` (NATS JetStream) |
+| **Service Discovery** | `discoverServiceConfigs()` auto-discovers configs from `infra/services/*.ts` |
+| **Local Dev** | `generateComposeYaml()`, k3d cluster scripts |
+| **CLI** | `generate-env` generates `.env.local` from Pulumi config + service discovery |
+
+## Quick Start
 
-One `index.ts` that provisions a cluster, runtime, and all services:
+One `index.ts` that provisions a cluster, runtime components, and all services:
 
 ```typescript
 import {
@@ -31,7 +60,6 @@ import {
   discoverServiceConfigs,
 } from '@crossdelta/infrastructure'
 
-// 1. Cluster
 const vpc = createVPC({ name: 'my-vpc', region: 'fra1' })
 const { provider } = createDOKSCluster({
   name: 'my-cluster',
@@ -40,21 +68,19 @@ const { provider } = createDOKSCluster({
 })
 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
 
-Each file in `infra/services/` exports one config. The package derives Deployment, Service, Ingress, Secret, and probes from it:
+Each file in `infra/services/` exports one config object. The package derives all K8s resources from it:
 
 ```typescript
 import { ports, type K8sServiceConfig } from '@crossdelta/infrastructure'
@@ -75,14 +101,14 @@ const config: K8sServiceConfig = {
 export default config
 ```
 
-See `K8sServiceConfig` type for all available fields (replicas, volumes, strategy, containerEnv, etc.).
+See `K8sServiceConfig` for all fields: replicas, volumes, strategy, containerEnv, labels, annotations, serviceType, etc.
 
 ## Shared Cluster (Multi-Stack)
 
-When multiple Pulumi stacks share one cluster, use `clusterName`/`vpcName` to pin the DigitalOcean resource name (default appends the stack name):
+Pin DigitalOcean resource names with `clusterName`/`vpcName` to share a cluster across Pulumi stacks:
 
 ```typescript
-// Stack A (stage) — owns the cluster
+// Stage stack owns the cluster
 const { provider, kubeconfig } = createDOKSCluster({
   name: 'my-cluster',
   clusterName: 'my-cluster',
@@ -91,7 +117,7 @@ const { provider, kubeconfig } = createDOKSCluster({
 })
 export const clusterKubeconfig = kubeconfig
 
-// Stack B (production) — references the shared cluster
+// Production stack references stage
 const stageStack = new StackReference('org/project/stage')
 const provider = createK8sProviderFromKubeconfig(
   'production',
@@ -99,9 +125,24 @@ const provider = createK8sProviderFromKubeconfig(
 )
 ```
 
-## generate-env
+## generate-env CLI
+
+Generates `.env.local` from Pulumi secrets and discovered service configs:
+
+```bash
+npx generate-env              # defaults to stage stack
+npx generate-env --stack=production
+npx generate-env --no-pulumi  # skip Pulumi, only service discovery
+```
+
+## Limitations
+
+- **DOKS only.** No other cloud provider is implemented.
+- **Helm chart versions are pinned.** NGINX v4.11.3, cert-manager v1.16.2, NATS v1.2.6. No override option yet.
+- **Service discovery assumes a convention:** `infra/services/*.ts` files with `export default config`.
+- **`@crossdelta/cloudevents` is a hard dependency** even if you don't use NATS streams https://github.com/orderboss/platform/issues/TBD.
+- **Caddy deployment uses Recreate strategy** (RWO PVC incompatible with rolling updates).
 
-Generates `.env.local` from Pulumi secrets (default: `stage` stack) and discovered services. Override with `--stack=production` or `--no-pulumi`.
 
 ## License
 

package/dist/index.cjs

@@ -1149,7 +1149,8 @@ var indent = (text, level) => {
 `).map((line) => line.trim() === "" ? "" : `${prefix}${line}`).join(`
 `);
 };
-var basicAuthLines = (basicAuth) => basicAuth ? ["basicauth {", `  ${basicAuth.user} ${basicAuth.hash}`, "}"] : [];
+var encodeHash = (hash) => hash.startsWith("$") ? Buffer.from(hash).toString("base64") : hash;
+var basicAuthLines = (basicAuth) => basicAuth ? ["basic_auth {", `  ${basicAuth.user} ${encodeHash(basicAuth.hash)}`, "}"] : [];
 var generateHandleBlock = (handle, level, basicAuth) => {
   const hasPath = handle.path != null;
   const header = hasPath ? `handle ${handle.path}* {` : "handle {";

package/dist/index.js

@@ -1053,7 +1053,8 @@ var indent = (text, level) => {
 `).map((line) => line.trim() === "" ? "" : `${prefix}${line}`).join(`
 `);
 };
-var basicAuthLines = (basicAuth) => basicAuth ? ["basicauth {", `  ${basicAuth.user} ${basicAuth.hash}`, "}"] : [];
+var encodeHash = (hash) => hash.startsWith("$") ? Buffer.from(hash).toString("base64") : hash;
+var basicAuthLines = (basicAuth) => basicAuth ? ["basic_auth {", `  ${basicAuth.user} ${encodeHash(basicAuth.hash)}`, "}"] : [];
 var generateHandleBlock = (handle, level, basicAuth) => {
   const hasPath = handle.path != null;
   const header = hasPath ? `handle ${handle.path}* {` : "handle {";

package/package.json

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