certmanager/AGENTS.md

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 + ca_chain requests and the output shapes
internal/vault/               # HTTP client: approle, kubernetes, unauthenticated
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. run derives interactivity from isTerminal(stdout) and hands it to runWith, which tests call directly to pin either side. isTerminal is a terminal ioctl (x/term.IsTerminal), not a character-device stat: /dev/null and the /dev/null the runtime reopens onto a closed fd 1 are character devices, and a stat would hand both of them the help-and-exit-zero path.
• Flat CLI: the root command takes common_name positionally (cobra.MaximumNArgs(1)); no args prints help only when stdout is a terminal and otherwise fails, args-less flags fail. ca, completion and help are the only subcommands; --config is persistent so ca shares it, and an explicitly empty --config is rejected.
• ca is unauthenticated: GET {addr}/v1/{mount}/ca_chain sends no X-Vault-Token and loads the config through config.LoadCA, which requires only vault.addr. The body is parsed as PEM, never sniffed — Vault labels it application/pkix-cert. It prints raw PEM: Puppet uses it as file content.
• 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.Resolve picks the config: --config, then $XDG_CONFIG_HOME/certmanager/config.yaml, then $HOME/.config/certmanager/config.yaml (both only if the file exists), then config.FallbackPath() — baked in at build time via -X ...internal/config.defaultPath= (make build CONFIG_PATH=...). Under generate() the puppet user has no usable home, so the baked path is what resolves.

Deliberate deviations from the Python script

• The CA is served by certmanager ca from the mount's /ca_chain, not welded to issuance. issuing_ca is the intermediate only, and deriving the CA from an issue response would pin CA rotation to each node's 90 day renewal.
• full_chain is leaf first; the Python put the issuer first.
• 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

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.

hermeticEnv, the subprocess environment those tests share, sits outside the tag in hermetic_env_test.go so a plain go test ./... guards it. It replaces the ambient environment rather than extending it; its test asserts exactly that, because a helper that leaked HOME would point the binary at a real Vault and only the tagged tests would notice.

TestBareInvocationHelpsOnlyATerminal drives the built binary once per kind of fd 1 — pipe, regular file, unix socket, /dev/null, a closed fd 1 and a pty allocated from /dev/ptmx — and only the pty may exit zero with help on stdout. The pty is what pins the true branch: CI containers have no controlling terminal, so a test that reached for /dev/tty would skip.

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.