Skip to content

LiorCohen/sdd / plugin/fullstack-typescript/skills/orchestrators/local-env-orchestration

local-env-orchestration

Verified

Orchestrates local Kubernetes development environment management.

FileKindSize
SKILL.mdskill md7.7 KB
---
name: local-env-orchestration
description: Orchestrates local Kubernetes development environment management.
user-invocable: false
---

# 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:**
```bash
<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:**
```bash
<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:**
```bash
<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:**
```bash
<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:**
```bash
<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:**
```bash
<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:**
```bash
<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:**
```bash
<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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path β€” even casually (like "the xlsx in my downloads") β€” and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall