container-superposition 0.1.1 → 0.1.3

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/.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

package/overlays/.shared/README.md

@@ -0,0 +1,43 @@
+# Shared Overlay Configurations
+
+This directory contains shared configuration fragments that can be imported by multiple overlays to reduce duplication and ensure consistency.
+
+## Structure
+
+```
+.shared/
+├── otel/               # OpenTelemetry configurations
+├── compose/            # Docker Compose patterns (healthchecks, etc.)
+└── vscode/             # VS Code extension sets
+```
+
+## Usage
+
+Overlays can import shared files by adding them to the `imports` field in `overlay.yml`:
+
+```yaml
+id: prometheus
+imports:
+    - .shared/otel/otel-base-config.yaml
+    - .shared/compose/common-healthchecks.yml
+```
+
+## Benefits
+
+- **DRY (Don't Repeat Yourself)**: Common patterns defined once
+- **Consistency**: All overlays using the same shared config stay in sync
+- **Maintainability**: Update shared config once, all overlays benefit
+- **Best Practices**: Shared configs embody proven patterns
+
+## Creating Shared Configs
+
+1. Identify common patterns across overlays
+2. Extract to appropriate `.shared/` subdirectory
+3. Update overlays to import the shared file
+4. Test that imports work correctly
+
+## Import Resolution
+
+- Imports are resolved relative to the `overlays/` directory
+- Shared files are merged into the overlay during composition
+- Files are applied in the order they are listed

package/overlays/.shared/compose/common-healthchecks.yml

@@ -0,0 +1,38 @@
+# Common Docker Compose Healthcheck Patterns
+# These can be referenced by overlays to ensure consistent healthcheck configuration
+
+healthchecks:
+    http:
+        test: ['CMD-SHELL', 'curl -f http://localhost:${PORT}/health || exit 1']
+        interval: 30s
+        timeout: 10s
+        retries: 3
+        start_period: 40s
+
+    postgres:
+        test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-postgres}']
+        interval: 10s
+        timeout: 5s
+        retries: 5
+        start_period: 10s
+
+    redis:
+        test: ['CMD', 'redis-cli', 'ping']
+        interval: 10s
+        timeout: 5s
+        retries: 5
+        start_period: 10s
+
+    mongodb:
+        test: ['CMD', 'mongosh', '--eval', "db.adminCommand('ping')"]
+        interval: 10s
+        timeout: 5s
+        retries: 5
+        start_period: 10s
+
+    mysql:
+        test: ['CMD', 'mysqladmin', 'ping', '-h', 'localhost']
+        interval: 10s
+        timeout: 5s
+        retries: 5
+        start_period: 10s

package/overlays/.shared/otel/instrumentation.env

@@ -0,0 +1,20 @@
+# OpenTelemetry Instrumentation Environment Variables
+# Common variables for language-specific auto-instrumentation
+
+# OTEL SDK Configuration
+OTEL_SERVICE_NAME=my-service
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
+OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+
+# Resource Attributes
+OTEL_RESOURCE_ATTRIBUTES=deployment.environment=development
+
+# Trace Configuration
+OTEL_TRACES_SAMPLER=always_on
+OTEL_TRACES_EXPORTER=otlp
+
+# Metrics Configuration
+OTEL_METRICS_EXPORTER=otlp
+
+# Logs Configuration
+OTEL_LOGS_EXPORTER=otlp

package/overlays/.shared/otel/otel-base-config.yaml

@@ -0,0 +1,30 @@
+# OpenTelemetry Base Configuration
+# This file provides common OTEL environment variables for instrumentation
+
+receivers:
+    otlp:
+        protocols:
+            grpc:
+                endpoint: 0.0.0.0:4317
+            http:
+                endpoint: 0.0.0.0:4318
+
+exporters:
+    logging:
+        loglevel: debug
+
+processors:
+    batch:
+        timeout: 10s
+        send_batch_size: 1024
+
+service:
+    pipelines:
+        traces:
+            receivers: [otlp]
+            processors: [batch]
+            exporters: [logging]
+        metrics:
+            receivers: [otlp]
+            processors: [batch]
+            exporters: [logging]

package/overlays/.shared/vscode/recommended-extensions.json

@@ -0,0 +1,14 @@
+{
+    "description": "Commonly recommended VS Code extensions across overlays",
+    "extensions": {
+        "productivity": [
+            "streetsidesoftware.code-spell-checker",
+            "usernamehw.errorlens",
+            "eamodio.gitlens"
+        ],
+        "formatting": ["editorconfig.editorconfig", "esbenp.prettier-vscode"],
+        "docker": ["ms-azuretools.vscode-docker"],
+        "yaml": ["redhat.vscode-yaml"],
+        "markdown": ["yzhang.markdown-all-in-one", "davidanson.vscode-markdownlint"]
+    }
+}

package/overlays/README.md

@@ -150,6 +150,6 @@ See [Creating Overlays Guide](../docs/creating-overlays.md) for complete documen
 
 ## Presets (Meta-Overlays)
 
-Presets are special meta-overlays that select combinations of overlays for common scenarios (web-api, microservice, docs-site, fullstack). They're located in `overlays/presets/*.yml`.
+Presets are special meta-overlays that select combinations of overlays for common scenarios (web-api, microservice, docs-site, fullstack). They're located in `overlays/.presets/*.yml`.
 
 See [Presets Guide](../docs/presets.md) and [Presets Architecture](../docs/presets-architecture.md) for detailed documentation on creating and using presets.

package/overlays/codex/overlay.yml

@@ -12,3 +12,4 @@ tags:
     - ai
     - code-generation
 ports: []
+minimal: true