From 581ceaea948bdf0884efb741067e67935a5f9c6f Mon Sep 17 00:00:00 2001 From: "A. F. Dudley" Date: Tue, 3 Feb 2026 13:52:11 -0500 Subject: [PATCH] docs: Add cluster and volume management section Document that: - Volumes persist across cluster deletion by design - Only use --delete-volumes when explicitly requested - Multiple deployments share one kind cluster - Use --skip-cluster-management to stop single deployment Co-Authored-By: Claude Opus 4.5 --- docs/deployment_patterns.md | 39 +++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/deployment_patterns.md b/docs/deployment_patterns.md index 68484f13..cbb8cdca 100644 --- a/docs/deployment_patterns.md +++ b/docs/deployment_patterns.md @@ -124,3 +124,42 @@ When using Ansible for deployments, pass the token from a credentials file: 1. laconic-so reads the `registry-credentials` config from spec.yml 2. Creates a Kubernetes `docker-registry` secret named `{deployment}-registry` 3. The deployment's pods reference this secret for image pulls + +## Cluster and Volume Management + +### Stopping Deployments + +The `deployment stop` command has two important flags: + +```bash +# Default: stops deployment, deletes cluster, PRESERVES volumes +laconic-so deployment --dir my-deployment stop + +# Explicitly delete volumes (USE WITH CAUTION) +laconic-so deployment --dir my-deployment stop --delete-volumes +``` + +### Volume Persistence + +Volumes persist across cluster deletion by design. This is important because: +- **Data survives cluster recreation**: Ledger data, databases, and other state are preserved +- **Faster recovery**: No need to re-sync or rebuild data after cluster issues +- **Safe cluster upgrades**: Delete and recreate cluster without data loss + +**Only use `--delete-volumes` when:** +- You explicitly want to start fresh with no data +- The user specifically requests volume deletion +- You're cleaning up a test/dev environment completely + +### Shared Cluster Architecture + +In kind deployments, multiple stacks share a single cluster: +- First `deployment start` creates the cluster +- Subsequent deployments reuse the existing cluster +- `deployment stop` on ANY deployment deletes the shared cluster +- Other deployments will fail until cluster is recreated + +To stop a single deployment without affecting the cluster: +```bash +laconic-so deployment --dir my-deployment stop --skip-cluster-management +```