feat: configurable Vault storage key and write action (replace/append)

[cxdy]

latr currently sets the key to token when storing Linode API tokens in Vault, i.e:

➜  ~ vault read tokens/data/cxdy/linode-api -format=yaml | yq '.data'
data:
  pre-latr-token: REDACTED
  token: REDACTED
metadata:
  created_time: "2026-07-15T23:09:10.491815843Z"
  custom_metadata:
    current_linode_id: "12345678"
    label: linode-obs-k8s-cluster
    last_rotated_at: "2026-07-15T22:29:17Z"
    previous_linode_id: "0"
    rotation_count: "0"
  deletion_time: ""
  destroyed: false
  version: 8

This is unfortunate for many reasons, but a big one is being able to migrate in-place to using latr when you've already got API keys all over the place in Vault. This way, I can have an existing token at {mount}/data/tokens/api-token, but the data is my-api-token: REDACTED and latr can drop in and replace it when it's time. No need to go update Vault paths in your code to use latr.

This also adds in the action behavior:

• replace (default) - replaces the entire secret, so you're left with token: yOuRnEwApItOkEn
• append - appends the new token to the existing secret, so you're left with something more like the example at the top.

append sounds dangerous, yes, but we are practicing CAS (check-and-set) here to prevent situations where:

• latr reads version 1 of a secret
• latr merges the new key/value pair into version 1 of the secret
• latr writes the full map back ONLY IF the secret is still version 1
• If someone/something else wrote version 2 of the secret during that process, Vault will reject the write, and latr will retry up to 5 times (maxAppendCASAttempts in internal/vault/client.go)

[Copilot]

Pull request overview

This PR updates latr’s Vault KV v2 storage behavior to support configurable data keys and configurable write semantics (replace vs append with CAS), enabling in-place adoption for pre-existing Vault secrets without changing secret paths in downstream consumers.

Changes:

• Add storage.key (KV data key) and storage.action (replace/append) for Vault storage, with defaulting/normalization and config validation.
• Implement KV v2 append behavior via read-modify-write with CAS retries in the Vault client.
• Update docs/examples/tests to treat storage.path as relative to vault.mount_path (omit mount name and data/).

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/e2e/testdata/config-rotate.yaml	Update e2e config to use mount-relative Vault path.
test/e2e/testdata/config-dryrun.yaml	Update e2e config to use mount-relative Vault path.
test/e2e/testdata/config-daemon.yaml	Update e2e config to use mount-relative Vault path.
test/e2e/testdata/config-create.yaml	Update e2e config to use mount-relative Vault path.
README.md	Document mount-relative paths and new key/action fields and AppRole policy implications.
internal/vault/client.go	Implement configurable key + replace/append write actions with CAS retry logic.
internal/vault/client_test.go	Add/adjust tests for custom key, replace vs append behavior, and CAS retries.
internal/rotation/engine.go	Pass normalized key/action from storage config through to Vault client; log chosen values.
internal/rotation/engine_test.go	Update mocks and add coverage for custom key and append action.
internal/config/loader_test.go	Update config test data to use mount-relative Vault path.
internal/config/config.go	Add key/action fields, defaults/normalization, and storage validation.
internal/config/config_test.go	Add tests for defaults, normalization, and validation of new storage fields and path rules.
helm/latr/values.yaml	Update Helm values documentation for mount-relative path plus key/action.
helm/latr/README.md	Update Helm chart docs/examples for mount-relative Vault path.
examples/config.yaml	Update example config with mount-relative path and demonstrate key/action.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.