diff --git a/website/docs/howto.md b/website/docs/howto.md index 764a5e85854..b84da1e8f9e 100644 --- a/website/docs/howto.md +++ b/website/docs/howto.md @@ -138,16 +138,5 @@ kubectl get constraints ``` ### Input Review +You can view information on the `input.review` object that Gatekeeper takes as input [here](./input.md) -The `input.review` object stores the [admission request](https://pkg.go.dev/k8s.io/kubernetes/pkg/apis/admission#AdmissionRequest) under evaluation. It has the following fields: -- `dryRun`: Describes if the request was invoked by `kubectl --dry-run`. This cannot be populated by Kubernetes for audit. -- `kind`: The resource `kind`, `group`, `version` of the request object under evaluation. -- `name`: The name of the request object under evaluation. It may be empty if the deployment expects the API server to generate a name for the requested resource. -- `namespace`: The namespace of the request object under evaluation. Empty for cluster scoped objects. -- `object`: The request object under evaluation to be created or modified. -- `oldObject`: The original state of the request object under evaluation. This is only available for UPDATE operations. -- `operation`: The operation for the request (e.g. CREATE, UPDATE). This cannot be populated by Kubernetes for audit. -- `uid`: The request's unique identifier. This cannot be populated by Kubernetes for audit. -- `userInfo`: The request's user's information such as `username`, `uid`, `groups`, `extra`. This cannot be populated by Kubernetes for audit. - -> **_NOTE_** For `input.review` fields above that cannot be populated by Kubernetes for audit reviews, the constraint templates that rely on them are not auditable. It is up to the rego author to handle the case where these fields are unset and empty in order to avoid every matching resource being reported as violating resources. diff --git a/website/docs/input.md b/website/docs/input.md new file mode 100644 index 00000000000..488f1a54bb0 --- /dev/null +++ b/website/docs/input.md @@ -0,0 +1,75 @@ +--- +id: input +title: Admission Review Input +--- + +The data that's passed to Gatekeeper for review is in the form of an `input.review` object that stores the [admission request](https://pkg.go.dev/k8s.io/kubernetes/pkg/apis/admission#AdmissionRequest) under evaluation. It follows a structure that contains the object being created, and in the case of update operations the old object being updated. It has the following fields: +- `dryRun`: Describes if the request was invoked by `kubectl --dry-run`. This cannot be populated by Kubernetes for audit. +- `kind`: The resource `kind`, `group`, `version` of the request object under evaluation. +- `name`: The name of the request object under evaluation. It may be empty if the deployment expects the API server to generate a name for the requested resource. +- `namespace`: The namespace of the request object under evaluation. Empty for cluster scoped objects. +- `object`: The request object under evaluation to be created or modified. +- `oldObject`: The original state of the request object under evaluation. This is only available for UPDATE operations. +- `operation`: The operation for the request (e.g. CREATE, UPDATE). This cannot be populated by Kubernetes for audit. +- `uid`: The request's unique identifier. This cannot be populated by Kubernetes for audit. +- `userInfo`: The request's user's information such as `username`, `uid`, `groups`, `extra`. This cannot be populated by Kubernetes for audit. + +> **_NOTE_** For `input.review` fields above that cannot be populated by Kubernetes for audit reviews, the constraint templates that rely on them are not auditable. It is up to the rego author to handle the case where these fields are unset and empty in order to avoid every matching resource being reported as violating resources. + +You can see an example of the request structure below. + +```json +{ + "apiVersion": "admission.k8s.io/v1", + "kind": "AdmissionReview", + "request": { + "uid": "abc123", + "kind": { + "group": "apps", + "version": "v1", + "kind": "Deployment" + }, + "resource": { + "group": "apps", + "version": "v1", + "resource": "deployments" + }, + "namespace": "default", + "operation": "CREATE", + "userInfo": { + "username": "john_doe", + "groups": ["developers"] + }, + "object": { + // The resource object being created, updated, or deleted + "metadata": { + "name": "my-deployment", + "labels": { + "app": "my-app", + "env": "production" + } + }, + "spec": { + // Specific configuration for the resource + "replicas": 3, + // ... other fields ... + } + }, + "oldObject": { + // For update requests, the previous state of the resource + "metadata": { + "name": "my-deployment", + "labels": { + "app": "my-app", + "env": "staging" + } + }, + "spec": { + // Previous configuration for the resource + "replicas": 2, + // ... other fields ... + } + } + } +} +``` \ No newline at end of file diff --git a/website/sidebars.js b/website/sidebars.js index 34db5d6eeb0..33c8bc384ff 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -52,7 +52,10 @@ module.exports = { type: 'category', label: 'Concepts', collapsed: false, - items: ['mutation-background'] + items: [ + 'input', + 'mutation-background' + ] }, { type: 'category', diff --git a/website/versioned_docs/version-v3.14.x/howto.md b/website/versioned_docs/version-v3.14.x/howto.md index 764a5e85854..0eef2083683 100644 --- a/website/versioned_docs/version-v3.14.x/howto.md +++ b/website/versioned_docs/version-v3.14.x/howto.md @@ -138,16 +138,4 @@ kubectl get constraints ``` ### Input Review - -The `input.review` object stores the [admission request](https://pkg.go.dev/k8s.io/kubernetes/pkg/apis/admission#AdmissionRequest) under evaluation. It has the following fields: -- `dryRun`: Describes if the request was invoked by `kubectl --dry-run`. This cannot be populated by Kubernetes for audit. -- `kind`: The resource `kind`, `group`, `version` of the request object under evaluation. -- `name`: The name of the request object under evaluation. It may be empty if the deployment expects the API server to generate a name for the requested resource. -- `namespace`: The namespace of the request object under evaluation. Empty for cluster scoped objects. -- `object`: The request object under evaluation to be created or modified. -- `oldObject`: The original state of the request object under evaluation. This is only available for UPDATE operations. -- `operation`: The operation for the request (e.g. CREATE, UPDATE). This cannot be populated by Kubernetes for audit. -- `uid`: The request's unique identifier. This cannot be populated by Kubernetes for audit. -- `userInfo`: The request's user's information such as `username`, `uid`, `groups`, `extra`. This cannot be populated by Kubernetes for audit. - -> **_NOTE_** For `input.review` fields above that cannot be populated by Kubernetes for audit reviews, the constraint templates that rely on them are not auditable. It is up to the rego author to handle the case where these fields are unset and empty in order to avoid every matching resource being reported as violating resources. +You can view information on the `input.review` object that Gatekeeper takes as input [here](./input.md) \ No newline at end of file diff --git a/website/versioned_docs/version-v3.14.x/input.md b/website/versioned_docs/version-v3.14.x/input.md new file mode 100644 index 00000000000..488f1a54bb0 --- /dev/null +++ b/website/versioned_docs/version-v3.14.x/input.md @@ -0,0 +1,75 @@ +--- +id: input +title: Admission Review Input +--- + +The data that's passed to Gatekeeper for review is in the form of an `input.review` object that stores the [admission request](https://pkg.go.dev/k8s.io/kubernetes/pkg/apis/admission#AdmissionRequest) under evaluation. It follows a structure that contains the object being created, and in the case of update operations the old object being updated. It has the following fields: +- `dryRun`: Describes if the request was invoked by `kubectl --dry-run`. This cannot be populated by Kubernetes for audit. +- `kind`: The resource `kind`, `group`, `version` of the request object under evaluation. +- `name`: The name of the request object under evaluation. It may be empty if the deployment expects the API server to generate a name for the requested resource. +- `namespace`: The namespace of the request object under evaluation. Empty for cluster scoped objects. +- `object`: The request object under evaluation to be created or modified. +- `oldObject`: The original state of the request object under evaluation. This is only available for UPDATE operations. +- `operation`: The operation for the request (e.g. CREATE, UPDATE). This cannot be populated by Kubernetes for audit. +- `uid`: The request's unique identifier. This cannot be populated by Kubernetes for audit. +- `userInfo`: The request's user's information such as `username`, `uid`, `groups`, `extra`. This cannot be populated by Kubernetes for audit. + +> **_NOTE_** For `input.review` fields above that cannot be populated by Kubernetes for audit reviews, the constraint templates that rely on them are not auditable. It is up to the rego author to handle the case where these fields are unset and empty in order to avoid every matching resource being reported as violating resources. + +You can see an example of the request structure below. + +```json +{ + "apiVersion": "admission.k8s.io/v1", + "kind": "AdmissionReview", + "request": { + "uid": "abc123", + "kind": { + "group": "apps", + "version": "v1", + "kind": "Deployment" + }, + "resource": { + "group": "apps", + "version": "v1", + "resource": "deployments" + }, + "namespace": "default", + "operation": "CREATE", + "userInfo": { + "username": "john_doe", + "groups": ["developers"] + }, + "object": { + // The resource object being created, updated, or deleted + "metadata": { + "name": "my-deployment", + "labels": { + "app": "my-app", + "env": "production" + } + }, + "spec": { + // Specific configuration for the resource + "replicas": 3, + // ... other fields ... + } + }, + "oldObject": { + // For update requests, the previous state of the resource + "metadata": { + "name": "my-deployment", + "labels": { + "app": "my-app", + "env": "staging" + } + }, + "spec": { + // Previous configuration for the resource + "replicas": 2, + // ... other fields ... + } + } + } +} +``` \ No newline at end of file diff --git a/website/versioned_sidebars/version-v3.14.x-sidebars.json b/website/versioned_sidebars/version-v3.14.x-sidebars.json index d3102fabb8b..ea8ebb39ba1 100644 --- a/website/versioned_sidebars/version-v3.14.x-sidebars.json +++ b/website/versioned_sidebars/version-v3.14.x-sidebars.json @@ -53,6 +53,7 @@ "label": "Concepts", "collapsed": false, "items": [ + "input", "mutation-background" ] },