Skip to content

Commit 9d20d25

Browse files
barnabasbusabarnabasbusa
committed
feat add more skills
1 parent af2b9ac commit 9d20d25

File tree

4 files changed

+559
-0
lines changed

4 files changed

+559
-0
lines changed

‎skills/cli-local-build/SKILL.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
name: cli-local-build
3+
description: Build and test the Kurtosis CLI from source. Compile the CLI binary locally, run it against Docker or Kubernetes engines, and iterate on CLI changes without creating a release. Use when developing or debugging CLI commands.
4+
compatibility: Requires Go 1.23+.
5+
metadata:
6+
author: ethpandaops
7+
version: "1.0"
8+
---
9+
10+
# CLI Local Build
11+
12+
Build and test the Kurtosis CLI from source for local development.
13+
14+
## Quick build
15+
16+
```bash
17+
# Build the CLI binary
18+
go build -o /tmp/kurtosis ./cli/cli/
19+
20+
# Verify it works
21+
/tmp/kurtosis version
22+
```
23+
24+
## Using the local CLI
25+
26+
The locally built CLI works exactly like the installed one. Use the full path to avoid conflicts with the system-installed `kurtosis`:
27+
28+
```bash
29+
# Start engine
30+
/tmp/kurtosis engine start
31+
32+
# Run a package
33+
/tmp/kurtosis run github.com/ethpandaops/ethereum-package
34+
35+
# Clean up
36+
/tmp/kurtosis clean -a
37+
38+
# Stop engine
39+
/tmp/kurtosis engine stop
40+
```
41+
42+
## Switching between Docker and Kubernetes
43+
44+
```bash
45+
# Check current cluster setting
46+
/tmp/kurtosis cluster get
47+
48+
# Switch to Docker
49+
/tmp/kurtosis cluster set docker
50+
51+
# Switch to Kubernetes (uses current kubectl context)
52+
/tmp/kurtosis cluster set kubernetes
53+
54+
# Restart engine after switching
55+
/tmp/kurtosis engine restart
56+
```
57+
58+
## Build with race detector
59+
60+
For debugging concurrency issues:
61+
62+
```bash
63+
go build -race -o /tmp/kurtosis ./cli/cli/
64+
```
65+
66+
## Running tests
67+
68+
```bash
69+
# Run CLI command tests
70+
go test ./cli/cli/commands/...
71+
72+
# Run a specific test
73+
go test -run TestName ./cli/cli/commands/...
74+
75+
# Run with verbose output
76+
go test -v ./cli/cli/commands/...
77+
```
78+
79+
## Key source locations
80+
81+
| Component | Path |
82+
|-----------|------|
83+
| CLI entry point | `cli/cli/main.go` |
84+
| CLI commands | `cli/cli/commands/` |
85+
| Engine launcher | `engine/launcher/` |
86+
| API container launcher | `core/launcher/` |
87+
| Container engine abstraction | `container-engine-lib/` |
88+
| gRPC API definitions | `api/protobuf/` |
89+
| Version constant | `kurtosis_version/kurtosis_version.go` |
90+
91+
## Module dependency order
92+
93+
The monorepo has multiple Go modules. If you change a dependency, rebuild in order:
94+
95+
```
96+
container-engine-lib
97+
→ contexts-config-store
98+
→ grpc-file-transfer
99+
→ name-generator
100+
→ api
101+
→ metrics-library
102+
→ engine
103+
→ core
104+
→ cli
105+
```
106+
107+
Most CLI-only changes just need `go build ./cli/cli/`.
108+
109+
## Common issues
110+
111+
- **`go build` fails with import errors**: Run `go mod tidy` in the failing module directory
112+
- **CLI shows wrong version**: The version comes from `kurtosis_version/kurtosis_version.go` — it's compiled into the binary
113+
- **Engine image mismatch**: The CLI pulls engine images matching its compiled version. For dev testing with custom images, see the `k8s-dev-deploy` skill

‎skills/docker-debug/SKILL.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
name: docker-debug
3+
description: Debug Kurtosis running on local Docker. Inspect engine, API container, and service logs. Diagnose container crashes, port conflicts, and networking issues. Use when kurtosis commands fail or services aren't reachable on Docker.
4+
compatibility: Requires Docker and kurtosis CLI.
5+
metadata:
6+
author: ethpandaops
7+
version: "1.0"
8+
---
9+
10+
# Docker Debug
11+
12+
Diagnose and fix issues with Kurtosis running on a local Docker engine.
13+
14+
## Quick triage
15+
16+
```bash
17+
# Check engine is running
18+
kurtosis engine status
19+
20+
# List all kurtosis containers
21+
docker ps -a --filter "label=app.kubernetes.io/managed-by=kurtosis" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
22+
23+
# If no label filter works, grep for kurtosis
24+
docker ps -a | grep kurtosis
25+
```
26+
27+
## Engine issues
28+
29+
### Engine won't start
30+
31+
```bash
32+
# Check if old engine is still running
33+
docker ps -a | grep kurtosis-engine
34+
35+
# Check engine logs
36+
docker logs $(docker ps -aq --filter "name=kurtosis-engine") 2>&1 | tail -50
37+
38+
# Nuclear option: stop and remove all kurtosis containers
39+
kurtosis engine stop
40+
docker ps -a | grep kurtosis | awk '{print $1}' | xargs -r docker rm -f
41+
kurtosis engine start
42+
```
43+
44+
### Engine version mismatch
45+
46+
```bash
47+
# Check CLI version
48+
kurtosis version
49+
50+
# Check running engine version
51+
kurtosis engine status
52+
53+
# Force restart with matching version
54+
kurtosis engine restart
55+
```
56+
57+
## Enclave / API container issues
58+
59+
The API container (core/APIC) runs inside each enclave and manages services.
60+
61+
```bash
62+
# List enclaves
63+
kurtosis enclave ls
64+
65+
# Find the APIC container for an enclave
66+
docker ps -a | grep "kurtosis-api"
67+
68+
# View APIC logs (most useful for debugging enclave creation failures)
69+
docker logs $(docker ps -aq --filter "name=kurtosis-api") 2>&1 | tail -100
70+
```
71+
72+
## Service debugging
73+
74+
```bash
75+
# List services in an enclave
76+
kurtosis enclave inspect <enclave-name>
77+
78+
# View service logs
79+
kurtosis service logs <enclave-name> <service-name>
80+
81+
# Follow logs in real time
82+
kurtosis service logs <enclave-name> <service-name> -f
83+
84+
# Shell into a running service
85+
kurtosis service shell <enclave-name> <service-name>
86+
87+
# Execute a command in a service
88+
kurtosis service exec <enclave-name> <service-name> -- <command>
89+
```
90+
91+
## Port and networking issues
92+
93+
```bash
94+
# Check mapped ports for a service
95+
kurtosis enclave inspect <enclave-name>
96+
97+
# Verify port is actually listening inside the container
98+
kurtosis service exec <enclave-name> <service-name> -- netstat -tlnp
99+
100+
# Test connectivity between services (from inside a service)
101+
kurtosis service exec <enclave-name> <service-name> -- wget -qO- http://<other-service>:<port>/endpoint
102+
```
103+
104+
## File artifacts
105+
106+
```bash
107+
# List file artifacts in an enclave
108+
kurtosis enclave inspect <enclave-name>
109+
110+
# Download a file artifact for inspection
111+
kurtosis files download <enclave-name> <artifact-name> /tmp/artifact-output
112+
```
113+
114+
## Common problems
115+
116+
| Symptom | Likely cause | Fix |
117+
|---------|-------------|-----|
118+
| `engine not running` | Engine crashed or was stopped | `kurtosis engine start` |
119+
| Port conflict on start | Old container holding the port | `docker ps -a \| grep kurtosis \| awk '{print $1}' \| xargs docker rm -f` |
120+
| Service unreachable | Wrong port or service not ready | Check `kurtosis enclave inspect` for mapped ports |
121+
| `image not found` | Image not pulled or tag wrong | Check image name in Starlark, try `docker pull <image>` |
122+
| Enclave creation hangs | APIC crash or image pull issue | Check APIC logs: `docker logs` on the kurtosis-api container |
123+
124+
## Cleanup
125+
126+
```bash
127+
# Remove a specific enclave
128+
kurtosis enclave rm <enclave-name>
129+
130+
# Remove all enclaves and clean up
131+
kurtosis clean -a
132+
133+
# Full nuclear clean (if kurtosis clean fails)
134+
docker ps -a | grep kurtosis | awk '{print $1}' | xargs -r docker rm -f
135+
docker network ls | grep kurtosis | awk '{print $1}' | xargs -r docker network rm
136+
kurtosis engine start
137+
```

‎skills/enclave-inspect/SKILL.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
name: enclave-inspect
3+
description: Inspect and manage Kurtosis enclaves. List enclaves, view services and ports, examine file artifacts, dump enclave state for debugging, and clean up. Use when you need to understand what's running inside an enclave or export its state.
4+
compatibility: Requires kurtosis CLI with a running engine.
5+
metadata:
6+
author: ethpandaops
7+
version: "1.0"
8+
---
9+
10+
# Enclave Inspect
11+
12+
Inspect and manage Kurtosis enclaves and their contents.
13+
14+
## List enclaves
15+
16+
```bash
17+
kurtosis enclave ls
18+
```
19+
20+
Output shows enclave name, UUID, status (RUNNING/STOPPED), and creation time.
21+
22+
## Inspect an enclave
23+
24+
```bash
25+
kurtosis enclave inspect <enclave-name>
26+
```
27+
28+
This shows:
29+
- **File Artifacts** — uploaded files and rendered templates
30+
- **User Services** — running containers with their ports and status
31+
32+
## Services
33+
34+
### View service details
35+
36+
```bash
37+
# Full enclave inspection (shows all services with ports)
38+
kurtosis enclave inspect <enclave-name>
39+
40+
# View logs for a service
41+
kurtosis service logs <enclave-name> <service-name>
42+
43+
# Follow logs in real time
44+
kurtosis service logs <enclave-name> <service-name> -f
45+
46+
# Shell into a service
47+
kurtosis service shell <enclave-name> <service-name>
48+
49+
# Run a command in a service
50+
kurtosis service exec <enclave-name> <service-name> -- <command>
51+
```
52+
53+
### Access service ports
54+
55+
The `inspect` output shows port mappings like:
56+
57+
```
58+
http: 8545/tcp -> http://127.0.0.1:61817
59+
```
60+
61+
This means port 8545 inside the container is mapped to localhost:61817. On Kubernetes with gateway running, these are forwarded through the gateway.
62+
63+
## File artifacts
64+
65+
File artifacts are named blobs of files stored in the enclave.
66+
67+
```bash
68+
# List artifacts (shown in enclave inspect)
69+
kurtosis enclave inspect <enclave-name>
70+
71+
# Download an artifact to local disk
72+
kurtosis files download <enclave-name> <artifact-name> /tmp/output-dir
73+
74+
# Upload a local file as an artifact
75+
kurtosis files upload <enclave-name> /path/to/local/file
76+
```
77+
78+
## Dump enclave state
79+
80+
Export the full enclave state for offline debugging:
81+
82+
```bash
83+
kurtosis enclave dump <enclave-name> /tmp/enclave-dump
84+
```
85+
86+
This exports:
87+
- Service logs
88+
- Service configurations
89+
- File artifacts
90+
- Enclave metadata
91+
92+
Useful for sharing with others to debug issues.
93+
94+
## Enclave lifecycle
95+
96+
```bash
97+
# Create an enclave (usually done by kurtosis run)
98+
kurtosis enclave add <enclave-name>
99+
100+
# Stop an enclave (preserves state)
101+
kurtosis enclave stop <enclave-name>
102+
103+
# Remove a specific enclave
104+
kurtosis enclave rm <enclave-name>
105+
106+
# Remove all enclaves
107+
kurtosis clean -a
108+
```
109+
110+
## Kubernetes-specific
111+
112+
On Kubernetes, each enclave is a namespace prefixed with `kt-`:
113+
114+
```bash
115+
# See enclave namespaces
116+
kubectl get ns | grep kt-
117+
118+
# See pods in an enclave
119+
kubectl get pods -n kt-<enclave-name>
120+
121+
# Describe a service pod
122+
kubectl describe pod <pod-name> -n kt-<enclave-name>
123+
124+
# View pod logs directly
125+
kubectl logs <pod-name> -n kt-<enclave-name>
126+
```

0 commit comments

Comments
 (0)