docs: explain why audit runs as singleton

website/docs/audit.md

@@ -143,6 +143,13 @@ Limitations/drawbacks of exporting violations:
 - Additional dependency on the backend system provided. For example, using pubsub tools to export violations.
 
 ## Running Audit
+
+### Why Audit Runs as a Singleton
+
+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. 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.
+
+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 `--constraint-violations-limit=0`. Additionally, you must disable VAP generation when running multiple replicas to avoid conflicts.
+
 For more details on how to deploy audit and 
 number of instances to run, please refer to [operations audit](operations.md#audit). 
 

website/versioned_docs/version-v3.10.x/audit.md

@@ -118,6 +118,13 @@ All of these events (including `violation_audited`) are marked
 with the same `audit_id` for a given audit run.
 
 ## Running Audit
+
+### Why Audit Runs as a Singleton
+
+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 `--constraint-violations-limit=0`.
+
 For more details on how to deploy audit and 
 number of instances to run, please refer to [operations audit](operations.md#audit). 
 

website/versioned_docs/version-v3.11.x/audit.md

@@ -125,6 +125,13 @@ All of these events (including `violation_audited`) are marked
 with the same `audit_id` for a given audit run.
 
 ## Running Audit
+
+### Why Audit Runs as a Singleton
+
+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 `--constraint-violations-limit=0`.
+
 For more details on how to deploy audit and 
 number of instances to run, please refer to [operations audit](operations.md#audit). 
 

website/versioned_docs/version-v3.12.x/audit.md

@@ -125,6 +125,13 @@ All of these events (including `violation_audited`) are marked
 with the same `audit_id` for a given audit run.
 
 ## Running Audit
+
+### Why Audit Runs as a Singleton
+
+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 `--constraint-violations-limit=0`.
+
 For more details on how to deploy audit and 
 number of instances to run, please refer to [operations audit](operations.md#audit). 
 

website/versioned_docs/version-v3.13.x/audit.md

@@ -142,6 +142,13 @@ Limitations/drawbacks of getting violations using pubsub channel:
 - Additional dependency on pubsub broker. 
 
 ## Running Audit
+
+### Why Audit Runs as a Singleton
+
+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 `--constraint-violations-limit=0`.
+
 For more details on how to deploy audit and 
 number of instances to run, please refer to [operations audit](operations.md#audit). 
 

website/versioned_docs/version-v3.14.x/audit.md

@@ -142,6 +142,13 @@ Limitations/drawbacks of getting violations using pubsub channel:
 - Additional dependency on pubsub broker. 
 
 ## Running Audit
+
+### Why Audit Runs as a Singleton
+
+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 `--constraint-violations-limit=0`.
+
 For more details on how to deploy audit and 
 number of instances to run, please refer to [operations audit](operations.md#audit). 
 

website/versioned_docs/version-v3.15.x/audit.md

@@ -142,6 +142,13 @@ Limitations/drawbacks of getting violations using pubsub channel:
 - Additional dependency on pubsub broker. 
 
 ## Running Audit
+
+### Why Audit Runs as a Singleton
+
+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 `--constraint-violations-limit=0`.
+
 For more details on how to deploy audit and 
 number of instances to run, please refer to [operations audit](operations.md#audit). 
 

website/versioned_docs/version-v3.16.x/audit.md

@@ -142,6 +142,13 @@ Limitations/drawbacks of getting violations using pubsub channel:
 - Additional dependency on pubsub broker. 
 
 ## Running Audit
+
+### Why Audit Runs as a Singleton
+
+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 `--constraint-violations-limit=0`.
+
 For more details on how to deploy audit and 
 number of instances to run, please refer to [operations audit](operations.md#audit). 
 

website/versioned_docs/version-v3.17.x/audit.md

@@ -143,6 +143,13 @@ Limitations/drawbacks of getting violations using pubsub channel:
 - Additional dependency on pubsub broker. 
 
 ## Running Audit
+
+### Why Audit Runs as a Singleton
+
+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 `--constraint-violations-limit=0`.
+
 For more details on how to deploy audit and 
 number of instances to run, please refer to [operations audit](operations.md#audit). 
 

website/versioned_docs/version-v3.18.x/audit.md

@@ -143,6 +143,13 @@ Limitations/drawbacks of getting violations using pubsub channel:
 - Additional dependency on pubsub broker. 
 
 ## Running Audit
+
+### Why Audit Runs as a Singleton
+
+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. 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.
+
+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 `--constraint-violations-limit=0`. Additionally, you must disable VAP generation when running multiple replicas to avoid conflicts.
+
 For more details on how to deploy audit and 
 number of instances to run, please refer to [operations audit](operations.md#audit). 
 

website/versioned_docs/version-v3.19.x/audit.md

@@ -143,6 +143,13 @@ Limitations/drawbacks of exporting violations:
 - Additional dependency on the backend system provided. For example, using pubsub tools to export violations.
 
 ## Running Audit
+
+### Why Audit Runs as a Singleton
+
+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. 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.
+
+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 `--constraint-violations-limit=0`. Additionally, you must disable VAP generation when running multiple replicas to avoid conflicts.
+
 For more details on how to deploy audit and 
 number of instances to run, please refer to [operations audit](operations.md#audit). 
 

website/versioned_docs/version-v3.20.x/audit.md

@@ -143,6 +143,13 @@ Limitations/drawbacks of exporting violations:
 - Additional dependency on the backend system provided. For example, using pubsub tools to export violations.
 
 ## Running Audit
+
+### Why Audit Runs as a Singleton
+
+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. 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.
+
+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 `--constraint-violations-limit=0`. Additionally, you must disable VAP generation when running multiple replicas to avoid conflicts.
+
 For more details on how to deploy audit and 
 number of instances to run, please refer to [operations audit](operations.md#audit). 
 

website/versioned_docs/version-v3.6.x/audit.md

@@ -108,7 +108,12 @@ In addition to violations, these other audit events may be useful (all uniquely
 All of these events (including `violation_audited`) are marked with the same `audit_id` for a given audit run.
 
 ## Running Audit
-By default, audit runs as its own deployment. To limit traffic to the API server and to avoid contention writing audit results to constraints, audit should run as a singleton pod.
+
+### Why Audit Runs as a Singleton
+
+By default, audit runs as its own deployment. 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. To limit traffic to the API server and to avoid contention writing audit results to constraints, audit should run as a singleton pod.
+
+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 `--constraint-violations-limit=0`.
 
 ## Configuring Audit
 

website/versioned_docs/version-v3.7.x/audit.md

@@ -108,6 +108,13 @@ In addition to violations, these other audit events may be useful (all uniquely
 All of these events (including `violation_audited`) are marked with the same `audit_id` for a given audit run.
 
 ## Running Audit
+
+### Why Audit Runs as a Singleton
+
+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 `--constraint-violations-limit=0`.
+
 For more details on how to deploy audit and 
 number of instances to run, please refer to [operations audit](operations.md#audit). 
 

website/versioned_docs/version-v3.8.x/audit.md

@@ -108,6 +108,13 @@ In addition to violations, these other audit events may be useful (all uniquely
 All of these events (including `violation_audited`) are marked with the same `audit_id` for a given audit run.
 
 ## Running Audit
+
+### Why Audit Runs as a Singleton
+
+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 `--constraint-violations-limit=0`.
+
 For more details on how to deploy audit and 
 number of instances to run, please refer to [operations audit](operations.md#audit). 
 

website/versioned_docs/version-v3.9.x/audit.md

@@ -117,6 +117,13 @@ All of these events (including `violation_audited`) are marked
 with the same `audit_id` for a given audit run.
 
 ## Running Audit
+
+### Why Audit Runs as a Singleton
+
+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 `--constraint-violations-limit=0`.
+
 For more details on how to deploy audit and 
 number of instances to run, please refer to [operations audit](operations.md#audit).