From afe799952010c6d618d3971f4e13bda1d2dc408d Mon Sep 17 00:00:00 2001 From: Jaydip Gabani Date: Wed, 31 Jul 2024 20:19:23 +0000 Subject: [PATCH] updating docs Signed-off-by: Jaydip Gabani --- website/docs/enforcement-points.md | 8 +++++--- website/docs/validating-admission-policy.md | 4 ++-- .../version-v3.16.x/validating-admission-policy.md | 2 +- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/website/docs/enforcement-points.md b/website/docs/enforcement-points.md index f8b9a48f847..0b7f226b83e 100644 --- a/website/docs/enforcement-points.md +++ b/website/docs/enforcement-points.md @@ -14,15 +14,15 @@ An enforcement point defines the location where enforcement happens. Below are t ### How to use different enforcement points in constraint -By default, a constraint will be enforced at all enforcement points with common enforcement action defined in `spec.enforcementAction`. However, you can chose to enforce a constraint at specific enforcement points different actions using `spec.scopedEnforcementActions`. Below are the different examples and use cases that utilizes different enforcement actions for different enforcement points. +By default, a constraint will be enforced at all enforcement points with common enforcement action defined in `spec.enforcementAction`. However, you can choose to enforce a constraint at specific enforcement points with different actions using `enforcementAction: scoped` and `spec.scopedEnforcementActions`. Below are examples and use cases that utilize different enforcement actions for different enforcement points. :::note -`spec.enforcementAction: scoped` is needed to customize specific enforcement point/enforcement action behavior. If `spec.enforcementAction: scoped` is not provided, `spec.scopedEnforcementActions` is ignored and defined `enforcementAction` will be enforced at all enforcement points. +`spec.enforcementAction: scoped` is needed to customize specific enforcement point/enforcement action behavior. If `spec.enforcementAction: scoped` is not provided, `spec.scopedEnforcementActions` is ignored and the provided `enforcementAction` will be applied across all enforcement points. ::: ###### Deny in shift-left and warn at admission -You are trying out a new constraint template, and you want deny violating resources in shift-left testing, but do not want to block any resources when admitted to cluster to avoid faulty rejects. You may want to use `deny` action for `gator.gatekeeper.sh` enforcement point and `warn` for `validation.gatekeepet.sh`. The below constraint satisfies this use case. +You are trying out a new constraint template, and you want to deny violating resources in shift-left testing, but do not want to block any resources admitted to clusters to reduce impact for faulty rejections. You may want to use `deny` action for the `gator.gatekeeper.sh` shift-left enforcement point and `warn` for `the validation.gatekeepet.sh` admission webhook enforcement point. The below constraint satisfies this use case. ```yaml apiVersion: constraints.gatekeeper.sh/v1beta1 @@ -42,6 +42,8 @@ spec: ... ``` +> **Note**: The audit enforcement point is not included unless explicitly added to scopedEnforcementActions.enforcementPoints or if scopedEnforcementActions.enforcementPoints is set to "*". + ###### Only audit You are depending on external-data or referential policies for validating resources. These type of validation may be latency sensitive and may take longer to evaluate. To avoid such situation you may want to only use `audit.gatekeeper.sh` enforcement point to not face any delay at admission time, but still get the information about violating resources from Gatekeeper's audit operation. Here is the constraint for only using `audit.gatekeeper.sh` enforcement point. diff --git a/website/docs/validating-admission-policy.md b/website/docs/validating-admission-policy.md index 5ec1d326f0d..81d1a26b5b3 100644 --- a/website/docs/validating-admission-policy.md +++ b/website/docs/validating-admission-policy.md @@ -26,7 +26,7 @@ The [Constraint Framework](https://github.com/open-policy-agent/frameworks/tree/ Together with Gatekeeper and [gator CLI](gator.md), you can get admission, audit, and shift left validations for policies written in both CEL and Rego policy languages, even for clusters that do not support Validating Admission Policy feature yet. For simple policies, you may want admission requests to be handled by the K8s built-in Validating Admission Controller (only supports CEL) instead of the Gatekeeper admission webhook. -To summarize, these are potential options when running Gatekeeper: +In summary, these are potential options when running Gatekeeper: | Policy Language(s) | Enforcement Point | | ------------------ | ------------------ | @@ -136,7 +136,7 @@ spec: ... ``` -Constraints will follow the behavior defined in `spec.scopedEnforcementActions`. When `spec.scopedEnforcementAction` is not defined, constraints will follow behavior defined by the flag `--default-create-vap-binding-for-constraints`. By default, `--default-create-vap-binding-for-constraints` is set to `false`. +Gatekeeper determines the intended enforcement actions for a given enforcement point by evaluating what is provided in `spec.scopedEnforcementActions` and `spec.enforcementAction: scoped` in the constraint. If these values are not provided in the constraint, then Gatekeeper will follow behavior defined by the flag `--default-create-vap-binding-for-constraints`. By default, `--default-create-vap-binding-for-constraints` is set to `false`. The overall opt-in/opt-out behavior for constraint to generate Validating Admission Policy Binding (VAPB) is as below: diff --git a/website/versioned_docs/version-v3.16.x/validating-admission-policy.md b/website/versioned_docs/version-v3.16.x/validating-admission-policy.md index 4ce0307a955..bb40232f1d5 100644 --- a/website/versioned_docs/version-v3.16.x/validating-admission-policy.md +++ b/website/versioned_docs/version-v3.16.x/validating-admission-policy.md @@ -26,7 +26,7 @@ The [Constraint Framework](https://github.com/open-policy-agent/frameworks/tree/ Together with Gatekeeper and [gator CLI](gator.md), you can get admission, audit, and shift left validations for policies written in both CEL and Rego policy languages, even for clusters that do not support Validating Admission Policy feature yet. For simple policies, you may want admission requests to be handled by the K8s built-in Validating Admission Controller (only supports CEL) instead of the Gatekeeper admission webhook. -To summary, these are potential options when running Gatekeeper: +In summary, these are potential options when running Gatekeeper: | Policy Language(s) | Enforcement Point | | ------------------ | ------------------ |