container-superposition 0.1.1 → 0.1.4

package/overlays/.presets/k8s-operator-dev.yml

@@ -0,0 +1,462 @@
+# Kubernetes Operator Development Preset
+# Go-based Kubernetes operator/controller development
+
+id: k8s-operator-dev
+name: Kubernetes Operator Development
+description: Go-based operator development with kubectl and Helm
+type: meta
+category: preset
+supports: [] # Works with both plain and compose
+tags: [preset, kubernetes, operator, controller, k8s, crd, go]
+
+# Overlays to select
+selects:
+    # Always included
+    required:
+        - go
+        - kubectl-helm
+        - modern-cli-tools
+
+    # No user choices - operators are typically Go
+    userChoice: {}
+
+# Glue configuration - integration helpers
+glueConfig:
+    # Pre-configured environment variables
+    environment:
+        # Go environment
+        GOOS: 'linux'
+        GOARCH: 'amd64'
+        CGO_ENABLED: '0'
+
+        # Kubernetes configuration
+        KUBECONFIG: '/home/vscode/.kube/config'
+
+        # Operator SDK settings
+        OPERATOR_NAME: 'my-operator'
+        OPERATOR_NAMESPACE: 'default'
+
+        # Development cluster settings (for future kind/k3d overlay)
+        # KIND_CLUSTER_NAME: 'operator-dev'
+        # K3D_CLUSTER_NAME: 'operator-dev'
+
+    # Suggested port mappings
+    portMappings:
+        operator-metrics: 8080
+        operator-health: 8081
+
+    # README snippet to add to generated devcontainer
+    readme: |
+        ## Kubernetes Operator Development Stack
+
+        This devcontainer is configured for Kubernetes operator development:
+
+        ### Tools
+
+        - **Go**: Operator runtime and tooling
+        - **kubectl**: Kubernetes CLI
+        - **Helm**: Package manager for Kubernetes
+        - **Modern CLI Tools**: jq, yq, bat for manifest inspection
+
+        ### Operator Frameworks
+
+        This environment supports multiple operator frameworks:
+
+        #### Kubebuilder (Recommended)
+
+        ```bash
+        # Install Kubebuilder
+        curl -L -o kubebuilder "https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)"
+        chmod +x kubebuilder
+        sudo mv kubebuilder /usr/local/bin/
+
+        # Initialize new operator
+        mkdir my-operator && cd my-operator
+        kubebuilder init --domain example.com --repo github.com/myorg/my-operator
+
+        # Create API/Controller
+        kubebuilder create api --group apps --version v1alpha1 --kind MyResource
+        ```
+
+        #### Operator SDK
+
+        ```bash
+        # Install Operator SDK
+        export ARCH=$(case "$(uname -m)" in
+          x86_64) echo -n amd64 ;;
+          aarch64) echo -n arm64 ;;
+          *) echo -n "$(uname -m)" ;;
+        esac)
+        export OS=$(uname | awk '{print tolower($0)}')
+        export OPERATOR_SDK_DL_URL=https://github.com/operator-framework/operator-sdk/releases/latest/download
+        curl -LO ${OPERATOR_SDK_DL_URL}/operator-sdk_${OS}_${ARCH}
+        chmod +x operator-sdk_${OS}_${ARCH}
+        sudo mv operator-sdk_${OS}_${ARCH} /usr/local/bin/operator-sdk
+
+        # Create new operator
+        mkdir my-operator && cd my-operator
+        operator-sdk init --domain example.com --repo github.com/myorg/my-operator
+
+        # Create API
+        operator-sdk create api --group apps --version v1alpha1 --kind MyResource
+        ```
+
+        ### Quick Start (Kubebuilder)
+
+        #### 1. Scaffold Operator
+
+        ```bash
+        mkdir my-operator && cd my-operator
+        kubebuilder init --domain example.com --repo github.com/myorg/my-operator
+        kubebuilder create api --group apps --version v1alpha1 --kind MyApp --resource --controller
+        ```
+
+        This creates:
+        - `api/v1alpha1/myapp_types.go` - CRD definition
+        - `internal/controller/myapp_controller.go` - Reconciliation logic
+        - `config/` - Kubernetes manifests
+
+        #### 2. Define CRD
+
+        ```go
+        // api/v1alpha1/myapp_types.go
+        type MyAppSpec struct {
+            // +kubebuilder:validation:Minimum=1
+            Replicas int32 `json:"replicas"`
+
+            // +kubebuilder:validation:Required
+            Image string `json:"image"`
+        }
+
+        type MyAppStatus struct {
+            // Conditions represent the latest available observations
+            Conditions []metav1.Condition `json:"conditions,omitempty"`
+
+            // Ready replicas
+            ReadyReplicas int32 `json:"readyReplicas"`
+        }
+        ```
+
+        #### 3. Implement Controller
+
+        ```go
+        // internal/controller/myapp_controller.go
+        func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
+            log := log.FromContext(ctx)
+
+            // Fetch the MyApp instance
+            myApp := &appsv1alpha1.MyApp{}
+            err := r.Get(ctx, req.NamespacedName, myApp)
+            if err != nil {
+                return ctrl.Result{}, client.IgnoreNotFound(err)
+            }
+
+            // Reconciliation logic
+            // 1. Ensure Deployment exists
+            // 2. Update Deployment if spec changed
+            // 3. Update status
+
+            log.Info("Reconciled MyApp", "name", myApp.Name)
+            return ctrl.Result{}, nil
+        }
+        ```
+
+        #### 4. Test Locally
+
+        ```bash
+        # Generate manifests
+        make manifests
+
+        # Run tests
+        make test
+
+        # Run controller locally (no cluster needed initially)
+        make run
+        ```
+
+        ### Connecting to Kubernetes Cluster
+
+        This preset includes kubectl and Helm. You can connect to:
+
+        #### Remote Cluster
+
+        ```bash
+        # Set up kubeconfig
+        export KUBECONFIG=~/.kube/config
+
+        # Or copy config from local machine
+        cp /path/to/kubeconfig ~/.kube/config
+
+        # Verify connection
+        kubectl cluster-info
+        kubectl get nodes
+        ```
+
+        #### Future: Local Cluster (kind/k3d overlay)
+
+        When kind or k3d overlay is available:
+
+        ```bash
+        # kind
+        kind create cluster --name operator-dev
+
+        # k3d
+        k3d cluster create operator-dev
+        ```
+
+        ### Development Workflow
+
+        #### 1. Install CRDs
+
+        ```bash
+        make install
+        # This creates CustomResourceDefinition in cluster
+        ```
+
+        #### 2. Run Operator
+
+        ```bash
+        # Option A: Run locally (outside cluster)
+        make run
+
+        # Option B: Build and deploy to cluster
+        make docker-build docker-push IMG=myregistry/my-operator:v0.1.0
+        make deploy IMG=myregistry/my-operator:v0.1.0
+        ```
+
+        #### 3. Create Custom Resource
+
+        ```yaml
+        # config/samples/apps_v1alpha1_myapp.yaml
+        apiVersion: apps.example.com/v1alpha1
+        kind: MyApp
+        metadata:
+            name: myapp-sample
+        spec:
+            replicas: 3
+            image: nginx:latest
+        ```
+
+        ```bash
+        kubectl apply -f config/samples/apps_v1alpha1_myapp.yaml
+        ```
+
+        #### 4. Watch Reconciliation
+
+        ```bash
+        # Watch controller logs
+        kubectl logs -f -n <namespace> <operator-pod>
+
+        # Watch custom resource
+        kubectl get myapp -w
+
+        # Describe custom resource
+        kubectl describe myapp myapp-sample
+        ```
+
+        ### Testing Operators
+
+        #### Unit Tests
+
+        ```go
+        // internal/controller/myapp_controller_test.go
+        var _ = Describe("MyApp Controller", func() {
+            Context("When reconciling a resource", func() {
+                It("Should create a Deployment", func() {
+                    // Test reconciliation logic
+                })
+            })
+        })
+        ```
+
+        Run tests:
+
+        ```bash
+        make test
+        ```
+
+        #### Integration Tests with envtest
+
+        ```go
+        var k8sClient client.Client
+        var testEnv *envtest.Environment
+
+        BeforeSuite(func() {
+            testEnv = &envtest.Environment{
+                CRDDirectoryPaths: []string{filepath.Join("..", "config", "crd", "bases")},
+            }
+            cfg, err := testEnv.Start()
+            Expect(err).NotTo(HaveOccurred())
+
+            k8sClient, err = client.New(cfg, client.Options{})
+            Expect(err).NotTo(HaveOccurred())
+        })
+        ```
+
+        ### Helm Chart for Operator
+
+        ```bash
+        # Create Helm chart
+        mkdir -p charts/my-operator
+        helm create charts/my-operator
+
+        # Package chart
+        helm package charts/my-operator
+
+        # Install from chart
+        helm install my-operator charts/my-operator
+        ```
+
+        ### RBAC Configuration
+
+        Operators need appropriate permissions:
+
+        ```yaml
+        # config/rbac/role.yaml
+        apiVersion: rbac.authorization.k8s.io/v1
+        kind: ClusterRole
+        metadata:
+            name: operator-role
+        rules:
+        - apiGroups: ["apps.example.com"]
+          resources: ["myapps"]
+          verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
+        - apiGroups: ["apps"]
+          resources: ["deployments"]
+          verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
+        ```
+
+        Kubebuilder generates RBAC with markers:
+
+        ```go
+        // +kubebuilder:rbac:groups=apps.example.com,resources=myapps,verbs=get;list;watch;create;update;patch;delete
+        // +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
+        ```
+
+        ### Operator Patterns
+
+        #### Level-Based Reconciliation
+
+        ```go
+        func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
+            // Get desired state
+            myApp := &appsv1alpha1.MyApp{}
+            if err := r.Get(ctx, req.NamespacedName, myApp); err != nil {
+                return ctrl.Result{}, client.IgnoreNotFound(err)
+            }
+
+            // Get current state
+            deployment := &appsv1.Deployment{}
+            err := r.Get(ctx, types.NamespacedName{
+                Name: myApp.Name, Namespace: myApp.Namespace,
+            }, deployment)
+
+            if err != nil {
+                // Create if not exists
+                return r.createDeployment(ctx, myApp)
+            }
+
+            // Update if different
+            if deployment.Spec.Replicas != &myApp.Spec.Replicas {
+                return r.updateDeployment(ctx, myApp, deployment)
+            }
+
+            return ctrl.Result{}, nil
+        }
+        ```
+
+        #### Finalizers
+
+        ```go
+        const myFinalizerName = "myapp.example.com/finalizer"
+
+        func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
+            myApp := &appsv1alpha1.MyApp{}
+            if err := r.Get(ctx, req.NamespacedName, myApp); err != nil {
+                return ctrl.Result{}, client.IgnoreNotFound(err)
+            }
+
+            // Handle deletion
+            if myApp.DeletionTimestamp != nil {
+                if controllerutil.ContainsFinalizer(myApp, myFinalizerName) {
+                    // Cleanup logic
+                    if err := r.cleanup(ctx, myApp); err != nil {
+                        return ctrl.Result{}, err
+                    }
+
+                    controllerutil.RemoveFinalizer(myApp, myFinalizerName)
+                    return ctrl.Result{}, r.Update(ctx, myApp)
+                }
+                return ctrl.Result{}, nil
+            }
+
+            // Add finalizer if not present
+            if !controllerutil.ContainsFinalizer(myApp, myFinalizerName) {
+                controllerutil.AddFinalizer(myApp, myFinalizerName)
+                return ctrl.Result{}, r.Update(ctx, myApp)
+            }
+
+            // Normal reconciliation
+            return ctrl.Result{}, nil
+        }
+        ```
+
+        ### Debugging
+
+        ```bash
+        # Use kubectl to inspect resources
+        kubectl get myapp -o yaml
+        kubectl describe myapp myapp-sample
+
+        # Check events
+        kubectl get events --sort-by='.lastTimestamp'
+
+        # Debug with delve
+        dlv debug ./cmd/main.go
+        ```
+
+        ### Modern CLI Tools for K8s
+
+        ```bash
+        # Inspect manifests with yq
+        yq eval '.spec.replicas' config/samples/myapp.yaml
+
+        # Format YAML with bat
+        bat config/crd/bases/apps.example.com_myapps.yaml
+
+        # Search in manifests
+        rg 'kind: Deployment' config/
+
+        # Find manifest files
+        fd -e yaml config/
+        ```
+
+        ### Future Enhancements
+
+        When kind/k3d and tilt/skaffold overlays are available:
+
+        #### Local Kubernetes Cluster
+
+        - Fast inner development loop
+        - No external cluster dependencies
+        - Test CRD installations locally
+
+        #### Live Reload with Tilt/Skaffold
+
+        - Automatic rebuild on code changes
+        - Fast feedback cycle
+        - Port forwarding management
+        - Log aggregation
+
+        ### Next Steps
+
+        - Choose operator framework (Kubebuilder or Operator SDK)
+        - Design your Custom Resource Definition (CRD)
+        - Implement reconciliation logic
+        - Add unit and integration tests
+        - Configure RBAC permissions
+        - Create Helm chart for distribution
+        - Set up CI/CD for operator builds
+        - Document operator usage
+        - Implement metrics and monitoring
+        - Add webhooks for validation/mutation

package/overlays/{presets → .presets}/microservice.yml

@@ -26,11 +26,35 @@ selects:
             options: [dotnet, nodejs, python, go, java]
             defaultOption: nodejs
 
-        messaging:
-            id: messaging
-            prompt: Select message broker
-            options: [rabbitmq, redpanda, nats]
-            defaultOption: rabbitmq
+# Parameterized slots
+parameters:
+    broker:
+        description: 'Message broker'
+        default: rabbitmq
+        options:
+            - id: rabbitmq
+              overlays: [rabbitmq]
+              description: 'RabbitMQ AMQP message broker'
+            - id: nats
+              overlays: [nats]
+              description: 'NATS lightweight messaging'
+            - id: redpanda
+              overlays: [redpanda]
+              description: 'Redpanda Kafka-compatible streaming'
+            - id: none
+              overlays: []
+              description: 'No message broker'
+
+    observability:
+        description: 'Observability stack level'
+        default: standard
+        options:
+            - id: standard
+              overlays: []
+              description: 'Standard (Jaeger + Prometheus + Grafana, already included)'
+            - id: full
+              overlays: [loki]
+              description: 'Full stack - adds Loki for log aggregation'
 
 # Glue configuration - integration helpers
 glueConfig:
@@ -66,11 +90,12 @@ glueConfig:
 
         ### Services
 
-        - **Message Broker**: Async communication between services
+        - **Message Broker**: Async communication between services (RabbitMQ/NATS/Redpanda based on your choice)
         - **OpenTelemetry Collector**: Distributed tracing collection (ports 4317, 4318)
         - **Jaeger**: Distributed tracing UI (port 16686)
         - **Prometheus**: Metrics storage (port 9090)
         - **Grafana**: Unified observability dashboard (port 3000)
+        - **Loki** _(full observability only)_: Log aggregation (port 3100)
 
         ### Connection Strings
 
@@ -100,6 +125,7 @@ glueConfig:
         2. Publish/subscribe to messages via your chosen broker
         3. View distributed traces in Jaeger at http://localhost:16686
         4. Monitor metrics in Grafana at http://localhost:3000
+        5. _(Full observability)_ Query logs in Loki via Grafana at http://localhost:3000
 
         ### Distributed Tracing
 

package/overlays/.presets/web-api.yml

@@ -0,0 +1,129 @@
+# Web API Stack Preset
+# Complete environment for REST/GraphQL API development
+
+id: web-api
+name: Web API Stack
+description: Complete REST/GraphQL API development environment with database, cache, and observability
+type: meta
+category: preset
+supports: [compose] # Requires Docker Compose for services
+tags: [preset, api, web, backend, observability]
+
+# Overlays to select
+selects:
+    # Always included
+    required: []
+
+    # User makes choices
+    userChoice:
+        language:
+            id: language
+            prompt: Select API language/framework
+            options: [dotnet, nodejs, python, go, java]
+            defaultOption: nodejs
+
+# Parameterized slots - users can customize these without micro-managing individual overlays
+parameters:
+    database:
+        description: 'Primary data store'
+        default: postgres
+        options:
+            - id: postgres
+              overlays: [postgres]
+              description: 'PostgreSQL relational database'
+            - id: mongodb
+              overlays: [mongodb]
+              description: 'MongoDB document database'
+            - id: mysql
+              overlays: [mysql]
+              description: 'MySQL relational database'
+            - id: none
+              overlays: []
+              description: 'No database (manage separately)'
+
+    cache:
+        description: 'In-memory cache'
+        default: redis
+        options:
+            - id: redis
+              overlays: [redis]
+              description: 'Redis cache and session store'
+            - id: none
+              overlays: []
+              description: 'No cache'
+
+    broker:
+        description: 'Message broker (optional)'
+        default: none
+        options:
+            - id: rabbitmq
+              overlays: [rabbitmq]
+              description: 'RabbitMQ AMQP message broker'
+            - id: nats
+              overlays: [nats]
+              description: 'NATS lightweight messaging'
+            - id: redpanda
+              overlays: [redpanda]
+              description: 'Redpanda Kafka-compatible streaming'
+            - id: none
+              overlays: []
+              description: 'No message broker'
+
+    observability:
+        description: 'Monitoring and observability stack'
+        default: standard
+        options:
+            - id: minimal
+              overlays: []
+              description: 'No observability tools'
+            - id: standard
+              overlays: [prometheus, grafana]
+              description: 'Metrics and dashboards'
+            - id: full
+              overlays: [otel-collector, prometheus, grafana, loki]
+              description: 'Full stack - metrics, logs, and traces'
+
+# Glue configuration - integration helpers
+glueConfig:
+    # Suggested port mappings (actual ports depend on chosen overlays)
+    portMappings:
+        api: 8000
+        grafana: 3000
+        prometheus: 9090
+
+    # README snippet to add to generated devcontainer
+    readme: |
+        ## Web API Stack
+
+        This devcontainer is configured for web API development. The exact services depend
+        on the parameters you chose (database, cache, broker, observability).
+
+        ### Connection Strings
+
+        Connection strings for each service are defined in `.devcontainer/.env.example`.
+        Copy that file to `.env` and adjust values as needed:
+
+        ```bash
+        cd .devcontainer
+        cp .env.example .env
+        ```
+
+        ### Quick Start
+
+        1. Start your API (default suggested port: 8000)
+        2. Access Grafana at http://localhost:3000 (admin/admin) — if observability was enabled
+        3. View metrics in Prometheus at http://localhost:9090 — if observability was enabled
+
+        ### Health Checks
+
+        Verify all services are running:
+
+        ```bash
+        docker-compose ps
+        ```
+
+        ### Next Steps
+
+        - Configure your API to use the connection strings from `.env`
+        - Add OpenTelemetry SDK to your application (if full observability was selected)
+        - Create custom Grafana dashboards for your API metrics

package/overlays/.registry/README.md

@@ -11,4 +11,4 @@ These files are loaded during initialization to provide choices for base images
 
 ## Note
 
-Preset definitions are stored in `overlays/presets/*.yml`.
+Preset definitions are stored in `overlays/.presets/*.yml`.

package/overlays/.registry/deployment-targets.yml

@@ -0,0 +1,54 @@
+deployment_targets:
+    - id: local
+      name: Local Development
+      description: Running on local machine with Docker Desktop or Docker daemon
+      incompatibleOverlays: []
+      recommendations: {}
+      portForwarding:
+          defaultBehavior: notify
+          autoForward: false
+      constraints:
+          hasHostDocker: true
+          supportsPrivileged: true
+
+    - id: codespaces
+      name: GitHub Codespaces
+      description: Cloud-based development environment on GitHub
+      incompatibleOverlays:
+          - docker-sock
+      recommendations:
+          docker-sock:
+              - docker-in-docker
+      portForwarding:
+          defaultBehavior: notify
+          autoForward: true
+      constraints:
+          hasHostDocker: false
+          supportsPrivileged: true
+
+    - id: gitpod
+      name: Gitpod
+      description: Cloud development environment on Gitpod
+      incompatibleOverlays:
+          - docker-sock
+      recommendations:
+          docker-sock:
+              - docker-in-docker
+      portForwarding:
+          defaultBehavior: openBrowser
+          autoForward: true
+      constraints:
+          hasHostDocker: false
+          supportsPrivileged: true
+
+    - id: devpod
+      name: DevPod
+      description: Client-only development environments
+      incompatibleOverlays: []
+      recommendations: {}
+      portForwarding:
+          defaultBehavior: notify
+          autoForward: false
+      constraints:
+          hasHostDocker: true
+          supportsPrivileged: true