docs: explain why audit runs as singleton

[Copilot]

The audit documentation lacked explanation for why the component must run as a singleton, causing confusion about replica configuration.

Changes

• Added "Why Audit Runs as a Singleton" subsection explaining:

  • Audit writes to Constraint CRs; multiple instances cause conflicting writes
  • Audit generates CRDs and VAP resources from ConstraintTemplate (v3.18+); multiple instances cause conflicts for these resources as well
  • Exception: multiple replicas safe when consuming only logs (not Constraint status)
  • Recommendation: set --constraint-violations-limit=0 for multi-replica setups
  • Requirement (v3.18+): must disable VAP generation when running multiple replicas to avoid conflicts

• Updated 16 files: main docs + all versioned docs (v3.6.x through v3.20.x)

  • Main docs and v3.18.x-v3.20.x: Include CRD/VAP conflict information and VAP disable requirement (feature introduced in v3.18)
  • v3.6.x-v3.17.x: Include only basic singleton explanation without CRD/VAP information

Location

Section added under "Running Audit" in website/docs/audit.md and all website/versioned_docs/version-*/audit.md files.

• Fixes open-policy-agent/gatekeeper#4215

Original prompt

---

This section details on the original issue you should resolve

<issue_title>docs: describe why audit is singleton</issue_title> <issue_description>Describe the solution you'd like

add to audit docs:

Gatekeeper audit component is designed to run as a singleton because it writes to Constraint CRs, and having multiple instances could lead to conflicting writes.

If your setup only consumes audit results from logs (and does not rely on Constraint status updates), you can safely run multiple replicas. However, we generally don’t recommend this unless you set --total-violations-limit=0.

Anything else you would like to add:

Environment:

• Gatekeeper version:
• Kubernetes version: (use kubectl version):</issue_description>

<agent_instructions>make sure to add to versioned_docs as well</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes open-policy-agent/gatekeeper#4215

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[sozercan]

@copilot add this too

Gatekeeper audit component is also responsible for generating CRDs and VAP resources from ConstraintTemplate. Increasing audit replicas may result in writing conflicts for CRDs and VAP resources as well.

[Copilot]

@copilot add this too

Gatekeeper audit component is also responsible for generating CRDs and VAP resources from ConstraintTemplate. Increasing audit replicas may result in writing conflicts for CRDs...

Added the CRD and VAP resource conflict information to all documentation files. Commit: 9f688dc

[JaydipGabani]

@copilot CRD generation and vap generation was moved to singleton audit in release 3.18, so only update versioned docs of 3.18, 3.19, and 3.20. Do not update any older docs since the support window is n-2. Keep the changes in website/docs as is.

[Copilot]

@copilot CRD generation and vap generation was moved to singleton audit in release 3.18, so only update versioned docs of 3.18, 3.19, and 3.20. Do not update any older docs since the support window is...

Removed CRD/VAP information from versions 3.6.x through 3.17.x. The CRD/VAP conflict information now only appears in v3.18.x, v3.19.x, v3.20.x and the main docs. Commit: a2eb673

[sozercan]

@copilot add that you can't also generate VAP with multiple replicas so users should turn off that if they want multiple replicas

[Copilot]

@copilot add that you can't also generate VAP with multiple replicas so users should turn off that if they want multiple replicas

Added requirement to disable VAP generation when running multiple replicas. Updated main docs and v3.18.x-v3.20.x. Commit: 2f98c65