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.