@maestro-js/aws-cdk-recipes 1.0.0-alpha.23 → 1.0.0-alpha.25

package/README.md

@@ -27,18 +27,75 @@ Package dependencies:
 ## Available Constructs
 
 ### Vpc
-Multi-AZ VPC with public and private subnets, configurable NAT strategy (none, single, onePerAz, ec2), optional WireGuard VPN, and VPC Flow Logs.
+Multi-AZ VPC with public and private subnets, configurable NAT strategy (none, single, onePerAz, ec2), an optional VPN (self-hosted WireGuard or Tailscale), and VPC Flow Logs.
 
 ```ts
 const network = new Vpc(this, 'Network', {
   natGateways: 'single',
-  wireguard: true
+  vpn: { type: 'tailscale', auth: { method: 'authKey' } }
 })
 ```
 
-Key props: `cidr`, `maxAzs`, `natGateways`, `subnetConfiguration`, `wireguard`, `flowLogs`.
+Key props: `cidr`, `maxAzs`, `natGateways`, `subnetConfiguration`, `vpn`, `flowLogs`.
 
-Exposes: `vpc`, `publicSubnets`, `privateSubnets`, `securityGroup`, `wireguard`, `wireguardPublicKeyParam`.
+Exposes: `vpc`, `publicSubnets`, `privateSubnets`, `securityGroup`, `wireguard`, `wireguardPublicKeyParam`, `tailscale`, `tailscaleRoutes`.
+
+#### VPN: WireGuard vs Tailscale
+
+`vpn` selects the backend: `{ type: 'wireguard' }` or `{ type: 'tailscale', auth: ... }`. Omit it for no VPN.
+
+- **WireGuard** — a self-hosted server in a public subnet with an Elastic IP and inbound UDP 51820. Server keys and peer config persist in SSM; provision clients with `maestro aws:make-wireguard-client`.
+- **Tailscale** — a subnet router that joins your tailnet **outbound-only** (no public ingress, no Elastic IP) and advertises the VPC CIDR so tailnet members can reach private resources. Clients onboard themselves with `tailscale up` — there's no per-client CLI.
+
+Either way the VPN node carries the VPC's `securityGroup`, so you grant it access to private resources the same way:
+
+```ts
+db.connections.allowDefaultPortFrom(network.securityGroup, 'VPN access')
+```
+
+#### Tailscale setup
+
+1. **Create the auth secret in SSM** (one-time, out-of-band). CloudFormation can't create `SecureString` parameters, so the construct only *reads* a pre-existing one:
+
+   ```bash
+   # Auth key (tskey-auth-...), short-lived; or OAuth client secret (tskey-client-...), long-lived
+   aws ssm put-parameter --name /tailscale/Network/auth-key --type SecureString --value tskey-auth-...
+   ```
+
+   The default param name is `/tailscale/<id>/auth-key` (authKey) or `/tailscale/<id>/oauth-secret` (oauth); override with `tailscale.auth.param`.
+
+2. **Choose an auth method.** Supplying `tags` registers the node under the `tagged-devices` system user (rather than the human who minted the credential), which also disables key expiry on the node:
+
+   - **`authKey`** (`tskey-auth-...`) — short-lived. Set `auth.tags` to advertise tags; the SSM key should itself be created as a tagged key. Without tags the node registers personally-owned and inherits the tailnet's key expiry.
+   - **`oauth`** (`tskey-client-...`) — long-lived and mints ephemeral keys on demand (so it survives instance replacement without key rotation); `tags` is **required**.
+
+   ```ts
+   new Vpc(this, 'Network', {
+     vpn: {
+       type: 'tailscale',
+       auth: { method: 'oauth', tags: ['tag:subnet-router'] },
+       advertiseRoutes: ['10.0.0.0/16'], // defaults to the VPC CIDR
+       exitNode: false,                  // also route clients' internet traffic out AWS
+       ephemeral: true,                  // auto-remove from tailnet when offline
+       placement: 'public'               // 'private' requires natGateways !== 'none'
+     }
+   })
+   ```
+
+3. **Approve the advertised routes.** Advertising a route doesn't make it usable — approve it once in the admin console, or auto-approve via your tailnet ACL policy:
+
+   ```jsonc
+   // tailnet ACL policy
+   "autoApprovers": {
+     "routes": {
+       "10.0.0.0/16": ["tag:subnet-router"]
+     }
+   }
+   ```
+
+   The construct emits a `TailscaleRouteApproval` CfnOutput naming the exact routes and tag to approve.
+
+4. **Onboard clients** with the standard Tailscale flow (`tailscale up` on each device); the control plane handles IP assignment, key exchange, and ACL-based access.
 
 ### Cluster
 ECS cluster inside a VPC with optional Fargate capacity providers for Spot pricing.
@@ -137,7 +194,9 @@ new EcsFargateService(this, 'Api', {
 })
 ```
 
-Key props: `cluster`, `architecture`, `cpu`, `memoryLimitMiB`, `containers` (array with `name`, `image`, `port`, `environment`, `ssm`, `secrets`, `health`, `logging`), `loadBalancer` (with `domain`, `health`, `rules`), `scaling`, `capacity` (`'spot'` or mixed), `permissions`, `transform`.
+Key props: `cluster`, `architecture`, `cpu`, `memoryLimitMiB`, `ephemeralStorageGiB`, `desiredCount`, `volumes`, `containers` (array with `name`, `image`, `port`, `command`, `workingDirectory`, `essential`, `mountPoints`, `dependsOn`, `environment`, `ssm`, `secrets`, `health`, `logging`), `loadBalancer` (with `domain`, `health`, `healthCheckGracePeriodSeconds`, `rules`), `scaling`, `capacity` (`'spot'` or mixed), `permissions`, `transform`.
+
+Sidecar/init-container primitives: declare task-scoped `volumes`, mount them per container via `mountPoints`, and order startup with `dependsOn` (`'start' | 'complete' | 'success' | 'healthy'`). Mark short-lived init containers `essential: false`.
 
 Exposes: `service`, `taskDefinition`, `containers`, `logGroups`, `securityGroup`, `alb`, `listener`, `targetGroups`.
 
@@ -199,6 +258,27 @@ Key props: `cluster`, `path`, `buildDirectory`, `image`, `port`, `environment`,
 
 Exposes: `bucket`, `distribution`, `ecsService`.
 
+### ArtifactEcsFargateService
+Framework-agnostic Fargate service that runs an application **artifact downloaded at boot** instead of a baked image — so a new version ships **without a Docker build or `cdk deploy`**. A single container runs a boot-time Node bootstrap that downloads the tarball from S3 (SigV4 with the task role's credentials), verifies its SHA-256, and extracts it to `/app`, then `exec`s the app in place — no init sidecar, no shared volume.
+
+CDK owns the durable infrastructure (ALB, roles, buckets, CloudFront, autoscaling, the service, and a single bootstrap task definition); CI owns every subsequent task-def revision. On `cdk deploy` the service comes up on a sentinel artifact key with no pinned `DesiredCount` — its create-time task serves a healthy placeholder (200 on the health path, 503 elsewhere) so the stack reaches a healthy state without running the real app. The app comes alive on the first CI deploy. See [docs/artifact-deploy-runbook.md](docs/artifact-deploy-runbook.md) for the deploy / promote / rollback procedure.
+
+```ts
+// React Router SSR app — command points at the artifact's react-router-serve binary.
+new ArtifactEcsFargateService(this, 'App', {
+  app: 'my-app',
+  cluster: cluster.cluster,
+  command: ['./node_modules/.bin/react-router-serve', './build/server/index.js'],
+  environment: { ENV_NAME: 'production' },
+  ssm: { MAESTRO_ENV_ENCRYPTION_KEY: '/my-app/production/env-key' },
+  domain: { name: 'app.example.com', certificateArn: '...' }
+})
+```
+
+Key props: `app`, `cluster`, `command`, `port`, `architecture`, `cpu`, `memoryLimitMiB`, `ephemeralStorageGiB`, `runtimeImage`, `mountPath`, `workingDirectory`, `environment` (set `ENV_NAME` here), `ssm`, `secrets`, `artifact` (`bucket` for cross-account), `cdn`, `assets` (`lifecycleDays`, `behaviors`), `domain`, `edge`, `loadBalancer`, `healthCheck` (with `gracePeriodSeconds`), `scaling`, `permissions`, `discovery` (`namespace`), `taskFamily`, `s3GatewayEndpoint`, `logging`, `transform`.
+
+Exposes: `ecsService`, `artifactBucket`, `assetBucket`, `distribution`, `deployPolicy` (managed policy to attach to your CI principal), `taskFamily`. Writes discovery values to SSM under `/maestro/<app>/{region,cluster,service,task-family,artifact-bucket,asset-bucket}`.
+
 ### ReactRouterEcrImage
 Builds a Docker image for a React Router app and pushes it to ECR. Auto-generates a Dockerfile when none is provided. Use to pre-build an image shared across multiple ECS services.
 
@@ -226,6 +306,7 @@ export { Cluster } from './cluster.ts'
 export { StaticSite } from './static-site.ts'
 export { ReactRouterSsrSiteLambda } from './react-router-ssr-site-lambda.ts'
 export { ReactRouterSsrSiteEcsFargateService } from './react-router-ssr-site-ecs-fargate-service.ts'
+export { ArtifactEcsFargateService } from './artifact-ecs-fargate-service.ts'
 export { ReactRouterEcrImage } from './react-router-ecr-image.ts'
 export { MySqlDatabase } from './mysql-database.ts'
 export { AuroraDatabase } from './aurora-database.ts'
@@ -247,6 +328,7 @@ export { EcsFargateService } from './ecs-fargate-service.ts'
 | `StaticSite` | `new StaticSite(scope, id, props: StaticSite.Props)` |
 | `ReactRouterSsrSiteLambda` | `new ReactRouterSsrSiteLambda(scope, id, props: ReactRouterSsrSiteLambda.Props)` |
 | `ReactRouterSsrSiteEcsFargateService` | `new ReactRouterSsrSiteEcsFargateService(scope, id, props: ReactRouterSsrSiteEcsFargateService.Props)` |
+| `ArtifactEcsFargateService` | `new ArtifactEcsFargateService(scope, id, props: ArtifactEcsFargateService.Props)` |
 | `ReactRouterEcrImage` | `new ReactRouterEcrImage(scope, id, props?: ReactRouterEcrImage.Props)` |
 
 ## Common Patterns
@@ -311,6 +393,29 @@ new ReactRouterSsrSiteEcsFargateService(this, 'App', {
 })
 ```
 
+### Download-on-boot deploys without `cdk deploy`
+
+Ship new app versions by uploading an artifact and rolling the service — no Docker build, no CDK run.
+CDK provisions the durable infrastructure once; CI owns subsequent task-def revisions.
+
+```ts
+const app = new ArtifactEcsFargateService(this, 'App', {
+  app: 'my-app',
+  cluster: cluster.cluster,
+  command: ['./node_modules/.bin/react-router-serve', './build/server/index.js'],
+  environment: { ENV_NAME: 'production' },
+  ssm: { MAESTRO_ENV_ENCRYPTION_KEY: '/my-app/production/env-key' },
+  domain: { name: 'app.example.com', certificateArn: '...' }
+})
+
+// Attach the emitted, tightly-scoped policy to your CI OIDC principal.
+ciPrincipal.addManagedPolicy(app.deployPolicy)
+```
+
+After `cdk deploy`, CI discovers its targets from SSM and runs the deploy flow in
+[docs/artifact-deploy-runbook.md](docs/artifact-deploy-runbook.md). Rollback is one call to a prior
+task-def revision.
+
 ### Transform escape hatch for customizing underlying CDK props
 
 Every construct supports a `transform` prop that receives default CDK props and returns modified versions:
@@ -359,7 +464,7 @@ Values starting with `arn:aws:secretsmanager:` are resolved as Secrets Manager s
 const network = new Vpc(this, 'Network', {
   natGateways: 'ec2',
   maxAzs: 2,
-  wireguard: true,
+  vpn: { type: 'wireguard' },
   flowLogs: { retention: RetentionDays.ONE_WEEK }
 })
 ```
@@ -383,7 +488,9 @@ The `'ec2'` NAT option uses a `t4g.nano` instance running the fck-nat AMI (~$3/m
 - `packages/aws-cdk-recipes/src/static-site.ts` - StaticSite construct
 - `packages/aws-cdk-recipes/src/react-router-ssr-site-lambda.ts` - ReactRouterSsrSiteLambda construct
 - `packages/aws-cdk-recipes/src/react-router-ssr-site-ecs-fargate-service.ts` - ReactRouterSsrSiteEcsFargateService construct
+- `packages/aws-cdk-recipes/src/artifact-ecs-fargate-service.ts` - ArtifactEcsFargateService construct (download-on-boot deploys)
 - `packages/aws-cdk-recipes/src/react-router-ecr-image.ts` - ReactRouterEcrImage construct
+- `packages/aws-cdk-recipes/docs/artifact-deploy-runbook.md` - Artifact deploy / promote / rollback runbook
 - `packages/aws-cdk-recipes/src/helpers/cloudfront.ts` - Shared CloudFront/S3 deployment helpers
 - `packages/aws-cdk-recipes/src/helpers/ecs.ts` - Shared ECS helpers (log retention, secrets)
 - `packages/aws-cdk-recipes/src/helpers/docker.ts` - React Router Dockerfile generation