102 lines
3.5 KiB
Markdown
102 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/vcm/`) and
|
|
token cache (`~/.cache/vcm/`), so once a context is configured every tool
|
|
knows about it.
|
|
|
|
| Tool | Purpose |
|
|
| -------------------- | ----------------------------------------------------------------------- |
|
|
| [`vcm`](docs/vcm.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/vcm
|
|
cat > ~/.config/vcm/config.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/vcm/
|
|
vcm login sydney
|
|
vcm 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
|
|
vcm renew --all
|
|
|
|
# See what's configured and which tokens are still valid
|
|
vcm list
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Both tools read `~/.config/vcm/config.yaml` (`$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/vcm.md](docs/vcm.md#configuration) for the full schema and resolution
|
|
rules.
|
|
|
|
Tokens are cached under `~/.cache/vcm/<context>` (`$XDG_CACHE_HOME` honoured)
|
|
with restrictive permissions (files `0600`, dirs `0700`), storing the token
|
|
plus its accessor, policies, TTL/expiry and renewable flag. Files are
|
|
encrypted with a per-boot key in the kernel user keyring; after a reboot the
|
|
tokens show as locked, so run `vcm login` again.
|
|
|
|
## Layout
|
|
|
|
```
|
|
shared/ # config parsing, token cache, Vault HTTP client (shared lib + tests)
|
|
vcm/ # vcm 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 vcm + 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, builds both binaries for linux 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.
|