unkinben
9e7687fccb
ci/woodpecker/push/apply Pipeline was successful
## Why netbox_user_management authenticates to NetBox to reconcile service users + permissions on every apply. It must not depend on a second static admin token, and it must not break when the engine rotates its admin seed (`netbox/config/rotate` mints a fresh admin token and deletes the old one). The durable shape: keep exactly ONE static admin token, and have the netbox engine mint an ephemeral, user-admin-capable token that the e-breuninger provider uses to manage users. ## How - `module.netbox_user_mgmt_role` creates `netbox/roles/vault-user-mgmt`, a write-enabled role for a pre-existing NetBox superuser named by `user_mgmt_username`. Minted tokens authenticate AS that superuser (NetBox tokens carry no scope beyond `write_enabled`; the user's permissions apply), so they can create users. - `netbox_user_management` reads `netbox/creds/vault-user-mgmt` and configures the netbox provider with the minted token. When `user_mgmt_username` is unset it falls back to the single static `admin_token` (a `check` block warns that rotation would then break it) - a bootstrap/degraded path, never a second static token. - Grant the deployer `read` on `netbox/creds/vault-user-mgmt` (the one deliberate exception to the admin policy's `netbox/creds/*` exclusion). - Keep the bare-token + `token_version`-match postconditions on the single static admin token. ## Feasibility constraints (worked through, documented in-module) 1. **The engine CAN mint a user-admin token** - roles map to a pre-existing user with only a `write_enabled` gate (`vault-plugin-secrets-netbox` `path_roles.go`, `client.go` `MintToken`); point it at a superuser and minted tokens can manage users. 2. **Token transits state.** The hashicorp/vault provider (5.6.0) exposes ephemeral resources for KV only, not dynamic engine creds, so the mint is read via the `vault_generic_secret` DATA source: the short-lived token is written to state (sensitive, lease-revoked) and re-minted each plan. Migrate to an ephemeral resource once the vault provider ships a dynamic-secret one. 3. **A clean single fresh apply is not possible.** A provider cannot be configured from a role created in the same run (data sources don't defer; OpenTofu 1.11 defers only ephemeral resources, which the vault provider doesn't offer here). So enabling the dynamic path on a backend needs a one-time targeted bootstrap of the mount + role, then normal applies. Documented in `config/netbox_secret_backend/netbox.yaml`. ## Operator follow-up - Repair the live mount first (unchanged): `vault write netbox/config token=<BARE>` (the mount uses `ignore_changes=[token]`), keep `token_version=2`. - To enable dynamic minting: set `user_mgmt_username` to the pre-existing superuser, apply the deployer creds policy, then bootstrap once: `tofu apply -target=...netbox_secret_backend -target=...netbox_user_mgmt_role`, then apply normally. Until then user management stays on the static token (non-breaking, with a warning). Reviewed-on: #119 Co-authored-by: Ben Vincent <ben@unkin.net> Co-committed-by: Ben Vincent <ben@unkin.net>
49 lines
2.9 KiB
YAML
49 lines
2.9 KiB
YAML
# Mounts the netbox token secrets engine at "netbox" and writes its config.
|
|
# The seeded NetBox admin token is sensitive and read from KV, not stored here:
|
|
# kv/service/vault/au/syd1/secret_backend/netbox/config
|
|
# -> key: admin_token (required) the SINGLE static admin credential
|
|
#
|
|
# admin_token must be a BARE NetBox token with NO scheme prefix: do not prepend
|
|
# "Bearer " or "Token ". NetBox infers the version from the value's nbt_ prefix,
|
|
# so one bare token authenticates under either scheme; the plugin adds the keyword
|
|
# itself. A prefixed value yields a malformed header + 403.
|
|
#
|
|
# Populate admin_token with a purpose-built NetBox superuser token (add_user +
|
|
# add_token + grant_token, or superuser) BEFORE applying, then run
|
|
# `vault write -f netbox/config/rotate` after the first apply so only Vault holds
|
|
# the live admin token.
|
|
#
|
|
# Only ONE static admin token exists. netbox_user_management does NOT re-read this
|
|
# token; instead the engine mints it a short-lived user-admin token per apply from
|
|
# netbox/roles/vault-user-mgmt (see user_mgmt_username below), so rotating
|
|
# admin_token never breaks user management. Set user_mgmt_username to the
|
|
# pre-existing NetBox superuser the static admin_token belongs to (or another
|
|
# superuser). Leaving it unset falls back to using admin_token directly, which is
|
|
# only a bootstrap/degraded path and breaks after rotation.
|
|
#
|
|
# Bootstrap ordering: the vault-user-mgmt role must exist before the netbox
|
|
# provider is configured from its creds, so on a brand-new backend apply the mount
|
|
# + role first (e.g. `tofu apply -target=...netbox_secret_backend
|
|
# -target=...netbox_user_mgmt_role`) once, then apply normally.
|
|
#
|
|
# token_version 2 is the NetBox 4.6.5 default and requires API_TOKEN_PEPPERS to
|
|
# be configured on the NetBox server; set token_version: 1 here if the server
|
|
# has no peppers. token_version does NOT change how the plugin authenticates its
|
|
# own calls (that scheme comes from the admin_token value's nbt_ prefix); it only
|
|
# sets the version of the per-user tokens the engine mints. It must still MATCH
|
|
# the admin_token kind: nbt_ v2 token -> token_version 2; bare v1 token -> 1.
|
|
#
|
|
# The mount uses ignore_changes=[token], so editing KV alone does NOT reach the
|
|
# live mount. To push a corrected/rotated admin token into a running mount:
|
|
# vault write netbox/config token=<BARE_TOKEN>
|
|
# (netbox_url/token_version are preserved on a partial update). Do NOT -replace
|
|
# the mount to force a re-read - that recreates it and drops all roles/config.
|
|
description: "NetBox ephemeral scoped API token engine"
|
|
netbox_url: "https://netbox.k8s.syd1.au.unkin.net"
|
|
token_version: 2
|
|
request_timeout_seconds: 30
|
|
# Set to the pre-existing NetBox superuser admin_token belongs to, to mint the
|
|
# user-management credential dynamically (recommended). Until set, user management
|
|
# uses admin_token directly and a check block warns that rotation will break it.
|
|
# user_mgmt_username: "vault-netbox-admin"
|