One of the more useful changes in vault-ops was not about PKI itself. It was about script layout.

Repo:

The Problem

Over time, automation scripts grow versions almost by accident:

  • setup-vault-agent-app-config-v4.sh
  • setup-vault-agent-app-config-v5.sh
  • setup-vault-agent-app-config-v5.1.sh

That is normal during iteration. But once those names leak into notes, docs, or muscle memory, daily operations become messy:

  • it is easy to call the wrong version,
  • blog posts become stale fast,
  • and “which script is the real one?” becomes a recurring question.

The Fix

The repo now uses:

  • stable wrappers in infra/
  • versioned implementations in infra/versions/

So the operational entry point stays stable:

./infra/setup-vault-agent-app-config.sh
./infra/setup-vault-agent-mtls-client-config.sh
./infra/setup-vault-agent-proxy-config.sh

while the implementation can still evolve underneath that wrapper.

Why This Is Better

This gives me two things at once.

First, I keep history. I can still see and preserve earlier implementations instead of pretending the system was designed perfectly from the start.

Second, I get a cleaner interface for real operations. My README, my notes, and my runbooks can point to one stable script name.

That lowers the chance of operational mistakes, especially in a setup that already has enough moving parts:

  • offline root,
  • per-environment intermediates,
  • Vault server TLS,
  • admin certs,
  • per-app agent identities,
  • and proxy CA-chain refresh.

Why It Matters In Security Work

Security automation often fails in boring ways:

  • stale paths,
  • unclear entry points,
  • old commands copied from old notes,
  • and inconsistent assumptions across environments.

Stable wrappers are a small design choice, but they reduce exactly that kind of friction.

It also makes the blog easier to maintain. Older posts can refer to the stable command names and then link to the repo for the current implementation details.

That is a much better contract between documentation and operations.