container-superposition 0.1.7 → 0.1.9

package/overlays/k3d/README.md

@@ -0,0 +1,201 @@
+# k3d Overlay
+
+Installs [k3d](https://k3d.io), a lightweight wrapper that runs [k3s](https://k3s.io) (Rancher's minimal Kubernetes distribution) in Docker containers, enabling fast local Kubernetes clusters for development.
+
+> **Note:** This overlay conflicts with `kind` because both tools create local Kubernetes clusters using Docker containers. Choose `k3d` for faster startup and lower resource usage, or `kind` for full Kubernetes conformance.
+
+## Features
+
+- **k3d CLI** — Create, manage, and delete local k3s clusters from the terminal
+- **Fast cluster startup** — Clusters spin up in seconds, compared to heavier alternatives
+- **Low resource usage** — k3s has a smaller memory and CPU footprint than full Kubernetes
+- **Multi-node clusters** — Simulate multi-node topologies with server and agent nodes
+- **Load balancer included** — Built-in k3s service load balancer for `LoadBalancer` services
+- **Port and volume mapping** — Map host ports and directories into the cluster easily
+
+## How It Works
+
+k3d is installed as a static binary in the devcontainer during `setup.sh`. It requires Docker (provided by the `docker-in-docker` dependency) to create k3s nodes as Docker containers.
+
+**Dependencies:**
+
+- `docker-in-docker` (required) — Provides the Docker daemon that k3d uses to launch k3s nodes
+
+**Suggested overlays:**
+
+- `kubectl-helm` — Kubernetes CLI and Helm for interacting with k3d clusters
+
+## Installation
+
+k3d is installed automatically during devcontainer creation via `setup.sh`:
+
+- Downloads the k3d binary for your architecture (amd64/arm64)
+- Installs to `/usr/local/bin/k3d`
+- Verifies Docker access
+
+## Common Commands
+
+### Cluster Management
+
+```bash
+# Create a single-node cluster (control plane + agent in one node)
+k3d cluster create dev
+
+# Create a cluster with multiple agents
+k3d cluster create dev --agents 2
+
+# Create with a specific k3s version
+k3d cluster create dev --image rancher/k3s:v1.30.0-k3s1
+
+# Create with port mapping (host 8080 → cluster LoadBalancer 80)
+k3d cluster create dev -p "8080:80@loadbalancer"
+
+# List all clusters
+k3d cluster list
+
+# Start/stop a cluster
+k3d cluster start dev
+k3d cluster stop dev
+
+# Delete a cluster
+k3d cluster delete dev
+```
+
+### Working with Clusters
+
+```bash
+# Merge k3d kubeconfig into default kubeconfig
+k3d kubeconfig merge dev --kubeconfig-merge-default
+
+# Get kubeconfig for a specific cluster
+k3d kubeconfig get dev
+
+# Import a Docker image into the cluster (avoids registry push/pull)
+docker build -t myapp:dev .
+k3d image import myapp:dev --cluster dev
+```
+
+### kubectl Integration
+
+```bash
+# Use kubectl with the k3d cluster
+kubectl cluster-info --context k3d-dev
+
+# Deploy a workload
+kubectl create deployment nginx --image=nginx
+kubectl expose deployment nginx --port=80 --type=LoadBalancer
+
+# Port-forward for direct access
+kubectl port-forward service/nginx 8080:80
+```
+
+## Configuration
+
+### Multi-Node Cluster
+
+```bash
+k3d cluster create dev \
+  --servers 1 \
+  --agents 3 \
+  --k3s-arg "--disable=traefik@server:*"
+```
+
+### Volume Mounts
+
+```bash
+# Mount a local directory into all nodes
+k3d cluster create dev \
+  --volume "${PWD}:/app@all"
+```
+
+### Port Mapping
+
+```bash
+# Expose ports 80 and 443 through the cluster load balancer
+k3d cluster create dev \
+  -p "80:80@loadbalancer" \
+  -p "443:443@loadbalancer"
+```
+
+## Benefits vs kind
+
+| Feature               | k3d (this overlay)          | kind                         |
+| --------------------- | --------------------------- | ---------------------------- |
+| **Distribution**      | k3s (lightweight variant)   | ✅ Full Kubernetes           |
+| **Startup speed**     | ✅ Faster (~15–30 s)        | Moderate (~30–60 s)          |
+| **Resource usage**    | ✅ Lower (~256 MB RAM/node) | Higher (~512 MB+ RAM/node)   |
+| **Conformance**       | High (not 100%)             | ✅ 100% CNCF conformant      |
+| **Port mapping**      | ✅ Built-in load balancer   | Manual NodePort/port-forward |
+| **Production parity** | Sufficient for most apps    | ✅ Identical to production   |
+
+**Choose k3d when:**
+
+- Fast iteration cycles are more important than 100% conformance
+- System resources are limited
+- You want built-in load balancer for easy port mapping
+
+**Choose kind when:**
+
+- You need guaranteed Kubernetes API compatibility
+- Developing Kubernetes operators or controllers
+- Testing for production environments
+
+## Use Cases
+
+- **Rapid Kubernetes development** — Fast cluster creation and teardown for iterative development
+- **Helm chart testing** — Deploy and test Helm charts locally before pushing
+- **CI/CD prototyping** — Simulate cluster deployments in low-resource environments
+- **Multi-node testing** — Test workloads across multiple nodes on a single machine
+- **Learning Kubernetes** — Explore Kubernetes concepts with minimal overhead
+
+**Integrates well with:**
+
+- `kubectl-helm` — Kubernetes CLI and Helm package manager
+- `tilt` — Live reload for Kubernetes workloads
+- `skaffold` — Build/deploy automation for Kubernetes
+- `terraform` — IaC for cluster configuration
+
+## Troubleshooting
+
+### Cluster Creation Fails
+
+```bash
+# Ensure Docker daemon is running
+docker info
+
+# Check Docker has sufficient resources
+docker system df
+```
+
+### `kubectl` Cannot Connect
+
+```bash
+# Ensure kubeconfig is merged
+k3d kubeconfig merge dev --kubeconfig-merge-default
+
+# Verify cluster is running
+k3d cluster list
+kubectl cluster-info --context k3d-dev
+```
+
+### Image Not Found in Cluster
+
+```bash
+# Import local images directly (avoids registry round-trip)
+k3d image import myapp:latest --cluster dev
+```
+
+## References
+
+- [k3d Documentation](https://k3d.io)
+- [k3d GitHub](https://github.com/k3d-io/k3d)
+- [k3s Documentation](https://docs.k3s.io)
+- [Kubernetes Documentation](https://kubernetes.io/docs/)
+
+**Related Overlays:**
+
+- `docker-in-docker` — Required: provides the Docker daemon for k3d
+- [`kubectl-helm`](../kubectl-helm/README.md) — Kubernetes CLI and Helm
+- [`kind`](../kind/README.md) — Full-conformance K8s alternative (conflicts)
+- [`tilt`](../tilt/README.md) — Live reload for Kubernetes development
+- [`skaffold`](../skaffold/README.md) — K8s build and deploy automation

package/overlays/k3d/devcontainer.patch.json

@@ -0,0 +1,9 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "curl",
+            "apk": "curl"
+        }
+    }
+}

package/overlays/k3d/overlay.yml

@@ -0,0 +1,19 @@
+id: k3d
+name: k3d
+description: Lightweight local Kubernetes clusters using k3s in Docker
+category: cloud
+supports: []
+requires:
+    - docker-in-docker
+suggests:
+    - kubectl-helm
+conflicts:
+    - kind
+tags:
+    - cloud
+    - kubernetes
+    - k8s
+    - k3d
+    - k3s
+    - testing
+ports: []

package/overlays/k3d/setup.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Setup script for k3d
+
+set -e
+
+echo "🔧 Setting up k3d..."
+
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
+detect_arch
+
+# Install k3d
+K3D_VERSION="${K3D_VERSION:-v5.7.4}"
+echo "📦 Installing k3d ${K3D_VERSION}..."
+
+install_binary \
+    "https://github.com/k3d-io/k3d/releases/download/${K3D_VERSION}/k3d-linux-${CS_ARCH}" \
+    "k3d"
+
+# Verify installation
+if command -v k3d &>/dev/null; then
+    echo "✅ k3d installed successfully"
+    k3d version
+else
+    echo "❌ k3d installation failed"
+    exit 1
+fi
+
+echo "✅ k3d setup complete"
+echo ""
+echo "ℹ️  To create a cluster, run:"
+echo "   k3d cluster create dev"

package/overlays/k3d/verify.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# Verification script for k3d overlay
+# Confirms k3d is installed
+
+set -e
+
+echo "🔍 Verifying k3d overlay..."
+echo ""
+
+# Check k3d is installed
+echo "1️⃣ Checking k3d installation..."
+if command -v k3d &>/dev/null; then
+    k3d version
+    echo "   ✅ k3d is installed"
+else
+    echo "   ❌ k3d is not installed"
+    exit 1
+fi
+
+# Check Docker is available (required for k3d)
+echo ""
+echo "2️⃣ Checking Docker availability..."
+if ! command -v docker &>/dev/null; then
+    echo "   ❌ Docker CLI not found"
+    exit 1
+fi
+if docker version --format '{{.Server.Version}}' &>/dev/null; then
+    echo "   ✅ Docker is available"
+else
+    echo "   ❌ Docker daemon not accessible"
+    exit 1
+fi
+
+echo ""
+echo "✅ k3d overlay verification complete"
+echo ""
+echo "ℹ️  To create a cluster, run:"
+echo "   k3d cluster create dev"

package/overlays/keycloak/devcontainer.patch.json

@@ -1,7 +1,6 @@
 {
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
     "runServices": ["keycloak"],
-    "_serviceOrder": 10,
     "forwardPorts": [8180],
     "portsAttributes": {
         "8180": {

package/overlays/keycloak/docker-compose.yml

@@ -32,3 +32,4 @@ services:
 
 networks:
     devnet:
+        name: devnet

package/overlays/keycloak/overlay.yml

@@ -8,6 +8,7 @@ requires:
     - postgres
 suggests: []
 conflicts: []
+serviceOrder: 2
 tags:
     - dev
     - auth
@@ -21,3 +22,17 @@ ports:
       description: Keycloak admin console and auth endpoints
       path: /
       onAutoForward: openBrowser
+parameters:
+    KEYCLOAK_VERSION:
+        description: Keycloak image version tag
+        default: '26.0'
+    KEYCLOAK_PORT:
+        description: Host port mapped to Keycloak HTTP (8180 inside container)
+        default: '8180'
+    KEYCLOAK_ADMIN:
+        description: Keycloak initial admin username
+        default: admin
+    KEYCLOAK_ADMIN_PASSWORD:
+        description: Keycloak initial admin password
+        default: admin
+        sensitive: true

package/overlays/localstack/docker-compose.yml

@@ -23,3 +23,4 @@ volumes:
 
 networks:
     devnet:
+        name: devnet

package/overlays/localstack/overlay.yml

@@ -7,7 +7,25 @@ supports:
 requires: []
 suggests:
     - aws-cli
-conflicts: []
+conflicts:
+    - minio
+serviceOrder: 0
+parameters:
+    LOCALSTACK_VERSION:
+        description: LocalStack image version tag
+        default: latest
+    LOCALSTACK_EDGE_PORT:
+        description: Host port mapped to LocalStack edge (4566 inside container)
+        default: '4566'
+    LOCALSTACK_S3_PORT:
+        description: Host port mapped to LocalStack S3 legacy endpoint (4571 inside container)
+        default: '4571'
+    LOCALSTACK_SERVICES:
+        description: Comma-separated list of AWS services to enable
+        default: s3,sqs,sns,dynamodb,lambda,cloudformation
+    LOCALSTACK_DEBUG:
+        description: Enable LocalStack debug logging (0 or 1)
+        default: '0'
 tags:
     - cloud
     - aws

package/overlays/loki/devcontainer.patch.json

@@ -1,7 +1,6 @@
 {
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
     "runServices": ["loki"],
-    "_serviceOrder": 1,
     "forwardPorts": [3100],
     "portsAttributes": {
         "3100": {

package/overlays/loki/docker-compose.yml

@@ -2,6 +2,7 @@ version: '3.8'
 services:
     loki:
         image: grafana/loki:${LOKI_VERSION:-latest}
+        restart: unless-stopped
         command: -config.file=/etc/loki/loki-config.yaml
         volumes:
             - ./loki-config-loki.yaml:/etc/loki/loki-config.yaml
@@ -10,9 +11,16 @@ services:
             - '${LOKI_PORT:-3100}:3100'
         networks:
             - devnet
+        healthcheck:
+            test: ['CMD', 'wget', '-qO-', 'http://localhost:3100/ready']
+            interval: 10s
+            timeout: 5s
+            retries: 5
+            start_period: 15s
 
 volumes:
     loki_data:
 
 networks:
     devnet:
+        name: devnet

package/overlays/loki/overlay.yml

@@ -20,3 +20,4 @@ ports:
       path: /
       onAutoForward: notify
 order: 1
+serviceOrder: 1

package/overlays/mailpit/docker-compose.yml

@@ -15,3 +15,4 @@ services:
 
 networks:
     devnet:
+        name: devnet

package/overlays/mailpit/overlay.yml

@@ -7,6 +7,7 @@ supports:
 requires: []
 suggests: []
 conflicts: []
+serviceOrder: 0
 tags:
     - dev
     - email

package/overlays/minio/devcontainer.patch.json

@@ -24,7 +24,7 @@
         "MINIO_ROOT_PASSWORD": "minioadmin",
         "AWS_ACCESS_KEY_ID": "minioadmin",
         "AWS_SECRET_ACCESS_KEY": "minioadmin",
-        "AWS_REGION": "us-east-1",
+        "AWS_DEFAULT_REGION": "us-east-1",
         "S3_ENDPOINT": "http://minio:9000"
     }
 }

package/overlays/minio/docker-compose.yml

@@ -26,3 +26,4 @@ volumes:
 
 networks:
     devnet:
+        name: devnet

package/overlays/minio/overlay.yml

@@ -5,8 +5,29 @@ category: database
 supports:
     - compose
 requires: []
-suggests: []
-conflicts: []
+suggests:
+    - prometheus
+    - grafana
+conflicts:
+    - localstack
+serviceOrder: 0
+parameters:
+    MINIO_VERSION:
+        description: MinIO image version tag
+        default: latest
+    MINIO_API_PORT:
+        description: Host port mapped to MinIO S3 API (9000 inside container)
+        default: '9000'
+    MINIO_CONSOLE_PORT:
+        description: Host port mapped to MinIO web console (9001 inside container)
+        default: '9001'
+    MINIO_ROOT_USER:
+        description: MinIO root username (access key)
+        default: minioadmin
+    MINIO_ROOT_PASSWORD:
+        description: MinIO root password (secret key)
+        default: minioadmin
+        sensitive: true
 tags:
     - database
     - storage

package/overlays/mkdocs/devcontainer.patch.json

@@ -7,11 +7,7 @@
     },
     "customizations": {
         "vscode": {
-            "extensions": [
-                "yzhang.markdown-all-in-one",
-                "DavidAnson.vscode-markdownlint",
-                "bierner.markdown-mermaid"
-            ]
+            "extensions": ["bierner.markdown-mermaid"]
         }
     },
     "forwardPorts": [8000],

package/overlays/mkdocs/overlay.yml

@@ -1,7 +1,7 @@
 id: mkdocs
 name: MkDocs
 description: Material for MkDocs - professional documentation generator
-category: language
+category: dev
 supports: []
 requires:
     - python
@@ -12,5 +12,7 @@ tags:
     - documentation
     - mkdocs
     - python
+imports:
+    - .shared/vscode/markdown-extensions.json
 ports:
     - 8000

package/overlays/mkdocs2/devcontainer.patch.json

@@ -2,11 +2,7 @@
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
     "customizations": {
         "vscode": {
-            "extensions": [
-                "yzhang.markdown-all-in-one",
-                "DavidAnson.vscode-markdownlint",
-                "bierner.markdown-mermaid"
-            ]
+            "extensions": ["bierner.markdown-mermaid"]
         }
     },
     "forwardPorts": [8000],

package/overlays/mkdocs2/overlay.yml

@@ -13,5 +13,7 @@ tags:
     - documentation
     - mkdocs
     - python
+imports:
+    - .shared/vscode/markdown-extensions.json
 ports:
     - 8000

package/overlays/mongodb/docker-compose.yml

@@ -19,6 +19,7 @@ services:
             interval: 10s
             timeout: 5s
             retries: 5
+            start_period: 20s
 
     mongo-express:
         image: mongo-express:${MONGO_EXPRESS_VERSION:-latest}
@@ -42,3 +43,4 @@ volumes:
 
 networks:
     devnet:
+        name: devnet

package/overlays/mongodb/overlay.yml

@@ -5,8 +5,32 @@ category: database
 supports:
     - compose
 requires: []
-suggests: []
-conflicts: []
+suggests:
+    - prometheus
+    - grafana
+conflicts:
+    - redpanda
+    - otel-demo-python
+    - go
+    - java
+serviceOrder: 0
+parameters:
+    MONGODB_VERSION:
+        description: MongoDB image version tag
+        default: '8'
+    MONGODB_PORT:
+        description: Host port mapped to MongoDB (27017 inside container)
+        default: '27017'
+    MONGO_EXPRESS_PORT:
+        description: Host port mapped to Mongo Express (8081 inside container)
+        default: '8081'
+    MONGODB_USER:
+        description: MongoDB root username
+        default: root
+    MONGODB_PASSWORD:
+        description: MongoDB root password
+        default: example
+        sensitive: true
 tags:
     - database
     - nosql

package/overlays/mysql/docker-compose.yml

@@ -30,6 +30,7 @@ services:
             interval: 10s
             timeout: 5s
             retries: 5
+            start_period: 30s
 
     phpmyadmin:
         image: phpmyadmin:${PHPMYADMIN_VERSION:-latest}
@@ -53,3 +54,4 @@ volumes:
 
 networks:
     devnet:
+        name: devnet

package/overlays/mysql/overlay.yml

@@ -5,8 +5,42 @@ category: database
 supports:
     - compose
 requires: []
-suggests: []
-conflicts: []
+suggests:
+    - prometheus
+    - grafana
+conflicts:
+    - redpanda
+    - nodejs
+    - bun
+    - go
+    - java
+    - dotnet
+    - otel-demo-nodejs
+serviceOrder: 0
+parameters:
+    MYSQL_VERSION:
+        description: MySQL image version tag
+        default: '8'
+    MYSQL_PORT:
+        description: Host port mapped to MySQL (3306 inside container)
+        default: '3306'
+    PHPMYADMIN_PORT:
+        description: Host port mapped to phpMyAdmin (80 inside container)
+        default: '8080'
+    MYSQL_DATABASE:
+        description: Name of the database to create
+        default: devdb
+    MYSQL_USER:
+        description: MySQL user name
+        default: devuser
+    MYSQL_PASSWORD:
+        description: MySQL user password
+        default: devpassword
+        sensitive: true
+    MYSQL_ROOT_PASSWORD:
+        description: MySQL root password
+        default: rootpassword
+        sensitive: true
 tags:
     - database
     - sql

package/overlays/nats/docker-compose.yml

@@ -29,3 +29,4 @@ volumes:
 
 networks:
     devnet:
+        name: devnet

package/overlays/nats/overlay.yml

@@ -1,12 +1,28 @@
 id: nats
 name: NATS
 description: Lightweight pub/sub messaging with JetStream
-category: database
+category: messaging
 supports:
     - compose
 requires: []
-suggests: []
+suggests:
+    - prometheus
+    - grafana
 conflicts: []
+serviceOrder: 0
+parameters:
+    NATS_VERSION:
+        description: NATS image version tag
+        default: '2'
+    NATS_CLIENT_PORT:
+        description: Host port mapped to NATS client (4222 inside container)
+        default: '4222'
+    NATS_HTTP_PORT:
+        description: Host port mapped to NATS monitoring HTTP (8222 inside container)
+        default: '8222'
+    NATS_CLUSTER_PORT:
+        description: Host port mapped to NATS cluster (6222 inside container)
+        default: '6222'
 tags:
     - database
     - messaging