@crossdelta/infrastructure 0.2.27 → 0.3.0-beta.1

package/README.md

@@ -3,56 +3,85 @@
 [![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)
 
-Infrastructure-as-Code helpers for deploying microservices to DigitalOcean with Pulumi.
+Infrastructure-as-Code toolkit for deploying microservices to Kubernetes with Pulumi.
 
-> **Note**: This is an MVP architecture optimized for simplicity and cost-efficiency.
-> For production with SLAs, consider managed services or HA clustering.
+**Current Support:**
+- ✅ **DigitalOcean Kubernetes (DOKS)** - Production-ready, fully tested
+- ✅ **Local Kubernetes (k3d)** - Development environment
+
+**Planned Support:**
+- 🚧 **AWS EKS** - Planned (contributions welcome)
+- 🚧 **Azure AKS** - Planned (contributions welcome)
+- 🚧 **Google GKE** - Planned (contributions welcome)
+
+The architecture is **provider-agnostic** - runtime components (NATS, Ingress, Cert-Manager) use provider-specific implementations, but service configs remain portable.
 
 ## Architecture Overview
 
-```mermaid
-graph TB
-    subgraph DO[DigitalOcean]
-        subgraph APP[App Platform]
-            FE[frontend :3000]
-            API[api :4000]
-            WRK[worker :4001]
-        end
-        
-        subgraph DROP[Droplet]
-            NATS[NATS + JetStream]
-            VOL[(Volume /data)]
-            NATS --> VOL
-        end
-        
-        APP -->|VPC| DROP
-    end
-    
-    style APP fill:#e1f5fe
-    style DROP fill:#fff3e0
-    style VOL fill:#f5f5f5
+```
+                     ┌─────────────────────────────────────────┐
+                     │  DigitalOcean Kubernetes (DOKS)        │
+                     │                                         │
+     ┌───────────────┤  Runtime Components:                   │
+     │               │  • NATS + JetStream (messaging)        │
+ Internet            │  • NGINX Ingress (routing)             │
+     │               │  • Cert-Manager (TLS certs)            │
+     │               └─────────────────────────────────────────┘
+     ▼                                    │
+┌──────────┐                              ▼
+│   DNS    │         ┌──────────────────────────────────────────┐
+└────┬─────┘         │  Microservices:                          │
+     │               │                                           │
+     ▼               │  ┌──────────────┐  ┌──────────────┐     │
+┌──────────┐         │  │ api-gateway  │  │   orders     │     │
+│   Load   │◄────────┼──┤   :4000      │  │   :4001      │     │
+│ Balancer │         │  └──────┬───────┘  └──────┬───────┘     │
+└──────────┘         │         │                  │             │
+                     │         ▼                  ▼             │
+                     │  ┌──────────────────────────────┐       │
+                     │  │    NATS (Event Stream)       │       │
+                     │  └──────────────────────────────┘       │
+                     │         ▲                  ▲             │
+                     │         │                  │             │
+                     │  ┌──────┴───────┐  ┌──────┴───────┐     │
+                     │  │notifications │  │  storefront  │     │
+                     │  │   :4002      │  │   :3000      │     │
+                     │  └──────────────┘  └──────────────┘     │
+                     └──────────────────────────────────────────┘
 ```
 
-### Platform Strategy
-
-| Platform | Use Case | Pros | Cons |
-|----------|----------|------|------|
-| **App Platform** | Stateless services (APIs, frontends) | Auto-scaling, zero-ops, built-in networking | No persistent volumes |
-| **Droplet** | Stateful services (NATS, databases) | Persistent volumes, full control | Manual management |
+### Why Kubernetes?
 
-**Why this split?** DigitalOcean App Platform doesn't support persistent volumes.
-Services like NATS with JetStream need persistent storage for message durability.
+| Feature | Benefit |
+|---------|---------|
+| **Declarative** | Define desired state, K8s maintains it |
+| **Self-healing** | Auto-restart failed pods, reschedule on node failure |
+| **Scaling** | Horizontal pod autoscaling based on metrics |
+| **Rolling updates** | Zero-downtime deployments |
+| **Service discovery** | Built-in DNS for pod-to-pod communication |
+| **Persistent volumes** | StatefulSets for databases and message queues |
 
 ## Features
 
-- **Dual Platform Support** - Deploy to App Platform or Droplets from the same config
-- **Service Discovery** - Auto-discover service configs from `infra/services/*.ts`
-- **Type-safe Config** - Full TypeScript support with `ServiceConfig` type
-- **Smart Routing** - Automatic ingress rules for public services
-- **VPC Networking** - Secure private communication between platforms
-- **Persistent Volumes** - Automatic volume creation and mounting for Droplets
-- **Config File Mounting** - Share config files between local dev and production
-- **URL Generation** - Auto-generate service URLs and port env vars
+### 🚀 Core Features
+- **Provider-Agnostic** - One config for DOKS, k3d, EKS, AKS, GKE
+- **Unified Runtime API** - Single `deployRuntime()` for NATS, Ingress, Cert-Manager
+- **Service Discovery** - Auto-discover services from `infra/services/*.ts`
+- **Fluent Port Configuration** - Modern API for HTTP, gRPC, custom ports
+- **Health Checks** - Automatic HTTP health check configuration
+- **Type-Safe** - Full TypeScript support with strict typing
+
+### 📦 Runtime Components
+- **NATS + JetStream** - Event-driven messaging with persistence
+- **NGINX Ingress** - HTTP routing and load balancing
+- **Cert-Manager** - Automatic TLS certificates via Let's Encrypt
+- **OpenTelemetry** - Distributed tracing and metrics (via `@crossdelta/telemetry`)
+
+### 🔧 Developer Experience
+- **Auto-Generated Types** - Service names from directory structure
+- **Environment Generation** - `.env.local` from Pulumi secrets
+- **Image Registry Support** - GHCR, DockerHub, DOCR
+- **Health Check Integration** - Kubernetes liveness/readiness probes
 
 ## Installation
 
@@ -62,381 +91,570 @@ npm install @crossdelta/infrastructure
 
 ## Quick Start
 
-### 1. Create service configs
+### 1. Install dependencies
+
+```bash
+npm install @crossdelta/infrastructure @pulumi/pulumi @pulumi/kubernetes @pulumi/digitalocean
+```
+
+### 2. Create service configs
 
 ```typescript
-// infra/services/api.ts - App Platform (stateless)
-import type { ServiceConfig } from '@crossdelta/infrastructure'
-
-const config: ServiceConfig = {
-  name: 'api',
-  httpPort: 4000,
-  ingressPrefix: '/api',
-  instanceSizeSlug: 'apps-s-1vcpu-0.5gb',
+// infra/services/orders.ts
+import { ports, type K8sServiceConfig } from '@crossdelta/infrastructure'
+
+const config: K8sServiceConfig = {
+  name: 'orders',
+  ports: ports().http(4001).build(),
+  replicas: 1,
+  healthCheck: { httpPath: '/health' },
+  resources: {
+    requests: { cpu: '50m', memory: '64Mi' },
+    limits: { cpu: '150m', memory: '128Mi' },
+  },
 }
 
 export default config
 ```
 
 ```typescript
-// infra/services/nats.ts - Droplet (stateful with persistence)
-import { dockerHubImage, type ServiceConfig } from '@crossdelta/infrastructure'
-import { readFileSync } from 'node:fs'
-
-const config: ServiceConfig = {
-  name: 'nats',
-  platform: 'droplet',
-  internalPorts: [4222, 8222],
-  internalUrl: 'nats://nats:4222',
-  image: dockerHubImage('nats', '2.10-alpine'),
-  runCommand: '-c /etc/nats/nats.conf',
-  droplet: {
-    size: 's-1vcpu-1gb',
-    volumes: [{ name: 'nats-data', mountPath: '/data', sizeGb: 10 }],
-    vpcPorts: [4222, 8222],
-    configFile: {
-      containerPath: '/etc/nats/nats.conf',
-      content: readFileSync('path/to/nats.conf', 'utf-8'),
-    },
+// infra/services/api-gateway.ts - Public service with ingress
+import { ports, type K8sServiceConfig } from '@crossdelta/infrastructure'
+
+const config: K8sServiceConfig = {
+  name: 'api-gateway',
+  ports: ports().http(4000).public().build(),
+  ingress: {
+    path: '/api',
+    host: 'api.example.com',
   },
+  replicas: 2,
+  healthCheck: { httpPath: '/health' },
 }
 
 export default config
 ```
 
-### 2. Create your Pulumi entry point
+### 3. Create your Pulumi infrastructure
 
 ```typescript
 // infra/index.ts
 import {
-  buildServices,
-  buildIngressRules,
-  buildServiceUrlEnvs,
-  buildServicePortEnvs,
-  buildDropletServices,
-  filterByPlatform,
-  discoverServices,
+  createDOKSCluster,
+  createNamespace,
+  createVPC,
+  deployK8sServices,
+  deployRuntime,
+  discoverServiceConfigs,
 } from '@crossdelta/infrastructure'
-import { App, Vpc } from '@pulumi/digitalocean'
 
 const region = 'fra1'
-const serviceConfigs = discoverServices('services')
-
-// Split services by platform
-const { appPlatformServices, dropletServices } = filterByPlatform(serviceConfigs)
+const namespace = 'my-platform'
 
-// Create VPC for private networking
-const vpc = new Vpc('platform-vpc', {
-  name: 'platform-vpc',
+// 1. Create VPC for private networking
+const vpc = createVPC({
+  name: `${namespace}-vpc`,
   region,
-  ipRange: '10.10.10.0/24',
+  description: 'VPC for platform internal communication',
 })
 
-// Deploy Droplet services (stateful)
-const dropletResources = buildDropletServices({
-  serviceConfigs: dropletServices,
+// 2. Create Kubernetes cluster
+const { cluster, provider, kubeconfig } = createDOKSCluster({
+  name: `${namespace}-cluster`,
   region,
   vpcUuid: vpc.id,
-  projectName: 'my-platform',
+  nodePool: {
+    name: 'default',
+    size: 's-2vcpu-4gb',
+    nodeCount: 2,
+  },
+})
+
+// 3. Create namespace
+createNamespace(provider, namespace)
+
+// 4. Deploy runtime components (NATS, Ingress, Cert-Manager)
+const runtime = deployRuntime(provider, namespace, {
+  nats: {
+    enabled: true,
+    config: {
+      replicas: 1,
+      jetstream: {
+        enabled: true,
+        storageSize: '1Gi',
+      },
+    },
+  },
+  ingress: {
+    enabled: true,
+    config: { replicas: 1 },
+  },
+  certManager: {
+    enabled: true,
+    config: { email: 'admin@example.com' },
+  },
 })
 
-// Get env vars for Droplet service URLs
-const dropletServiceEnvs = dropletResources.flatMap(r => [
-  { key: `${r.serviceName.toUpperCase()}_URL`, value: r.internalUrl },
-  { key: `${r.serviceName.toUpperCase()}_HOST`, value: r.privateIp },
-])
-
-// Deploy App Platform services (stateless)
-const app = new App('my-app', {
-  spec: {
-    name: 'my-platform',
-    region: region.replace(/\d+$/, ''), // 'fra1' -> 'fra'
-    envs: [
-      ...buildServiceUrlEnvs(appPlatformServices),
-      ...buildServicePortEnvs(appPlatformServices),
-      ...dropletServiceEnvs,
-    ],
-    services: buildServices({ serviceConfigs: appPlatformServices }),
-    ingress: { rules: buildIngressRules(appPlatformServices) },
+// 5. Auto-discover and deploy services
+const serviceConfigs = discoverServiceConfigs('services')
+const deployedServices = deployK8sServices({
+  provider,
+  namespace,
+  serviceConfigs,
+  env: {
+    NATS_URL: runtime.natsUrl,
   },
 })
+
+// Export outputs
+export const clusterEndpoint = cluster.endpoint
+export const clusterKubeconfig = kubeconfig
+export const natsInternalUrl = runtime.natsUrl
+export const loadBalancerIP = runtime.loadBalancerIp
 ```
 
-## ServiceConfig API
+## K8sServiceConfig API
 
-The `ServiceConfig` type is the central configuration for all services:
+The `K8sServiceConfig` type is the central configuration for Kubernetes services:
 
 ```typescript
-type ServiceConfig = {
-  /** Unique name of the service (required) */
+interface K8sServiceConfig {
+  /** Service name (used for deployment, service, ingress names) */
   name: string
   
-  /** Deployment platform: 'app-platform' (default) or 'droplet' */
-  platform?: 'app-platform' | 'droplet'
-  
-  /** Public HTTP port with ingress routing (requires ingressPrefix) */
-  httpPort?: number
-  
-  /** Internal-only ports, not publicly accessible */
-  internalPorts?: number[]
+  /** Port configuration (use fluent ports() builder) */
+  ports: PortConfig
   
-  /** Ingress path prefix for public routing (e.g., '/api') */
-  ingressPrefix?: string
+  /** Number of pod replicas (default: 1) */
+  replicas?: number
   
-  /** Override internal URL (e.g., 'nats://nats:4222' for non-HTTP) */
-  internalUrl?: string
+  /** Resource requests and limits */
+  resources?: {
+    requests?: { cpu: string; memory: string }
+    limits?: { cpu: string; memory: string }
+  }
   
-  /** Exclude from deployment */
-  skip?: boolean
+  /** Health check configuration */
+  healthCheck?: {
+    httpPath: string           // HTTP endpoint (e.g., '/health')
+    initialDelaySeconds?: number // Wait before first check (default: 10)
+    periodSeconds?: number      // Check interval (default: 10)
+  }
   
-  /** Custom image configuration */
-  image?: {
-    registryType: 'DOCKER_HUB' | 'GHCR' | 'DOCR'
-    registry: string      // e.g., 'library', 'myorg'
-    repository: string    // e.g., 'nats', 'platform/api'
-    tag: string           // e.g., '2.10-alpine', 'latest'
+  /** Ingress configuration for public services */
+  ingress?: {
+    path: string    // URL path (e.g., '/api')
+    host?: string   // Domain (e.g., 'api.example.com')
   }
   
-  /** Command to run in the container */
-  runCommand?: string
+  /** Environment variables */
+  env?: Record<string, pulumi.Input<string>>
   
-  /** App Platform: instance size (e.g., 'apps-s-1vcpu-0.5gb') */
-  instanceSizeSlug?: string
+  /** Kubernetes secrets */
+  secrets?: Record<string, pulumi.Input<string>>
   
-  /** Droplet-specific configuration */
-  droplet?: {
-    /** Droplet size (e.g., 's-1vcpu-1gb') */
-    size: string
-    
-    /** Persistent volumes */
-    volumes?: Array<{
-      name: string        // Volume name (unique)
-      mountPath: string   // Path in container (e.g., '/data')
-      sizeGb: number      // Size in GB
-    }>
-    
-    /** Ports to open in VPC firewall */
-    vpcPorts?: number[]
-    
-    /** Additional Docker run arguments */
-    dockerArgs?: string
-    
-    /** Config file to mount into container */
-    configFile?: {
-      containerPath: string  // Path in container
-      content: string        // File content
-    }
-  }
+  /** Custom image (defaults to GHCR with auto-generated tag) */
+  image?: string
+  
+  /** Skip deployment */
+  skip?: boolean
 }
 ```
 
-## Service Configuration Examples
+### Fluent Ports API
 
-### Public Service (App Platform)
+Build port configurations with a fluent, chainable API:
 
 ```typescript
-const config: ServiceConfig = {
-  name: 'frontend',
-  httpPort: 3000,
-  ingressPrefix: '/',
-  instanceSizeSlug: 'apps-s-1vcpu-1gb',
-}
+import { ports } from '@crossdelta/infrastructure'
+
+// Simple HTTP service
+ports().http(4000).build()
+
+// Public HTTP service (exposed via ingress)
+ports().http(4000).public().build()
+
+// gRPC service
+ports().grpc(50051).build()
+
+// Multiple ports
+ports()
+  .http(4000)              // Primary port
+  .addHttp(8080, 'metrics').public()  // Additional public port
+  .add(9090, 'admin')      // Additional internal port
+  .build()
+
+// Custom protocol
+ports()
+  .primary(4222, 'client')
+  .protocol('TCP')
+  .add(8222, 'monitoring')
+  .build()
 ```
 
-### Internal Service (App Platform)
+**Port Builder Methods:**
+- `.http(port)` - HTTP primary port
+- `.https(port)` - HTTPS primary port
+- `.grpc(port)` - gRPC primary port
+- `.primary(port, name?)` - Custom primary port
+- `.add(port, name?, protocol?)` - Add additional port
+- `.addHttp(port, name?)` - Add HTTP additional port
+- `.addGrpc(port, name?)` - Add gRPC additional port
+- `.public()` - Mark last port as public (exposed via ingress)
+- `.protocol(type)` - Set protocol for last port
+- `.build()` - Build final config
+
+## Service Configuration Examples
+
+### Public HTTP Service with Ingress
 
 ```typescript
-const config: ServiceConfig = {
-  name: 'worker',
-  internalPorts: [4001],
-  instanceSizeSlug: 'apps-s-1vcpu-0.5gb',
+import { ports, type K8sServiceConfig } from '@crossdelta/infrastructure'
+
+const config: K8sServiceConfig = {
+  name: 'api-gateway',
+  ports: ports().http(4000).public().build(),
+  replicas: 2,
+  healthCheck: { httpPath: '/health' },
+  ingress: {
+    path: '/api',
+    host: 'api.example.com',
+  },
+  resources: {
+    requests: { cpu: '100m', memory: '128Mi' },
+    limits: { cpu: '500m', memory: '512Mi' },
+  },
 }
+
+export default config
 ```
 
-### Stateful Service with Persistence (Droplet)
+### Internal Service (Event Consumer)
 
 ```typescript
-import { dockerHubImage, type ServiceConfig } from '@crossdelta/infrastructure'
-
-const config: ServiceConfig = {
-  name: 'nats',
-  platform: 'droplet',
-  internalPorts: [4222, 8222],
-  internalUrl: 'nats://nats:4222',
-  image: dockerHubImage('nats', '2.10-alpine'),
-  runCommand: '-c /etc/nats/nats.conf',
-  droplet: {
-    size: 's-1vcpu-1gb',
-    volumes: [{ name: 'nats-data', mountPath: '/data', sizeGb: 10 }],
-    vpcPorts: [4222, 8222],
-    configFile: {
-      containerPath: '/etc/nats/nats.conf',
-      content: readFileSync('services/nats/nats.conf', 'utf-8'),
-    },
+import { ports, type K8sServiceConfig } from '@crossdelta/infrastructure'
+
+const config: K8sServiceConfig = {
+  name: 'notifications',
+  ports: ports().http(4002).build(),
+  replicas: 1,
+  healthCheck: { httpPath: '/health' },
+  resources: {
+    requests: { cpu: '50m', memory: '64Mi' },
+    limits: { cpu: '150m', memory: '128Mi' },
   },
 }
+
+export default config
 ```
 
-### Config File Sharing (Local + Production)
+### Service with Multiple Ports
 
-One of the key features is sharing configuration between local development and production:
+```typescript
+import { ports, type K8sServiceConfig } from '@crossdelta/infrastructure'
+
+const config: K8sServiceConfig = {
+  name: 'api-gateway',
+  ports: ports()
+    .http(4000)                      // Primary HTTP port
+    .addHttp(8080, 'metrics').public()  // Metrics endpoint (public)
+    .add(9090, 'admin')              // Admin endpoint (internal)
+    .build(),
+  replicas: 2,
+  healthCheck: { httpPath: '/health' },
+}
 
-```
-services/nats/
-├── nats.conf              # Shared config (used by both)
-└── scripts/
-    └── start-dev.sh       # Local dev script
+export default config
 ```
 
-**nats.conf** (shared):
-```conf
-server_name: my-nats-server
-listen: 0.0.0.0:4222
-http: 0.0.0.0:8222
+### gRPC Service
 
-jetstream {
-  store_dir: /data
-  max_mem: 1G
-  max_file: 10G
+```typescript
+import { ports, type K8sServiceConfig } from '@crossdelta/infrastructure'
+
+const config: K8sServiceConfig = {
+  name: 'grpc-service',
+  ports: ports().grpc(50051).build(),
+  replicas: 2,
+  healthCheck: {
+    httpPath: '/grpc.health.v1.Health/Check',
+    initialDelaySeconds: 15,
+  },
 }
-```
 
-**start-dev.sh** (local):
-```bash
-docker run -d --name nats \
-  -v "$(pwd)/nats.conf:/etc/nats/nats.conf:ro" \
-  -v "$(pwd)/.nats-data:/data" \
-  -p 4222:4222 -p 8222:8222 \
-  nats:2.10-alpine -c /etc/nats/nats.conf
+export default config
 ```
 
-**infra/services/nats.ts** (production):
+## deployRuntime() - Unified Runtime Components
+
+Deploy all runtime components (NATS, Ingress, Cert-Manager) with a single function:
+
 ```typescript
-droplet: {
-  configFile: {
-    containerPath: '/etc/nats/nats.conf',
-    content: readFileSync('services/nats/nats.conf', 'utf-8'),
+import { deployRuntime } from '@crossdelta/infrastructure'
+
+const runtime = deployRuntime(provider, namespace, {
+  // NATS with JetStream for event-driven messaging
+  nats: {
+    enabled: true,
+    config: {
+      replicas: 1,
+      jetstream: {
+        enabled: true,
+        storageSize: '1Gi',
+        storageClass: 'do-block-storage',
+      },
+      resources: {
+        requests: { cpu: '25m', memory: '64Mi' },
+        limits: { cpu: '100m', memory: '192Mi' },
+      },
+    },
+  },
+
+  // NGINX Ingress Controller for HTTP routing
+  ingress: {
+    enabled: true,
+    config: {
+      replicas: 1,
+      resources: {
+        requests: { cpu: '50m', memory: '64Mi' },
+        limits: { cpu: '100m', memory: '128Mi' },
+      },
+    },
   },
+
+  // Cert-Manager for automatic TLS certificates
+  certManager: {
+    enabled: true,
+    config: {
+      email: 'admin@example.com',
+      staging: false,  // Use Let's Encrypt production
+      resources: {
+        requests: { cpu: '10m', memory: '32Mi' },
+        limits: { cpu: '100m', memory: '128Mi' },
+      },
+    },
+  },
+})
+
+// Use runtime outputs
+console.log('NATS URL:', runtime.natsUrl)
+console.log('LoadBalancer IP:', runtime.loadBalancerIp)
+console.log('Cert-Manager Ready:', runtime.certManagerReady)
+```
+
+**Returns:**
+```typescript
+interface RuntimeDeploymentResult {
+  natsUrl?: pulumi.Output<string>        // NATS connection URL
+  loadBalancerIp?: pulumi.Output<string> // Ingress LoadBalancer IP
+  certManagerReady?: boolean              // Cert-Manager installed
 }
 ```
 
-→ Same config file, same behavior, different environments.
+## Environment Generation
 
-## CLI: generate-env
+Generate `.env.local` for local development from Pulumi config:
 
-Generate `.env.local` and service-specific `env.ts` files for local development.
+```bash
+# In your workspace root
+bun dev  # Automatically generates .env.local before starting services
+```
 
-### Setup
+**Generated `.env.local`:**
+```bash
+# Auto-generated from Pulumi config (DO NOT EDIT)
+ORDERS_PORT=4001
+NOTIFICATIONS_PORT=4002
+API_GATEWAY_PORT=4000
+STOREFRONT_PORT=3000
 
-Add a script to your workspace `package.json`:
+NATS_URL=nats://localhost:4222
+DATABASE_URL=postgresql://localhost:5432/mydb
+API_KEY=your-secret-key
+```
 
-```json
-{
-  "scripts": {
-    "generate-env": "turbo run generate-env --ui=stream"
-  }
+**Generated `infra/env.ts`:**
+```typescript
+// Auto-generated type-safe service names
+export type ServiceName = 'orders' | 'notifications' | 'api-gateway' | 'storefront'
+
+export function getServicePort(name: ServiceName, fallback?: number): number {
+  const port = process.env[`${name.toUpperCase().replace(/-/g, '_')}_PORT`]
+  return port ? Number.parseInt(port, 10) : (fallback ?? 8080)
 }
 ```
 
-### What it does
+## API Reference
 
-1. Loads secrets from Pulumi config (dev stack)
-2. Discovers services from `infra/services/*.ts`
-3. Generates `SERVICE_URL` and `SERVICE_PORT` env vars for localhost
-4. Writes `.env.local` to your workspace root
-5. Generates `infra/env.ts` with type-safe `ServiceName` union type
-6. Generates `services/*/src/env.ts` for each service (Docker-compatible)
+### Core Functions
 
-### Example output
+| Function | Description |
+|----------|-------------|
+| `deployRuntime(provider, namespace, config)` | Deploy runtime components (NATS, Ingress, Cert-Manager) |
+| `discoverServiceConfigs(dir, options?)` | Auto-discover K8s service configs from directory |
+| `deployK8sServices(options)` | Deploy services to Kubernetes cluster |
+| `createDOKSCluster(config)` | Create DigitalOcean Kubernetes cluster |
+| `createVPC(config)` | Create VPC for private networking |
+| `createNamespace(provider, name, labels?)` | Create Kubernetes namespace |
+| `createImagePullSecret(provider, namespace, name, config)` | Create secret for private registries |
 
-`.env.local`:
-```bash
-# Service URLs (localhost for local development)
-API_URL=http://localhost:4000
-FRONTEND_URL=http://localhost:3000
-NATS_URL=nats://localhost:4222
+### Port Configuration
 
-# Service Ports
-API_PORT=4000
-FRONTEND_PORT=3000
+| Function | Description |
+|----------|-------------|
+| `ports()` | Start fluent port builder |
+| `.http(port)` | Set HTTP primary port |
+| `.https(port)` | Set HTTPS primary port |
+| `.grpc(port)` | Set gRPC primary port |
+| `.primary(port, name?)` | Set custom primary port |
+| `.add(port, name?, protocol?)` | Add additional port |
+| `.addHttp(port, name?)` | Add HTTP additional port |
+| `.addGrpc(port, name?)` | Add gRPC additional port |
+| `.public()` | Mark last port as public (ingress) |
+| `.protocol(type)` | Set protocol ('TCP', 'UDP', 'SCTP') |
+| `.build()` | Build final port configuration |
+
+### Service Discovery Options
+
+```typescript
+discoverServiceConfigs('services', {
+  filter?: RegExp | string,          // Filter by service name pattern
+  include?: string[],                // Whitelist specific services
+  exclude?: string[],                // Blacklist specific services
+  tags?: string[],                   // Filter by tags
+  env?: Record<string, string>,      // Inject env vars
+  validate?: boolean,                // Validate configs (default: true)
+  sort?: boolean,                    // Sort by name (default: true)
+})
 ```
 
-## Runtime Helpers
+### Kubernetes Deployment Options
 
-Use `@crossdelta/infrastructure/env` in your services to read environment configuration:
+```typescript
+deployK8sServices({
+  provider: k8s.Provider,            // Kubernetes provider
+  namespace: string,                 // Target namespace
+  serviceConfigs: K8sServiceConfig[], // Service configurations
+  env?: Record<string, pulumi.Input<string>>, // Global env vars
+  secrets?: Record<string, pulumi.Input<string>>, // Global secrets
+  imagePullSecrets?: string[],       // Image pull secret names
+  registry?: string,                 // Override registry URL
+})
+```
 
+Returns a Map:
 ```typescript
-import { getServicePort, getServiceUrl } from '@crossdelta/infrastructure/env'
+Map<string, {
+  deployment: k8s.apps.v1.Deployment,  // Kubernetes Deployment
+  service: k8s.core.v1.Service,         // Kubernetes Service
+  ingress?: k8s.networking.v1.Ingress,  // Ingress (if public)
+  internalUrl: pulumi.Output<string>,   // Internal service URL
+}>
+```
 
-// Get port from WORKER_PORT env var (fallback: 8080)
-const port = getServicePort('worker', 8080)
+### Environment Helpers (`@crossdelta/infrastructure/env`)
+
+```typescript
+import { getServicePort } from '@crossdelta/infrastructure/env'
 
-// Get URL from WORKER_URL env var
-const url = getServiceUrl('worker')
+// Read SERVICE_NAME_PORT from environment
+const port = getServicePort('orders', 4001)  // Fallback to 4001
 ```
 
-These helpers work both locally (via `.env.local`) and in production (via DO App Platform env injection).
+## Cost Estimation (DOKS)
 
-## API Reference
+### Basic Setup
+- **DOKS Cluster**: $12/month (control plane)
+- **Worker Nodes**: 2× s-2vcpu-4gb = $36/month
+- **Load Balancer**: $12/month (managed by DOKS)
+- **Block Storage**: 10GB for NATS JetStream = $1/month
+- **Total**: ~$61/month
 
-### Main Export (`@crossdelta/infrastructure`)
+### Production Setup
+- **DOKS Cluster**: $12/month
+- **Worker Nodes**: 3× s-2vcpu-4gb = $54/month (HA)
+- **Load Balancer**: $12/month
+- **Block Storage**: 50GB = $5/month
+- **Total**: ~$83/month
 
-| Function | Description |
-|----------|-------------|
-| `discoverServices(dir)` | Auto-discover service configs from directory |
-| `buildServices(options)` | Build App Platform service specs |
-| `buildIngressRules(configs)` | Generate ingress rules for public services |
-| `buildServiceUrlEnvs(configs)` | Create SERVICE_NAME_URL env vars |
-| `buildServicePortEnvs(configs)` | Create SERVICE_NAME_PORT env vars |
-| `buildLocalUrls(configs)` | Generate localhost URLs for local dev |
-| `filterByPlatform(configs)` | Split configs into App Platform and Droplet services |
-| `buildDropletServices(options)` | Create Droplet resources with volumes and firewall |
-| `dockerHubImage(repo, tag, registry?)` | Create Docker Hub image config (defaults to `library`) |
-
-### Droplet Builder Options
+### Scaling Considerations
 
-```typescript
-buildDropletServices({
-  serviceConfigs: ServiceConfig[]  // Services with platform: 'droplet'
-  region: string                   // DO region (e.g., 'fra1')
-  vpcUuid: pulumi.Output<string>   // VPC ID for private networking
-  projectName: string              // Prefix for resource names
-})
+| Workload | Node Size | Monthly Cost |
+|----------|-----------|--------------|
+| Development | 1× s-2vcpu-4gb | $12 + $18 = $30/mo |
+| Staging | 2× s-2vcpu-4gb | $12 + $36 = $48/mo |
+| Production | 3× s-4vcpu-8gb | $12 + $144 = $156/mo |
+| High Traffic | 5× s-4vcpu-8gb | $12 + $240 = $252/mo |
+
+**Benefits of Kubernetes:**
+- **Auto-scaling**: HPA automatically adjusts pod count
+- **Self-healing**: Failed pods restart automatically
+- **Rolling updates**: Zero-downtime deployments
+- **Resource efficiency**: Better node utilization vs. dedicated VMs
+
+## Adding New Providers
+
+The library is designed to be **provider-agnostic**. To add support for a new cloud provider (AWS EKS, Azure AKS, GKE):
+
+### 1. Implement Provider-Specific Runtime Components
+
+Create a new directory under `lib/runtimes/`:
+
+```
+lib/runtimes/
+├── doks/          # DigitalOcean Kubernetes (reference implementation)
+│   ├── nats.ts
+│   ├── ingress.ts
+│   └── cert-manager.ts
+└── eks/           # Your new provider
+    ├── nats.ts
+    ├── ingress.ts
+    └── cert-manager.ts
 ```
 
-Returns an array of:
+### 2. Follow the Interface Pattern
+
+Each component should export a deployment function:
+
 ```typescript
-{
-  serviceName: string              // Service name
-  droplet: digitalocean.Droplet    // Created Droplet resource
-  privateIp: pulumi.Output<string> // Private IP in VPC
-  internalUrl: string              // URL for service discovery
+// lib/runtimes/eks/nats.ts
+export function deployNats(
+  provider: k8s.Provider,
+  namespace: string,
+  config: NatsConfig
+): NatsDeploymentResult {
+  // Provider-specific NATS deployment
+  // Use Helm, manifests, or provider-specific resources
+  
+  return {
+    release,
+    internalUrl: `nats://nats.${namespace}.svc.cluster.local:4222`,
+    serviceDns: `nats.${namespace}.svc.cluster.local`,
+  }
 }
 ```
 
-### Env Export (`@crossdelta/infrastructure/env`)
+### 3. Update deployRuntime()
 
-| Function | Description |
-|----------|-------------|
-| `getServicePort(name, default)` | Read SERVICE_NAME_PORT from env |
-| `getServiceUrl(name)` | Read SERVICE_NAME_URL from env |
-
-## MVP Limitations & Future Improvements
+Add your provider to `lib/core/runtime.ts`:
 
-This architecture is designed for MVP/Beta deployments:
+```typescript
+// Deploy NATS if enabled
+if (config.nats?.enabled) {
+  if (providerName === 'doks') {
+    const nats = deployNats(provider, namespace, config.nats.config || {})
+    result.natsUrl = pulumi.output(nats.internalUrl)
+  } else if (providerName === 'eks') {
+    const { deployNats } = require('../runtimes/eks/nats')
+    const nats = deployNats(provider, namespace, config.nats.config || {})
+    result.natsUrl = pulumi.output(nats.internalUrl)
+  }
+}
+```
 
-| Current (MVP) | Future (Production) |
-|---------------|---------------------|
-| Single NATS Droplet | NATS Cluster (3 nodes) or Synadia Cloud |
-| No auto-healing | Kubernetes or managed service |
-| Manual scaling | Auto-scaling policies |
-| Basic monitoring | Prometheus/Grafana stack |
+### 4. Service Configs Remain Portable
 
-**Cost estimate (MVP)**:
-- App Platform: ~$12-24/month (depending on instance sizes)
-- NATS Droplet: ~$6/month (s-1vcpu-1gb)
-- Volume: ~$1/month (10GB)
-- **Total**: ~$19-31/month
+Service configurations (`K8sServiceConfig`) work across all providers without changes. Only runtime components need provider-specific implementations.
 
 ## License