cerc-io
/
stack-orchestrator
mirror of https://github.com/cerc-io/stack-orchestrator
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

Split documentation: README for users, CLAUDE.md for agents 

README.md: deployment types, external stacks, commands, spec.yml reference
CLAUDE.md: implementation details, code locations, codebase navigation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
A. F. Dudley 2026-02-03 01:17:10 -05:00
parent e0f271347b
commit efdcfbb21d
2 changed files with 71 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
CLAUDE.md
View File

@ -47,43 +47,29 @@ This approach treats the human-AI collaboration as a form of **conversational li
## Architecture: k8s-kind Deployments ## Architecture: k8s-kind Deployments
### One Cluster Per Host ### One Cluster Per Host
There is **one Kind cluster per host by design**. Multiple deployments (stacks) share this cluster. Never request or expect separate clusters for different deployments on the same host. One Kind cluster per host by design. Never request or expect separate clusters.
- `create_cluster()` in `helpers.py` reuses any existing cluster - `create_cluster()` in `helpers.py` reuses any existing cluster
- Cluster name in deployment.yml is an identifier, not a cluster request - `cluster-id` in deployment.yml is an identifier, not a cluster request
- All deployments share ingress controller, etcd, certificates - All deployments share: ingress controller, etcd, certificates
### External Stacks ### Stack Resolution
External stacks are detected by filesystem path existence (`Path(stack).exists()`). Required structure: - External stacks detected via `Path(stack).exists()` in `util.py`
- Config/compose resolution: external path first, then internal fallback
- External path structure: `stack_orchestrator/data/stacks/<name>/stack.yml`
``` ### Secret Generation Implementation
<repo>/ - `GENERATE_TOKEN_PATTERN` in `deployment_create.py` matches `$generate:type:length$`
stack_orchestrator/data/ - `_generate_and_store_secrets()` creates K8s Secret
stacks/<name>/stack.yml - `cluster_info.py` adds `envFrom` with `secretRef` to containers
compose/docker-compose-<pod>.yml - Non-secret config written to `config.env`
deployment/spec.yml
```
Config/compose resolution: external path first, then internal fallback. ### Key Files (for codebase navigation)
- `deployment_create.py`: `deploy create` command, secret generation
### Deployment Lifecycle - `deployment.py`: `deployment start/stop/restart` commands
- `deploy create`: Initializes deployment dir, generates cluster-id, processes spec.yml - `deploy_k8s.py`: K8s deployer, cluster management calls
- `deployment start`: Creates/reuses cluster, deploys K8s resources - `helpers.py`: `create_cluster()`, etcd cleanup, kind operations
- `deployment restart`: Git pulls stack repo, syncs spec, redeploys (preserves data) - `cluster_info.py`: K8s resource generation (Deployment, Service, Ingress)
- `deployment stop`: Removes K8s resources (cluster persists)
### Secret Generation
`$generate:type:length$` tokens in spec.yml config section:
- Processed during `deploy create`
- Stored in K8s Secret `<deployment>-generated-secrets`
- Injected via `envFrom` with `secretRef`
- Non-secret config goes to `config.env`
### Key Files
- `spec.yml`: Deployment specification (in stack repo)
- `deployment.yml`: Cluster-id, stack-source path (generated)
- `config.env`: Non-secret environment variables (generated)
- `kind-config.yml`: Kind cluster configuration (generated)
## Insights and Observations ## Insights and Observations

53
README.md
View File

@ -71,6 +71,59 @@ The various [stacks](/stack_orchestrator/data/stacks) each contain instructions
- [laconicd with console and CLI](stack_orchestrator/data/stacks/fixturenet-laconic-loaded) - [laconicd with console and CLI](stack_orchestrator/data/stacks/fixturenet-laconic-loaded)
- [kubo (IPFS)](stack_orchestrator/data/stacks/kubo) - [kubo (IPFS)](stack_orchestrator/data/stacks/kubo)
## Deployment Types
- **compose**: Docker Compose on local machine
- **k8s**: External Kubernetes cluster (requires kubeconfig)
- **k8s-kind**: Local Kubernetes via Kind - one cluster per host, shared by all deployments
## External Stacks
Stacks can live in external git repositories. Required structure:
```
<repo>/
stack_orchestrator/data/
stacks/<stack-name>/stack.yml
compose/docker-compose-<pod-name>.yml
deployment/spec.yml
```
## Deployment Commands
```bash
# Create deployment from spec
laconic-so --stack <path> deploy create --spec-file <spec.yml> --deployment-dir <dir>
# Start (creates cluster on first run)
laconic-so deployment --dir <dir> start
# GitOps restart (git pull + redeploy, preserves data)
laconic-so deployment --dir <dir> restart
# Stop
laconic-so deployment --dir <dir> stop
```
## spec.yml Reference
```yaml
stack: stack-name-or-path
deploy-to: k8s-kind
network:
http-proxy:
- host-name: app.example.com
routes:
- path: /
proxy-to: service-name:port
acme-email: admin@example.com
config:
ENV_VAR: value
SECRET_VAR: $generate:hex:32$ # Auto-generated, stored in K8s Secret
volumes:
volume-name:
```
## Contributing ## Contributing
See the [CONTRIBUTING.md](/docs/CONTRIBUTING.md) for developer mode install. See the [CONTRIBUTING.md](/docs/CONTRIBUTING.md) for developer mode install.