Skip to content

ADR-011: mTLS Certificate Authority Strategy

Status: Approved (amended to use Vault)

Date: 2026-06-30

Decision

Use HashiCorp Vault PKI running in the management plane as the certificate authority for client Alloy mTLS certificates. Vault also serves as the management-plane secret store. Each client cluster runs cert-manager with a Vault issuer to request per-client, short-lived certificates authenticated via Kubernetes ServiceAccount tokens.

Rationale

  • Unified secrets and PKI platform: Vault handles both management-plane secrets and client mTLS certificates, reducing the number of components to operate.
  • Enterprise-grade PKI: fine-grained PKI roles, TTLs, and revocation capabilities.
  • Kubernetes-native authentication: client clusters authenticate to Vault using Kubernetes auth with bound ServiceAccounts, avoiding static credential distribution.
  • Future-proof: Vault PKI scales to additional use cases (service mesh, workload identity, dynamic database credentials) without changing the CA architecture.
  • Manual unseal for MVP: acceptable for the initial staging setup; auto-unseal (cloud KMS) will be adopted before production.

Alternatives Considered

Option Pros Cons
cert-manager + internal CA in each client cluster Simple, no central CA Hard to rotate root CA, no central revocation, trust distribution complexity
step-ca Lightweight, ACME-native, easy to operate Separate from secret store; another component to maintain
Manual certificate distribution Full control Error-prone, hard to rotate at scale

Architecture

Management Plane
└── Vault
    ├── secret/          (KV v2 for management-plane secrets)
    ├── pki/             (Root + intermediate CA for client mTLS)
    ├── auth/kubernetes/ (Kubernetes auth for management-plane cluster)
    └── auth/kubernetes-clients/ (Shared Kubernetes auth for client clusters)

Client Cluster
└── cert-manager
    └── ClusterIssuer (Vault)
        └── Certificate resources
            └── Alloy client certificate (signed by Vault PKI)

Vault PKI Configuration

  • Root CA generated inside Vault for the MVP.
  • Single PKI role client-mtls for client certificates, constrained by allowed domains and TTL.
  • Per-client Kubernetes auth roles bound to per-client ServiceAccounts.
  • Certificate lifetime: 720h (30 days) with renewal 168h (7 days) before expiry.

Per-Client Scoping

  • One shared Kubernetes auth backend (kubernetes-clients) for all client clusters.
  • Each client has a dedicated Vault role bound to a specific ServiceAccount name and namespace pattern.
  • cert-manager Certificate resources in each client cluster request certs scoped to that client.

Bootstrap

  1. Vault is installed in the management plane.
  2. Vault is manually initialized and unsealed.
  3. Vault config is applied: KV engine, PKI engine, Kubernetes auth backends, policies.
  4. During client onboarding, the client cluster ServiceAccount is registered in Vault.
  5. cert-manager with a Vault issuer is deployed as part of the Inari baseline.
  6. Alloy requests and renews its certificate automatically via a Certificate resource.

Rotation

  • Client certificates are short-lived and auto-renewed by cert-manager before expiry.
  • Root CA rotation is a planned maintenance event documented in the runbook.
  • Compromised certificates can be revoked via Vault PKI.