Skip to content

docs: explain why audit runs as singleton #4216

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

docs: explain why audit runs as singleton #4216

wants to merge 5 commits into from

Conversation

Copy link
Contributor

Copilot AI commented Nov 4, 2025 •
edited
Loading

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.

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)

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

@sozercan
docs: add explanation of why audit runs as singleton
263ae53 
Added detailed explanation to audit documentation about why the audit
component runs as a singleton and when multiple replicas can be used.
Updated both main docs and all 15 versioned documentation files.

Co-authored-by: sozercan <[email protected]>
Copilot AI changed the title [WIP] Add documentation for Gatekeeper audit singleton design docs: explain why audit runs as singleton Nov 4, 2025
Copilot AI requested a review from sozercan November 4, 2025 18:14
Copilot finished work on behalf of sozercan November 4, 2025 18:14
@sozercan sozercan marked this pull request as ready for review November 4, 2025 18:20
@sozercan sozercan requested a review from a team as a code owner November 4, 2025 18:20
Copilot AI review requested due to automatic review settings November 4, 2025 18:20
Copilot AI reviewed Nov 4, 2025
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds documentation explaining why the Gatekeeper audit component runs as a singleton. The addition clarifies that the singleton design prevents conflicting writes to Constraint CRs and provides guidance on when multiple replicas might be acceptable.

Key Changes:

  • Added a new subsection "Why Audit Runs as a Singleton" under the "Running Audit" section
  • Documentation explains the technical reason for the singleton design (conflicting writes to Constraint CRs)
  • Includes guidance on running multiple replicas when only consuming logs

Reviewed Changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated no comments.

Show a summary per file
File Description
website/docs/audit.md Added singleton explanation to the current documentation version
website/versioned_docs/version-v3.20.x/audit.md Added singleton explanation to v3.20.x documentation
website/versioned_docs/version-v3.19.x/audit.md Added singleton explanation to v3.19.x documentation
website/versioned_docs/version-v3.18.x/audit.md Added singleton explanation to v3.18.x documentation
website/versioned_docs/version-v3.17.x/audit.md Added singleton explanation to v3.17.x documentation
website/versioned_docs/version-v3.16.x/audit.md Added singleton explanation to v3.16.x documentation
website/versioned_docs/version-v3.15.x/audit.md Added singleton explanation to v3.15.x documentation
website/versioned_docs/version-v3.14.x/audit.md Added singleton explanation to v3.14.x documentation
website/versioned_docs/version-v3.13.x/audit.md Added singleton explanation to v3.13.x documentation
website/versioned_docs/version-v3.12.x/audit.md Added singleton explanation to v3.12.x documentation
website/versioned_docs/version-v3.11.x/audit.md Added singleton explanation to v3.11.x documentation
website/versioned_docs/version-v3.10.x/audit.md Added singleton explanation to v3.10.x documentation
website/versioned_docs/version-v3.9.x/audit.md Added singleton explanation to v3.9.x documentation
website/versioned_docs/version-v3.8.x/audit.md Added singleton explanation to v3.8.x documentation
website/versioned_docs/version-v3.7.x/audit.md Added singleton explanation to v3.7.x documentation
website/versioned_docs/version-v3.6.x/audit.md Added singleton explanation and restructured existing content for v3.6.x documentation

@sozercan
Copy link
Member

sozercan commented Nov 5, 2025

@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.

@sozercan
docs: add CRD and VAP conflict information to audit singleton explana…
9f688dc 
…tion

Added information about audit component's responsibility for generating
CRDs and VAP resources from ConstraintTemplate, and that increasing
replicas may cause conflicts for these resources as well.

Co-authored-by: sozercan <[email protected]>
Copy link
Contributor Author

Copilot AI commented Nov 5, 2025

@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

Copilot finished work on behalf of sozercan November 5, 2025 00:10
@JaydipGabani
Copy link
Contributor

JaydipGabani commented Nov 5, 2025

@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.

@JaydipGabani
docs: remove CRD/VAP info from v3.6-v3.17 audit docs
a2eb673 
CRD and VAP generation was moved to singleton audit in release 3.18.
Reverted CRD/VAP conflict information from versions 3.6.x through 3.17.x
as these versions did not have this functionality. Kept the information
in v3.18.x, v3.19.x, v3.20.x and main docs.

Co-authored-by: JaydipGabani <[email protected]>
Copy link
Contributor Author

Copilot AI commented Nov 5, 2025

@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

Copilot AI requested a review from JaydipGabani November 5, 2025 18:29
Copilot finished work on behalf of JaydipGabani November 5, 2025 18:29
@sozercan
Copy link
Member

sozercan commented Nov 5, 2025

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

@sozercan
docs: add requirement to disable VAP generation for multiple replicas
2f98c65 
Added note that users must disable VAP generation when running multiple
audit replicas to avoid conflicts. Updated main docs and v3.18.x-v3.20.x
versioned docs.

Co-authored-by: sozercan <[email protected]>
Copy link
Contributor Author

Copilot AI commented Nov 5, 2025

@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

Copilot finished work on behalf of sozercan November 5, 2025 18:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@sozercan sozercan Awaiting requested review from sozercan

@JaydipGabani JaydipGabani Awaiting requested review from JaydipGabani

At least 1 approving review is required to merge this pull request.

Assignees

@sozercan sozercan

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

docs: describe why audit is singleton

3 participants

@sozercan @JaydipGabani