unkinben
123faf8bbf
Introduces the vault-tools monorepo: two Go CLIs that share a config file (~/.config/vault) and token cache (~/.cache/vault) for working with multiple Vault instances (contexts). - add shared/ library: config parsing (vctl.yaml/config.yaml, per-context overrides, slash contexts), token cache (0600/0700, atomic writes, path- traversal guards), and a small hand-rolled Vault HTTP client (login/renew) - add vctl: login/renew (single or --all), list, --method/--user overrides, no-echo password/token prompts, dynamic context completion - add vctx: resolve a context, set VAULT_ADDR/VAULT_TOKEN/VAULT_NAMESPACE and exec the vault CLI, passing remaining args through untouched - add unit tests across shared/, vctl and vctx command layers (config resolution, cache paths, vault client, --all iteration + error aggregation, vctx arg pass-through and env construction via fakeable exec/prompt seams) - add Makefile (build/test/completions/rpm, patch|minor|major version bumps), nfpm RPM packaging bundling bash/zsh/fish completions for both binaries - add Woodpecker pipelines: build/test/pre-commit on PRs, and a tag release that cross-compiles, builds+uploads the RPM to artifactapi, and cuts a Gitea release (serviceAccountName default, k8s resources on every step) - add README, per-command docs (docs/vctl.md, docs/vctx.md), AGENTS.md and an example config Claude-Session: https://claude.ai/code/session_015ur3i7D2azsMAWTSVABApv
101 lines
3.5 KiB
Markdown
101 lines
3.5 KiB
Markdown
# vault-tools
|
||
|
||
A Go monorepo of small CLI tools for working with multiple Vault instances
|
||
("contexts"). Both tools share a single config file (`~/.config/vault/`) and
|
||
token cache (`~/.cache/vault/`), so once a context is configured every tool
|
||
knows about it.
|
||
|
||
| Tool | Purpose |
|
||
| -------------------- | ----------------------------------------------------------------------- |
|
||
| [`vctl`](docs/vctl.md) | Log in to / renew Vault tokens per context and cache them on disk. |
|
||
| [`vctx`](docs/vctx.md) | Run the real `vault` CLI against a named context (sets `VAULT_ADDR`/`VAULT_TOKEN`/`VAULT_NAMESPACE`, then execs `vault`). |
|
||
|
||
See the per-command docs in [`docs/`](docs/) for full details.
|
||
|
||
## Quick start
|
||
|
||
```bash
|
||
# 1. Configure your vaults
|
||
mkdir -p ~/.config/vault
|
||
cat > ~/.config/vault/vctl.yaml <<'YAML'
|
||
defaults:
|
||
method: ldap
|
||
user: ben
|
||
contexts:
|
||
sydney:
|
||
address: https://vault.syd1.au.unkin.net
|
||
staging/sydney:
|
||
address: https://vault-staging.syd1.au.unkin.net
|
||
namespace: staging
|
||
YAML
|
||
|
||
# 2. Log in (prompts for password), caches a token under ~/.cache/vault/
|
||
vctl login sydney
|
||
vctl login --all # or log in to every context at once
|
||
|
||
# 3. Use the vault CLI against a context
|
||
vctx --context sydney kv put kv/foo/bar secret=baz
|
||
vctx --context staging/sydney kv list kv/
|
||
|
||
# 4. Keep tokens fresh
|
||
vctl renew --all
|
||
|
||
# See what's configured and which tokens are still valid
|
||
vctl list
|
||
```
|
||
|
||
## Configuration
|
||
|
||
Both tools read the first of `~/.config/vault/vctl.yaml` or
|
||
`~/.config/vault/config.yaml` that exists (`$XDG_CONFIG_HOME` honoured). The
|
||
file maps context names to a vault address plus optional per-context overrides
|
||
(`method`, `user`, `namespace`, `path`) with file-level `defaults`. Context
|
||
names may contain slashes, which nest on disk in the token cache. See
|
||
[docs/vctl.md](docs/vctl.md#configuration) for the full schema and resolution
|
||
rules.
|
||
|
||
Tokens are cached under `~/.cache/vault/<context>` (`$XDG_CACHE_HOME` honoured)
|
||
as JSON with restrictive permissions (files `0600`, dirs `0700`), storing the
|
||
token plus its accessor, policies, TTL/expiry and renewable flag.
|
||
|
||
## Layout
|
||
|
||
```
|
||
shared/ # config parsing, token cache, Vault HTTP client (shared lib + tests)
|
||
vctl/ # vctl CLI (main package)
|
||
vctx/ # vctx CLI (main package)
|
||
docs/ # per-command documentation
|
||
packaging/nfpm.yaml# nfpm spec (envsubst-templated) for the RPM (both binaries + completions)
|
||
scripts/build-rpm.sh
|
||
.woodpecker/ # CI: build, test, pre-commit (PR) + release (tag)
|
||
Makefile # build / test / completions / rpm / version-bump targets
|
||
```
|
||
|
||
## Building
|
||
|
||
```bash
|
||
make build # build vctl + vctx into dist/
|
||
make test # go test -race ./...
|
||
make completions # generate bash/zsh/fish completions into dist/completions/
|
||
make rpm # build + package an RPM (needs nfpm)
|
||
```
|
||
|
||
## Releasing
|
||
|
||
Releases run in Woodpecker on a `v*` tag. Bump and tag with:
|
||
|
||
```bash
|
||
make patch # or: make minor / make major
|
||
```
|
||
|
||
which creates the next semver tag and pushes it. The release pipeline then
|
||
tests, cross-compiles both binaries (linux/darwin × amd64/arm64), builds an RPM
|
||
(bundling shell completions), PUTs the RPM to the artifactapi local `rpm-internal`
|
||
yum repo, and cuts a Gitea release with the binaries + checksums attached.
|
||
|
||
## Installation
|
||
|
||
Install the RPM from the internal yum repo (ships both binaries plus
|
||
bash/zsh/fish completions), or grab a prebuilt binary from the Gitea release
|
||
assets.
|