Contributing

Use this guide to contribute to bao-kms-provider. For operator procedures, start with Start Here .

Project Layout

Go package layout:

cmd/bao-kms-provider
internal/aad
internal/auth
internal/config
internal/health
internal/keyregistry
internal/kmsv2
internal/logging
internal/metrics
internal/openbao
internal/runtime
internal/socket
internal/status
internal/version
test/e2e
test/fakes
test/kmsconformance
test/deployment

Local Development

Install Nix and devenv 2.1 or later. Enter the repository root, then verify the pinned toolchain and install the repository-managed tools:

devenv test
devenv tasks run kms:bootstrap

The shell sets GOTOOLCHAIN=local. It does not start Docker, Kubernetes, OpenBao, or other services. It does not create credentials.

Every pull request must pass the local core gate:

devenv tasks run kms:ci-core

This task runs make ci-core. Make remains the command contract for local and CI checks. Use devenv shell when you need an interactive shell. Use devenv --profile editor shell to add Go language-server and debugger tools.

Run focused end-to-end (E2E) lanes when a change touches OpenBao, Kubernetes, deployment, rotation, failure injection, or release packaging behavior. The lane commands live in Development: E2E Framework .

For deployment sample or package metadata changes, run the focused deployment checks:

make deployment-samples-check
make package-build-check

deployment-samples-check verifies the systemd unit with the host systemd-analyze binary when it is installed. package-build-check uses the pinned nFPM version from .ci/versions.yaml/mk/config.mk through go run and builds throwaway .deb and .rpm packages from a temporary placeholder binary.

OpenBao Integration Tests

OpenBao integration tests use build tags and remain hermetic. They use in-process HTTPS fakes for OpenBao response shapes and do not require external OpenBao credentials:

go test -tags=integration ./internal/openbao -run TestOpenBaoTransitIntegration -count=1

OpenBao E2E Tests

OpenBao E2E validation uses the ephemeral continuous integration (CI) lane. E2E specs use the Ginkgo v2 and Gomega versions pinned in .ci/versions.yaml. The test/e2e/suites.yaml manifest describes the lanes:

make test-e2e-openbao-ci

The OpenBao CI target starts real OpenBao, bootstraps provider auth, runs the provider, and exercises the Unix socket with the Kubernetes KMS v2 protobuf client.

For the full E2E framework, label routing, suite manifest rules, and report artifacts see Development: E2E Framework .

Go Code Quality

Implementation follows Development: Code Quality . Key rules:

• no map[string]any in production code,
• no map[string]interface{} in production code,
• no broad any or interface{} outside reviewed boundary adapters,
• Viper stays at the CLI and configuration boundary,
• OpenBao, configuration, KMS, additional authenticated data (AAD), and registry data use typed structs,
• decode unknown fields strictly where the parser supports it,
• no free-form string state machines in internal logic,
• no panics in request-path code.

Wire Compatibility

The following surfaces are wire-format commitments:

• Kubernetes provider name behavior,
• key_id derivation,
• annotation keys and values,
• AAD canonicalization,
• historical key lookup behavior,
• compatibility mode semantics.

Any change to these surfaces requires:

• a documented migration plan,
• updated golden fixtures,
• a release note,
• a compatibility section in Reference: Compatibility .

Redaction Rules

Tests must prove these never appear in logs or command output:

• plaintext,
• JWTs,
• OpenBao tokens,
• full ciphertext,
• raw Transit key material.

For the full redaction policy see Reference: Observability: Logs and Security: Hardening: Logging .

Dependency Policy

Prefer:

• the official Kubernetes KMS protobuf package,
• official or OpenBao-compatible API clients where practical,
• Viper for CLI configuration loading and command environment binding,
• standard library parsers for structured data,
• small dependencies with clear maintenance status.

Avoid:

• ad hoc string parsing for YAML, JSON, or JWT when a structured-data parser exists,
• dependencies that log requests by default,
• dependencies that make Transport Layer Security (TLS) verification difficult to control.

Documentation Updates

When implementation changes behavior, update documentation in the same change:

• configuration changes update Reference: Configuration ,
• KMS protocol behavior updates Reference: KMS v2 Contract ,
• key_id or AAD changes update Reference: Key ID And AAD ,
• operational changes update the relevant operations or deployment runbook,
• support and version-envelope changes update Reference: Compatibility .

For writing style, page structure, links, and docs verification, see Development: Docs Style Guide .