ORCHORDS · ORCHORDS · Sep 5, 2026 · Sep 5, 2026
@@ -0,0 +1,70 @@
+# OPA Bundle Rotation Playbook
+
+## Purpose
+
+Define the operational procedure for rotating an OPA bundle (policy + data) without service disruption. The procedure ensures that OPA agents always have a signed, validated bundle.
+
+## Audience
+
+Platform engineers, SREs, and security engineers who run OPA in production.
+
+## Pre-conditions
+
+- OPA 1.0+ is in use (per `OPA_VERSION_GOVERNANCE.md`).
+- Bundles are signed via `cosign` or GPG.
+- The bundle server (BSR, S3, GCS, or HTTP) is reachable.
+
+## Procedure
+
+### Step 1 — Author the new bundle
+
+1. Edit the Rego policy under `policies/<package>/`.
+2. Edit the data under `data/<package>/` (JSON or YAML).
+3. Run `opa fmt -w policies/`.
+4. Run `opa test policies/`.
+5. Run `opa build -b policies/<package>/ -o bundle.tar.gz`.
+
+### Step 2 — Sign the bundle
+
+6. Compute the SHA-256 of `bundle.tar.gz`.
+7. Sign with `cosign sign --key cosign.key <sha>` or `gpg --sign`.
+8. Embed the signature in the bundle manifest (`.manifest`).
+
+### Step 3 — Publish
+
+9. Upload `bundle.tar.gz` to the bundle server (BSR / S3 / GCS / HTTP).
+10. Upload the signature.
+11. Update the discovery URL or BSR tag.
+
+### Step 4 — Verify the rotation
+
+12. Force a bundle pull: `curl http://opa-server/v1/bundles/<name>` or trigger via control plane.
+13. Confirm the new bundle SHA matches.
+14. Confirm OPA logs `bundle loaded` with the new SHA.
+
+### Step 5 — Validate
+
+15. Run a synthetic policy query.
+16. Confirm `decision_id` and `result`.
+17. Confirm the bundle is now serving traffic.
+
+### Step 6 — Roll back if needed
+
+18. If the new bundle is faulty, revert the upload.
+19. Force a bundle pull to the previous version.
+20. Confirm OPA logs `bundle loaded` with the previous SHA.
+
+## Rollback
+
+If the new bundle causes incorrect decisions:
+
+1. Revert the upload (or delete the bundle).
+2. OPA will continue serving the last good bundle.
+3. Investigate the policy regression.
+4. Re-publish a corrected bundle.
+
+## References
+
+- `OPA_VERSION_GOVERNANCE.md`
+- OPA bundles: `https://www.openpolicyagent.org/docs/latest/management-bundles/`
+- Cosign: `https://docs.sigstore.dev/cosign/overview/`
@@ -0,0 +1,69 @@
+# Protobuf Schema Deprecation Playbook
+
+## Purpose
+
+Define the operational procedure for deprecating and removing a field, enum value, or RPC method in a Protobuf schema while maintaining backward compatibility. The procedure ensures that consumers running older generated code do not lose functionality.
+
+## Audience
+
+Service owners and API engineers who maintain `.proto` files and generated code.
+
+## Pre-conditions
+
+- The schema lives in a Buf-managed module (per `PROTOBUF_VERSION_GOVERNANCE.md`).
+- The team has access to `buf` CLI.
+- The team can ship generated code in lockstep with consumers.
+
+## Procedure
+
+### Step 1 — Identify the candidate
+
+1. Inventory fields, enum values, and methods that are unused for at least 6 months.
+2. Check usage via generated-code search, logs, or consumer surveys.
+3. Confirm the field is not part of any documented public contract.
+
+### Step 2 — Mark deprecated
+
+4. Add `// deprecated: <reason>` to the field or method.
+5. Add `[deprecated = true]` annotation in the `.proto`.
+6. Bump the package version to `v1` (or maintain minor version).
+7. Update generated code in lockstep with consumers.
+
+### Step 3 — Communicate
+
+8. Announce the deprecation in the API changelog.
+9. Provide a 90-day migration window before deletion.
+10. Track consumer usage in the deprecation period.
+
+### Step 4 — Block reuse of field numbers
+
+11. Move the deprecated field to `reserved`.
+12. Add `reserved <field_number>;` in the message.
+13. This blocks reuse of the tag in any future field.
+
+### Step 5 — Remove
+
+14. After 90 days, remove the deprecated field, enum value, or method.
+15. Bump the package version to `v2` if breaking change.
+16. Run `buf breaking --against <previous-tag>` to confirm.
+
+### Step 6 — Verify
+
+17. Run `buf lint`.
+18. Run `buf build`.
+19. Confirm consumers regenerate successfully.
+20. Run integration tests.
+
+## Rollback
+
+If a removal breaks a consumer:
+
+1. Re-introduce the field as deprecated (not as `reserved`).
+2. Bump the version to reflect the regression.
+3. Communicate immediately.
+
+## References
+
+- `PROTOBUF_VERSION_GOVERNANCE.md`
+- Buf breaking: `https://buf.build/docs/lint/usage/`
+- Proto3 language guide: `https://protobuf.dev/programming-guides/proto3/`
@@ -265,3 +265,9 @@ This family contains repeatable procedures for development, deployment, incident
 - [Kubernetes Cluster Minor Upgrade Playbook](KUBERNETES_UPGRADE_PLAYBOOK.md)
 - [Container Image Hardening Playbook](CONTAINER_IMAGE_HARDENING_PLAYBOOK.md)
 - [Supply Chain Incident Response Playbook](SUPPLY_CHAIN_INCIDENT_PLAYBOOK.md)
+
+## 2026-09-05 Protobuf schema deprecation, OPA bundle rotation, and Vault audit log shipping playbooks (Batch 89)
+
+- [Protobuf Schema Deprecation Playbook](PROTOBUF_SCHEMA_DEPRECATION_PLAYBOOK.md)
+- [OPA Bundle Rotation Playbook](OPA_BUNDLE_ROTATION_PLAYBOOK.md)
+- [Vault Audit Log Shipping Playbook](VAULT_AUDIT_LOG_SHIPPING_PLAYBOOK.md)
@@ -0,0 +1,71 @@
+# Vault Audit Log Shipping Playbook
+
+## Purpose
+
+Define the operational procedure for shipping HashiCorp Vault audit logs to a centralized SIEM. The procedure ensures that every request — success or failure — is captured with full request / response context.
+
+## Audience
+
+Platform engineers, SREs, and security engineers who operate Vault.
+
+## Pre-conditions
+
+- Vault 1.10+ (per `VAULT_VERSION_GOVERNANCE.md`).
+- A SIEM endpoint reachable (Splunk, Elastic, Datadog, Sumo, etc.).
+- A shipper installed (Filebeat, Vector, Fluentd).
+
+## Procedure
+
+### Step 1 — Enable audit devices
+
+1. `vault audit enable -path=stdout file format=json`.
+2. `vault audit enable -path=file file_path=/var/log/vault/audit.log format=json`.
+3. Confirm via `vault audit list`.
+
+### Step 2 — Configure HMAC (optional)
+
+4. Generate an HMAC key:
+   - `uuidgen | vault audit enable -path=hmac file format=json hmac=true`.
+5. Confirm HMAC appears in every record.
+
+### Step 3 — Configure the shipper
+
+6. Configure Filebeat / Vector with the audit log path:
+   - Filebeat: `/var/log/vault/audit.log`.
+   - Vector: `sources.vault_audit.type = "file"; sources.vault_audit.include = ["/var/log/vault/audit.log"]`.
+7. Map fields:
+   - `type` → audit device.
+   - `request.path` → requested API path.
+   - `request.client_token` → token (masked).
+   - `response.status` → success / failure.
+   - `error` → failure reason.
+   - `time` → event timestamp.
+8. Configure output to the SIEM.
+
+### Step 4 — Verify
+
+9. Trigger a synthetic Vault request.
+10. Confirm the request appears in the SIEM within 60 seconds.
+11. Confirm the HMAC matches.
+
+### Step 5 — Monitor
+
+12. Alert on audit log shipping lag.
+13. Alert on the absence of audit logs for >5 minutes.
+14. Alert on the presence of `error` non-null in `response.status` for sensitive paths.
+
+## Rollback
+
+If the audit log pipeline is broken:
+
+1. Disable the shipper.
+2. Local audit logs continue to write to `/var/log/vault/audit.log`.
+3. Repair the shipper.
+4. Re-enable the shipper.
+
+## References
+
+- `VAULT_VERSION_GOVERNANCE.md`
+- Vault audit: `https://developer.hashicorp.com/vault/docs/audit`
+- Filebeat: `https://www.elastic.co/beats/filebeat`
+- Vector: `https://vector.dev/`
@@ -0,0 +1,103 @@
+---
+title: Open Policy Agent (OPA / Rego) Version Governance
+owner: Knowledge Engineering
+status: approved
+classification: public
+last-reviewed: 2026-09-05
+review-cycle: 180 days
+next-review: 2027-03-04
+source: Open Policy Agent; CNCF; Styra; OPA documentation at openpolicyagent.org
+---
+
+# Open Policy Agent (OPA / Rego) Version Governance
+
+## Scope
+
+This card governs how `orchords-docs` evaluates the Open Policy Agent (OPA) and the Rego policy language across versions, runtime modes, and integration patterns. It is the reference input for any KB card that touches admission control, authorization, or policy-as-code.
+
+## Why this card exists
+
+OPA has graduated from CNCF (March 2021) and is the de-facto standard for policy-as-code across Kubernetes, microservices, and API gateways. Without an explicit card, the KB cites Rego versions and integration patterns that ignore v0.x vs v1.x and `rego.v1` migration.
+
+## Versions
+
+OPA 0.x series:
+
+- 0.10–0.20 — early adoption.
+- 0.30–0.40 — Kubernetes admission (kube-mgmt).
+- 0.50–0.60 — multi-cloud (AWS, GCP, Azure).
+- 0.65–0.69 — last 0.x series.
+
+OPA 1.x series (current):
+
+- 1.0 (stable, Rego v1 introduced).
+- 1.1–1.4 — incremental.
+
+References: `https://github.com/open-policy-agent/opa/releases`.
+
+## Rego language
+
+Rego is the policy language:
+
+- **rego.v0** — classic syntax (`if` blocks).
+- **rego.v1** — current syntax (`if` → `if { ... }`).
+
+References: `https://www.openpolicyagent.org/docs/latest/policy-language/`.
+
+## Runtime modes
+
+| Mode | Use |
+|---|---|
+| Library | embedded in Go services via SDK |
+| CLI | `opa eval`, `opa test`, `opa fmt` |
+| Server | HTTP API for policy evaluation |
+| Bundle | distribution of policy + data |
+
+References: `https://www.openpolicyagent.org/docs/latest/`.
+
+## Integration patterns
+
+| Integration | Use |
+|---|---|
+| Kubernetes admission (Gatekeeper / kube-mgmt) | cluster-scoped admission |
+| Istio / Envoy (OPA WASM) | service-mesh authorization |
+| API gateways (Kong, Tyk, Envoy) | API authorization |
+| Microservices (SDK) | embedded authorization |
+| CI/CD (conftest) | policy check on manifests |
+
+## Bundle distribution
+
+OPA bundles:
+
+- `.tar.gz` of `policy.tar` + `data.json` + `.manifest`.
+- Signed via `cosign` or GPG.
+- Pulled by OPA server / agent on a refresh interval.
+
+References: `https://www.openpolicyagent.org/docs/latest/management-bundles/`.
+
+## Decision logging
+
+OPA emits decision logs:
+
+- `decision_id`, `input`, `result`, `path`, `timestamp`.
+- Stream to stdout, file, or HTTP webhook.
+- Required for audit and observability.
+
+References: `https://www.openpolicyagent.org/docs/latest/decision-log/`.
+
+## Cross-reference
+
+| Domain | Card |
+|---|---|
+| Kubernetes | `KUBERNETES_VERSION_GOVERNANCE.md` |
+| Istio | `ISTIO_VERSION_GOVERNANCE.md` |
+| Service mesh | `ISTIO_VERSION_GOVERNANCE.md` |
+| Admission | (deferred) |
+
+## Sources
+
+- OPA documentation: `https://www.openpolicyagent.org/docs/latest/`
+- OPA releases: `https://github.com/open-policy-agent/opa/releases`
+- Rego playground: `https://play.openpolicyagent.org/`
+- Styra: `https://www.styra.com/`
+- CNCF OPA: `https://www.cncf.io/projects/open-policy-agent-opa/`