local-env-orchestration

Local Environment Orchestration

Manage local Kubernetes development environments for SDD projects.

Input

Invoked by sdd-run.md with:

• action — The local-env action to perform
• args — Remaining arguments after the action

Prerequisites

• Docker installed and running
• kubectl installed
• helm installed
• One of the following cluster providers:
• kind (brew install kind) - recommended
• minikube (brew install minikube)
• Docker Desktop with Kubernetes enabled

Actions

| Action | Description | |--------|-------------| | create | Create cluster + install infra | | destroy | Delete cluster entirely | | start | Resume stopped cluster | | stop | Pause cluster (preserves state) | | status | Show cluster and workload status | | deploy | Set up databases, run migrations, deploy helm charts | | undeploy | Remove helm deployments (databases persist) | | forward | Manage port forwards | | infra | Install/reinstall observability infrastructure |

No Arguments

When invoked without an action, display usage:

⚠ Missing required action argument.

USAGE:
  /sdd-run local-env <action> [args] [options]

ACTIONS:
  create     Create local k8s cluster + install infra
  destroy    Delete cluster entirely                      🔴 destructive
  start      Resume stopped cluster
  stop       Pause cluster (preserves state)
  status     Show cluster and workload status
  deploy     Set up databases, run migrations, deploy helm charts
  undeploy   Remove helm deployments                      🟡 caution
  forward    Manage port forwards (start|stop|list)
  infra      Install/reinstall observability infrastructure

EXAMPLES:
  /sdd-run local-env create
  /sdd-run local-env deploy
  /sdd-run local-env forward start
  /sdd-run local-env status

Action Details

create

/sdd-run local-env create [--name=cluster-name] [--provider=kind|minikube|docker-desktop] [--skip-infra]

Creates a local k8s cluster and installs the observability stack (Victoria Metrics + Victoria Logs).

Options:

• --name: Cluster name (default: sdd-local)
• --provider: Cluster provider (default: auto-detected)
• kind: Kubernetes IN Docker (fast, lightweight)
• minikube: Full-featured local k8s
• docker-desktop: Uses Docker Desktop's built-in Kubernetes
• --skip-infra: Skip installing observability stack

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env create [--name=cluster-name] [--provider=kind|minikube|docker-desktop] [--skip-infra]

destroy

/sdd-run local-env destroy [--name=cluster-name]

Completely removes the local cluster (not available for docker-desktop).

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env destroy [--name=cluster-name]

start / stop

/sdd-run local-env start [--name=cluster-name]
/sdd-run local-env stop [--name=cluster-name]

Pause and resume the cluster. State is preserved when stopped.

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env start [--name=cluster-name]
<plugin-root>/fullstack-typescript/system/system-run.sh local-env stop [--name=cluster-name]

status

/sdd-run local-env status [--name=cluster-name]

Shows cluster status, node health, and deployed workloads.

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env status [--name=cluster-name]

deploy

/sdd-run local-env deploy [chart-name] [--namespace=<app-name>] [--skip-db] [--skip-migrate] [--exclude=name,...]

Deploys the full application stack in order:

1. Databases - Sets up PostgreSQL instances for each type: database component
2. Migrations - Runs database migrations
3. Helm charts - Deploys application charts from components/helm_charts/

Options:

• --namespace: Override namespace (default: app name from sdd-settings.yaml)
• --skip-db: Skip database setup (useful for redeploying apps only)
• --skip-migrate: Skip running migrations
• --exclude: Comma-separated list of charts to skip (for hybrid development)

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env deploy [chart-name] [--namespace=<app-name>] [--skip-db] [--skip-migrate] [--exclude=name,...]

undeploy

/sdd-run local-env undeploy [chart-name] [--namespace=<app-name>]

Removes deployed applications (keeps infrastructure).

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env undeploy [chart-name] [--namespace=<app-name>]

forward

/sdd-run local-env forward [start|stop|list] [--namespace=<app-name>]

Manages port forwards for local access to services.

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env forward [start|stop|list] [--namespace=<app-name>]

infra

/sdd-run local-env infra [--reinstall]

Install or reinstall the observability infrastructure stack.

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env infra [--reinstall]

Architecture

Cluster Providers

| Provider | Best For | Create Time | Notes | |----------|----------|-------------|-------| | kind | CI/CD, disposable clusters | ~30 seconds | Default, recommended | | minikube | Feature-rich local dev | ~60 seconds | Supports addons | | docker-desktop | Simple local dev | Already running | Uses existing cluster |

Auto-detection order:

1. If Docker Desktop k8s is running → docker-desktop
2. If minikube is installed → minikube
3. Default → kind

Infrastructure Stack

The telemetry namespace contains:

• Victoria Metrics: Metrics collection and storage
• Victoria Logs: Log aggregation
• Log Collector: DaemonSet collecting logs from all pods

Namespace Layout

| Namespace | Contents | |-----------|----------| | telemetry | Observability stack | | <app-name> | Application deployments (from sdd-settings.yaml name field) |

Integration with Settings

The deploy action reads sdd/sdd-settings.yaml (delegate to the techpack-settings skill for the settings schema — it returns the project name, component list with types, and per-component settings) to:

1. Get the app name (used as the Kubernetes namespace)
2. Find all type: database components to set up
3. Find all type: helm components to deploy

Hybrid Development

Run most services in k8s while developing one locally:

# Deploy everything except the service you're working on
/sdd-run local-env deploy --exclude=main-server-api

# Start port forwards so your local service can reach k8s
/sdd-run local-env forward start

# Run your service locally
cd components/servers/main-server
npm run dev

Your local service connects to:

• Databases: via port-forwarded PostgreSQL (localhost:5432)
• Other APIs: via port-forwarded services (localhost:8080+)
• Telemetry: Victoria Metrics at localhost:9090

Troubleshooting

Cluster won't start

# Check Docker is running
docker ps

# Check kind clusters
kind get clusters

# Delete and recreate
/sdd-run local-env destroy
/sdd-run local-env create

Pods not starting

# Check pod status
kubectl get pods -A

# Check pod logs
kubectl logs <pod-name> -n <namespace>

# Describe pod for events
kubectl describe pod <pod-name> -n <namespace>

Port forward not working

# List active forwards
/sdd-run local-env forward list

# Stop all and restart
/sdd-run local-env forward stop
/sdd-run local-env forward start

Output

Returns the system CLI output for the requested action.