From 0b3469f82a52c0dad15acc5edebdfbaa5b1e5d6e Mon Sep 17 00:00:00 2001 From: Alex Pana <8968914+acpana@users.noreply.github.com> Date: Thu, 28 Dec 2023 20:48:48 +0000 Subject: [PATCH 1/5] docs: syncset docs Signed-off-by: Alex Pana <8968914+acpana@users.noreply.github.com> --- website/docs/sync.md | 48 +++++++++++++++++++++++++++++++++++++------- 1 file changed, 41 insertions(+), 7 deletions(-) diff --git a/website/docs/sync.md b/website/docs/sync.md index a79bee11e29..888d90680e8 100644 --- a/website/docs/sync.md +++ b/website/docs/sync.md @@ -3,15 +3,38 @@ id: sync title: Replicating Data --- -`Feature State`: The `Config` resource is currently alpha. +## Replicating Data -> The "Config" resource must be named `config` for it to be reconciled by Gatekeeper. Gatekeeper will ignore the resource if you do not name it `config`. +Some constraints are impossible to write without access to more state than just the object under test. For example, it is impossible to know if an ingress's hostname is unique among all ingresses unless a ConstraintTemplate has access to all other ingresses. To enable this use case, we provide syncing of data into a data client. -Some constraints are impossible to write without access to more state than just the object under test. For example, it is impossible to know if an ingress's hostname is unique among all ingresses unless a rule has access to all other ingresses. To make such rules possible, we enable syncing of data into OPA. +### Replicating Data with SyncSets (preferred) -The [audit](audit.md) feature does not require replication by default. However, when the ``audit-from-cache`` flag is set to true, the audit informer cache will be used as the source-of-truth for audit queries; thus, an object must first be cached before it can be audited for constraint violations. +> `Feature State`: The `SyncSet` resource is currently in `alpha`. -Kubernetes data can be replicated into the audit cache via the sync config resource. Currently resources defined in `syncOnly` will be synced into OPA. Updating `syncOnly` should dynamically update what objects are synced. Below is an example: +Kubernetes data can be replicated into the data client using `SyncSet` resources. Below is an example of a `SyncSet`: + +```yaml +apiVersion: syncset.gatekeeper.sh/v1alpha1 +kind: SyncSet +metadata: + name: syncset-1 + namespace: "gatekeeper-system" +spec: + gvks: + - group: "" + version: "v1" + kind: "ConfigMap" +``` + +The resources defined in the `gvks` field of a SyncSet will be eventually synced into the data client. + +### Replicating Data with Config + +> `Feature State`: The `Config` resource is currently in `alpha`. + +> The "Config" resource must be named `config` for it to be reconciled by Gatekeeper. Gatekeeper will ignore the resource if you do not name it `config`. + +Kubernetes data can also be replicated into the data client via the Config resource. Resources defined in `syncOnly` will be synced into OPA. Below is an example: ```yaml apiVersion: config.gatekeeper.sh/v1alpha1 @@ -36,11 +59,22 @@ You can install this config with the following command: kubectl apply -f https://raw.githubusercontent.com/open-policy-agent/gatekeeper/master/demo/basic/sync.yaml ``` -Once data is synced into OPA, rules can access the cached data under the `data.inventory` document. +### Working with SyncSet and Config resources -The `data.inventory` document has the following format: +* Updating a Config's `syncOnly` field or a SyncSet's `gvks` field should dynamically update what objects are synced. +* Multiple `SyncSet`s may be defined and those will be reconciled by the Gatekeeper syncset-controller. Notably, the [set union](https://en.wikipedia.org/wiki/Union_(set_theory)) of all SyncSet resources' `gvks` and the [Config](sync#replicating-data-with-config) resource's `syncOnly` will be synced into the data client. +* A resource will continue to be present in the data client so long as a SyncSet or Config still specifies it under the `gvks` or `syncOnly` field. + +### Accessing replicated data +Once data is synced, ConstraintTemplates can access the cached data under the `data.inventory` document. + +The `data.inventory` document has the following format: * For cluster-scoped objects: `data.inventory.cluster[][][]` * Example referencing the Gatekeeper namespace: `data.inventory.cluster["v1"].Namespace["gatekeeper"]` * For namespace-scoped objects: `data.inventory.namespace[][groupVersion][][]` * Example referencing the Gatekeeper pod: `data.inventory.namespace["gatekeeper"]["v1"]["Pod"]["gatekeeper-controller-manager-d4c98b788-j7d92"]` + +### Auditing From Cache + +The [audit](audit.md) feature does not require replication by default. However, when the ``audit-from-cache`` flag is set to true, the audit informer cache will be used as the source-of-truth for audit queries; thus, an object must first be cached before it can be audited for constraint violations. Kubernetes data can be replicated into the audit cache via one of the resources above. \ No newline at end of file From 5ae0fad3dc8f2b8766a834f4e8965043b66b4bf5 Mon Sep 17 00:00:00 2001 From: alex <8968914+acpana@users.noreply.github.com> Date: Mon, 8 Jan 2024 13:32:47 -0800 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Rita Zhang Signed-off-by: alex <8968914+acpana@users.noreply.github.com> --- website/docs/sync.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/sync.md b/website/docs/sync.md index 888d90680e8..1ea0ecff958 100644 --- a/website/docs/sync.md +++ b/website/docs/sync.md @@ -7,7 +7,7 @@ title: Replicating Data Some constraints are impossible to write without access to more state than just the object under test. For example, it is impossible to know if an ingress's hostname is unique among all ingresses unless a ConstraintTemplate has access to all other ingresses. To enable this use case, we provide syncing of data into a data client. -### Replicating Data with SyncSets (preferred) +### Replicating Data with SyncSets (Recommended) > `Feature State`: The `SyncSet` resource is currently in `alpha`. From 5d826f2400954a50d53bd39622fcdad9720d2d0d Mon Sep 17 00:00:00 2001 From: Alex Pana <8968914+acpana@users.noreply.github.com> Date: Mon, 8 Jan 2024 21:58:49 +0000 Subject: [PATCH 3/5] feedback Signed-off-by: Alex Pana <8968914+acpana@users.noreply.github.com> --- website/docs/sync.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/sync.md b/website/docs/sync.md index 1ea0ecff958..aeac15ae707 100644 --- a/website/docs/sync.md +++ b/website/docs/sync.md @@ -9,7 +9,7 @@ Some constraints are impossible to write without access to more state than just ### Replicating Data with SyncSets (Recommended) -> `Feature State`: The `SyncSet` resource is currently in `alpha`. +`Feature State`: Gatekeeper version v3.15+ (alpha) Kubernetes data can be replicated into the data client using `SyncSet` resources. Below is an example of a `SyncSet`: @@ -21,16 +21,16 @@ metadata: namespace: "gatekeeper-system" spec: gvks: - - group: "" + - group: "networking.k8s.io" version: "v1" - kind: "ConfigMap" + kind: "Ingress" ``` The resources defined in the `gvks` field of a SyncSet will be eventually synced into the data client. ### Replicating Data with Config -> `Feature State`: The `Config` resource is currently in `alpha`. +`Feature State`: Gatekeeper version v3.6+ (alpha) > The "Config" resource must be named `config` for it to be reconciled by Gatekeeper. Gatekeeper will ignore the resource if you do not name it `config`. From 2af6c9a59274f94891567a025631b9ad5853e007 Mon Sep 17 00:00:00 2001 From: alex <8968914+acpana@users.noreply.github.com> Date: Wed, 10 Jan 2024 11:48:03 -0800 Subject: [PATCH 4/5] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sertaç Özercan <852750+sozercan@users.noreply.github.com> Signed-off-by: alex <8968914+acpana@users.noreply.github.com> --- website/docs/sync.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/sync.md b/website/docs/sync.md index aeac15ae707..dd429fe2813 100644 --- a/website/docs/sync.md +++ b/website/docs/sync.md @@ -77,4 +77,4 @@ The `data.inventory` document has the following format: ### Auditing From Cache -The [audit](audit.md) feature does not require replication by default. However, when the ``audit-from-cache`` flag is set to true, the audit informer cache will be used as the source-of-truth for audit queries; thus, an object must first be cached before it can be audited for constraint violations. Kubernetes data can be replicated into the audit cache via one of the resources above. \ No newline at end of file +The [audit](audit.md) feature does not require replication by default. However, when the `audit-from-cache` flag is set to true, the audit informer cache will be used as the source-of-truth for audit queries; thus, an object must first be cached before it can be audited for constraint violations. Kubernetes data can be replicated into the audit cache via one of the resources above. \ No newline at end of file From 5fcae224149fc3be4e9631cc4d512c3001b854b4 Mon Sep 17 00:00:00 2001 From: Alex Pana <8968914+acpana@users.noreply.github.com> Date: Thu, 11 Jan 2024 22:54:43 +0000 Subject: [PATCH 5/5] adjust sync scenario Signed-off-by: Alex Pana <8968914+acpana@users.noreply.github.com> --- website/docs/sync.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/website/docs/sync.md b/website/docs/sync.md index dd429fe2813..e47665908f1 100644 --- a/website/docs/sync.md +++ b/website/docs/sync.md @@ -5,7 +5,7 @@ title: Replicating Data ## Replicating Data -Some constraints are impossible to write without access to more state than just the object under test. For example, it is impossible to know if an ingress's hostname is unique among all ingresses unless a ConstraintTemplate has access to all other ingresses. To enable this use case, we provide syncing of data into a data client. +Some constraints are impossible to write without access to more state than just the object under test. For example, it is impossible to know if a label is unique across all pods and namespaces unless a ConstraintTemplate has access to all other pods and namespaces. To enable this use case, we provide syncing of data into a data client. ### Replicating Data with SyncSets (Recommended) @@ -18,16 +18,24 @@ apiVersion: syncset.gatekeeper.sh/v1alpha1 kind: SyncSet metadata: name: syncset-1 - namespace: "gatekeeper-system" spec: gvks: - - group: "networking.k8s.io" + - group: "" + version: "v1" + kind: "Namespace" + - group: "" version: "v1" - kind: "Ingress" + kind: "Pod" ``` The resources defined in the `gvks` field of a SyncSet will be eventually synced into the data client. +#### Working with SyncSet resources + +* Updating a SyncSet's `gvks` field should dynamically update what objects are synced. +* Multiple `SyncSet`s may be defined and those will be reconciled by the Gatekeeper syncset-controller. Notably, the [set union](https://en.wikipedia.org/wiki/Union_(set_theory)) of all SyncSet resources' `gvks` and the [Config](sync#replicating-data-with-config) resource's `syncOnly` will be synced into the data client. +* A resource will continue to be present in the data client so long as a SyncSet or Config still specifies it under the `gvks` or `syncOnly` field. + ### Replicating Data with Config `Feature State`: Gatekeeper version v3.6+ (alpha) @@ -59,10 +67,10 @@ You can install this config with the following command: kubectl apply -f https://raw.githubusercontent.com/open-policy-agent/gatekeeper/master/demo/basic/sync.yaml ``` -### Working with SyncSet and Config resources +#### Working with Config resources -* Updating a Config's `syncOnly` field or a SyncSet's `gvks` field should dynamically update what objects are synced. -* Multiple `SyncSet`s may be defined and those will be reconciled by the Gatekeeper syncset-controller. Notably, the [set union](https://en.wikipedia.org/wiki/Union_(set_theory)) of all SyncSet resources' `gvks` and the [Config](sync#replicating-data-with-config) resource's `syncOnly` will be synced into the data client. +* Updating a Config's `syncOnly` field should dynamically update what objects are synced. +* The `Config` resource is meant to be a singleton. The [set union](https://en.wikipedia.org/wiki/Union_(set_theory)) of all SyncSet resources' `gvks` and the [Config](sync#replicating-data-with-config) resource's `syncOnly` will be synced into the data client. * A resource will continue to be present in the data client so long as a SyncSet or Config still specifies it under the `gvks` or `syncOnly` field. ### Accessing replicated data