|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file provides guidance to coding agents (e.g. Claude Code, claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Repository purpose |
| 6 | + |
| 7 | +Go module `kubestash.dev/cli` — the [KubeStash](https://kubestash.com/) command-line, distributed as a **`kubectl` plugin** (binary name `kubectl-kubestash`). Operators reach for this for the bits of KubeStash that don't fit cleanly as CRDs: ad-hoc restore, trigger-on-demand, snapshot download/view, repository unlock, debug introspection, cloning, encryption-key management, and v1→v2 manifest conversion. |
| 8 | + |
| 9 | +Sub-commands (registered in `pkg/root.go`): |
| 10 | + |
| 11 | +- `copy` — copy a snapshot/secret/volumesnapshot. |
| 12 | +- `trigger-backup` — manually trigger a `BackupConfiguration`. |
| 13 | +- `pause` / `resume` — pause/resume a `BackupConfiguration` or `BackupBatch`. |
| 14 | +- `download` — download snapshot data to a local path. |
| 15 | +- `manifest view` / `manifest restore` — inspect or apply manifest-only snapshots. |
| 16 | +- `unlock-repository` — clear stale restic locks. |
| 17 | +- `debug` — `debug backup`, `debug restore`, `debug operator`, `debug backupstorage`. |
| 18 | +- `clone` — `clone pvc` (and other resource clones). |
| 19 | +- `key` — `key add`, `key list`, `key remove`, `key update` (manage encryption keys on a `BackupStorage`). |
| 20 | +- `convert` — convert legacy Stash manifests to KubeStash. |
| 21 | + |
| 22 | +Plus `version` and `completion`. |
| 23 | + |
| 24 | +## Architecture |
| 25 | + |
| 26 | +- `cmd/kubectl-kubestash/main.go` — entry point; calls `pkg.NewCmd()`. |
| 27 | +- `pkg/` — one file per top-level subcommand, plus `*_<subverb>.go` for nested verbs (e.g. `add_key.go`, `clone_pvc.go`, `debug_backup.go`, `copy_secret.go`, `copy_volumesnapshot.go`). `root.go` registers them; `util.go`, `constants.go`, `completion.go` are shared. |
| 28 | +- `pkg/common/` — shared types and helpers used across subcommands: |
| 29 | + - `types.go`, `helpers.go`. |
| 30 | + - `dump/` — manifest-only "view" / "restore" payload generation. |
| 31 | +- `hack/`, `Makefile` — AppsCode build harness (everything runs inside `ghcr.io/appscode/golang-dev`). This binary builds for **5 platforms**: linux amd64/arm/arm64 plus `windows/amd64`, `darwin/amd64`, `darwin/arm64` (kubectl plugins need to run on operator workstations). |
| 32 | +- `vendor/` — checked-in deps. |
| 33 | + |
| 34 | +The binary uses the conventional `kubectl-kubestash` name so it auto-attaches under `kubectl kubestash` once on `$PATH`. There is no Docker image — this is a host CLI. |
| 35 | + |
| 36 | +Note: `GO_PKG := stash.appscode.dev` in the Makefile is a **historical** leftover from the Stash → KubeStash split; the Go module is `kubestash.dev/cli`. Leave the Makefile alone unless you're doing a coordinated cleanup. |
| 37 | + |
| 38 | +## Common commands |
| 39 | + |
| 40 | +All Make targets run inside `ghcr.io/appscode/golang-dev` — Docker must be running. |
| 41 | + |
| 42 | +- `make ci` — CI pipeline (verify-license, lint, build). |
| 43 | +- `make build` — build the host binary into `bin/<os>_<arch>/kubectl-kubestash`. |
| 44 | +- `make all-build` — build for every `BIN_PLATFORMS` (linux amd64/arm/arm64 + windows/amd64 + darwin/amd64 + darwin/arm64). |
| 45 | +- `make fmt`, `make lint`, `make unit-tests` / `make test` — standard. |
| 46 | +- `make verify` — `verify-gen verify-modules`; `go mod tidy && go mod vendor` must leave the tree clean. |
| 47 | +- `make add-license` / `make check-license` — manage license headers. |
| 48 | + |
| 49 | +There is **no container target**; this CLI does not ship as an image. |
| 50 | + |
| 51 | +Run a single Go test (requires a local Go toolchain): |
| 52 | + |
| 53 | +``` |
| 54 | +go test ./pkg/... -run TestName -v |
| 55 | +``` |
| 56 | + |
| 57 | +To use the CLI locally after building: |
| 58 | + |
| 59 | +``` |
| 60 | +PATH=$PWD/bin/<os>_<arch>:$PATH kubectl kubestash --help |
| 61 | +``` |
| 62 | + |
| 63 | +## Conventions |
| 64 | + |
| 65 | +- Module path is `kubestash.dev/cli` (vanity URL). The Makefile's `GO_PKG := stash.appscode.dev` is **historical** — do not "fix" it without a coordinated build-tooling change. |
| 66 | +- License: `LICENSE.md` (AppsCode). New files need the standard "Copyright AppsCode Inc. and Contributors" header (`make add-license`). |
| 67 | +- Sign off commits (`git commit -s`); contributions follow the DCO (`DCO` file). |
| 68 | +- Vendor directory is checked in — `go mod tidy && go mod vendor` must leave the tree clean (enforced by `verify-modules`). |
| 69 | +- Binary name is `kubectl-kubestash` so kubectl picks it up as a plugin; do not rename without also moving the `cmd/` directory. |
| 70 | +- New subcommand: add a `pkg/<name>.go` (or `pkg/<name>_<sub>.go` for nested verbs), register it in `pkg/root.go`'s `NewCmd()`, and reuse `pkg/common/` helpers rather than re-implementing kube client setup or output formatting. |
| 71 | +- Builds linux/windows/darwin host binaries; do not pull in linux-only or cgo deps. |
| 72 | +- API types come from `kubestash.dev/apimachinery`; do not redefine them here. |
0 commit comments