unkin-agent
618e1414e4
Replace the nfpm script with .goreleaser.yaml as the single driver for the RPM, the raw release binaries the compiler initContainer fetches, archives and checksums. Add an end-to-end test that issues a certificate from a real Vault dev server over approle.
102 lines
4.8 KiB
Markdown
102 lines
4.8 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project Overview
|
|
|
|
`certmanager` issues Vault PKI certificates for Puppet-managed nodes. It is a
|
|
drop-in replacement for the Python `certmanager` script that
|
|
`profiles::helpers::certmanager` used to render into a venv.
|
|
|
|
## The contract
|
|
|
|
`profiles::pki::vault` (puppet-prod) calls the binary during catalog
|
|
compilation:
|
|
|
|
```
|
|
/usr/local/bin/certmanager <fqdn> --alt-names "host,fqdn" --ip-sans "127.0.0.1,<ip>" --expiry-days 90 --json
|
|
```
|
|
|
|
`generate()` runs with `failonfail: true, combine: true`. `combine: true` dups
|
|
stderr onto stdout at spawn, so anything on stderr is spliced into the JSON
|
|
stream and `parsejson()` fails — breaking the compile with a parse error rather
|
|
than a clean failure. Two rules follow:
|
|
|
|
- the success path writes the JSON document to stdout and nothing to stderr
|
|
(`TestRunSuccessWritesNothingToStderr` guards this);
|
|
- every failure exits non-zero, with the message on stderr and stdout empty.
|
|
|
|
## Structure
|
|
|
|
```
|
|
cmd/certmanager/main.go # CLI (flattened: the positional arg is the command)
|
|
cmd/certmanager/main_test.go # end-to-end tests against an httptest Vault stub
|
|
test/integration/ # end-to-end tests against a real Vault dev server
|
|
internal/config/ # YAML config: parsing, defaults, validation
|
|
internal/pki/ # issue request/response + the JSON output shape
|
|
internal/vault/ # authenticated HTTP client (approle, kubernetes)
|
|
Makefile # build / test / lint / completions / version bump
|
|
.goreleaser.yaml # single release driver: binaries + RPM + Gitea release
|
|
scripts/integration-test.sh # runs the integration test against a Vault dev server
|
|
.woodpecker/ # CI: build, test, integration, pre-commit (PR) + release (tag)
|
|
dist/ # build output: binaries, RPM, checksums (not committed)
|
|
```
|
|
|
|
## Code Patterns
|
|
|
|
- **`run(args, stdout, stderr) int`** is the testable entry point; `main()` only
|
|
wires it to the real streams and `os.Exit`. Cobra runs with `SilenceUsage` and
|
|
`SilenceErrors` so nothing reaches stderr unless the run failed.
|
|
- **Flat CLI**: the root command takes `common_name` positionally
|
|
(`cobra.ExactArgs(1)`). Only `completion` and `help` are subcommands.
|
|
- **`parseList`** splits comma lists, trims whitespace, drops empty tokens.
|
|
- **`config.Load`** applies defaults (`auth_method: approle`, `jwt_path`) then
|
|
`Validate()`, which names the offending key and rejects an unknown
|
|
`auth_method` before any network call.
|
|
- **`vault.New`** authenticates once and never falls back between auth methods.
|
|
Every request is bounded by `vault.timeout` (default 30s) — the Python set no
|
|
timeout, so a black-holed Vault hung the whole catalog compile.
|
|
- **`config.defaultPath`** is baked in at build time via
|
|
`-X ...internal/config.defaultPath=` (`make build CONFIG_PATH=...`).
|
|
|
|
## Deliberate deviations from the Python script
|
|
|
|
- Emits `ca_certificate`; the Python did not, so Puppet's
|
|
`/etc/pki/tls/vault/ca_certificate.crt` was silently never populated.
|
|
- `output_path` is read from under `vault:` where it is actually written. The
|
|
Python declared it at the top level but read it from the unwrapped `vault`
|
|
dict, so it never resolved.
|
|
- HTTP timeouts on every request.
|
|
- `tls_skip_verify` is a config key defaulting to `true`, preserving the
|
|
Python's `verify=False` while letting it be flipped without a code change.
|
|
- Non-zero exit on every failure path.
|
|
- `ldap` and `token` auth methods are gone; only `approle` and `kubernetes`
|
|
exist.
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
make test # go test -v -race ./...
|
|
make integration-test # -tags=integration, against a real Vault dev server
|
|
```
|
|
|
|
Unit tests stub Vault with `httptest.NewTLSServer` — no live Vault is required.
|
|
Coverage: the golden `--json` stdout document, stderr emptiness on success,
|
|
rejected logins for both auth methods, missing/empty JWT, unknown
|
|
`auth_method`, a non-200 issue response, request timeout, TLS verification when
|
|
enabled, file and zip output, and the comma-list parsing table.
|
|
|
|
`test/integration` (build tag `integration`) provisions a real PKI mount,
|
|
policy and `bind_secret_id: false` approle role on a Vault dev server, then
|
|
runs the binary with Puppet's argv and asserts exit code, empty stderr, the
|
|
four JSON keys, the parsed X.509 CN/SANs/lifetime, and that a refused name
|
|
exits non-zero with empty stdout. Dev mode is plain HTTP, so it does not
|
|
exercise the TLS path.
|
|
|
|
## Gotchas
|
|
|
|
- Changing the JSON key set or key order breaks `parsejson()` in
|
|
`profiles::pki::vault`; `TestRunJSONGolden` pins the exact bytes.
|
|
- `alt_names` and `ip_sans` are always sent, as empty strings when unset, to
|
|
match what the Python posted.
|
|
- The RPM owns `/usr/local/bin/certmanager` as a symlink; the Puppet class that
|
|
manages that path must be retired in the same change that ships the RPM.
|