mirrors/kyverno
1
0
Fork 0
mirror of https://github.com/kyverno/kyverno.git synced 2024-12-15 17:51:20 +00:00
Code Activity

update docs for new features

Browse source
This commit is contained in:
Jim Bugwadia 2020-02-06 00:04:19 -08:00
parent 46afbe5f14
commit 2068da18a8
9 changed files with 129 additions and 164 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
README.md
View file

@ -126,9 +126,11 @@ Refer to a list of curated of ***[sample policies](/samples/README.md)*** that c
* [Mutate](documentation/writing-policies-mutate.md)
* [Validate](documentation/writing-policies-validate.md)
* [Generate](documentation/writing-policies-generate.md)
* [Variables](documentation/writing-policies-variables.md)
* [Preconditions](documentation/writing-policies-preconditions.md)
* [Auto-Generation of Pod Controller Policies](documentation/writing-policies-autogen.md)
* [Background Processing](documentation/writing-policies-background.md)
* [Testing Policies](documentation/testing-policies.md)
* [Using kubectl](documentation/testing-policies.md#Test-using-kubectl)
* [Using the Kyverno CLI](documentation/testing-policies.md#Test-using-the-Kyverno-CLI)
* [Sample Policies](/samples/README.md)
## License

51
documentation/testing-policies.md
View file

@ -2,9 +2,11 @@
# Testing Policies
The resources definitions for testing are located in [/test](/test) directory. Each test contains a pair of files: one is the resource definition, and the second is the kyverno policy for this definition.
## Test using kubectl
To do this you should [install kyverno to the cluster](/documentation/installation.md).
For example, to test the simplest kyverno policy for ConfigMap, create the policy and then the resource itself via kubectl:
@ -19,52 +21,3 @@ Then compare the original resource definition in CM.yaml with the actual one:
````bash
kubectl get -f CM.yaml -o yaml
````
## Test using the Kyverno CLI
The Kyverno Command Line Interface (CLI) tool allows writing and testing policies without having to apply local policy changes to a cluster. You can also test policies without a Kubernetes clusters, but results may vary as default values will not be filled in.
### Building the CLI
You will need a [Go environment](https://golang.org/doc/install) setup.
1. Clone the Kyverno repo
````bash
git clone https://github.com/nirmata/kyverno/
````
2. Build the CLI
````bash
cd kyverno/cmd/kyverno
go build
````
Or, you can directly build and install the CLI using `go get`:
````bash
go get -u https://github.com/nirmata/kyverno/cmd/kyverno
````
### Using the CLI
The CLI loads default kubeconfig ($HOME/.kube/config) to test policies in Kubernetes cluster. If no kubeconfig is found, the CLI will test policies on raw resources.
To test a policy using the CLI type:
`kyverno apply @<policy> @<resource YAML file or folder>`
For example:
```bash
kyverno apply @../../examples/cli/policy-deployment.yaml @../../examples/cli/resources
```
To test a policy with the specific kubeconfig:
```bash
kyverno apply @../../examples/cli/policy-deployment.yaml @../../examples/cli/resources --kubeconfig $PATH_TO_KUBECONFIG_FILE
```
In future releases, the CLI will support complete validation and generation of policies.

20
documentation/writing-policies-autogen.md Normal file
View file

@ -0,0 +1,20 @@
<small>*[documentation](/README.md#documentation) / [Writing Policies](/documentation/writing-policies.md) / Auto-Generation for Pod Controllers*</small>
# Auto generating rules for pod controllers
Writing policies on pods helps address all pod creation flows. However, when pod cotrollers are used pod level policies result in errors not being reported when the pod controller object is created.
Kyverno solves this issue by supporting automatic generation of policy rules for pod controllers from a rule written for a pod.
This auto-generation behavior is controlled by the `pod-policies.kyverno.io/autogen-controllers` annotation.
By default, Kyverno inserts an annotation `pod-policies.kyverno.io/autogen-controllers=all`, to generate an additional rule that is applied to pod controllers: DaemonSet, Deployment, Job, StatefulSet.
You can change the annotation `pod-policies.kyverno.io/autogen-controllers` to customize the target pod controllers for the auto-generated rules. For example, Kyverno generates a rule for a `Deployment` if the annotation of policy is defined as `pod-policies.kyverno.io/autogen-controllers=Deployment`.
When a `name` or `labelSelector` is specified in the match / exclude block, Kyverno skips generating pod controllers rule as these filters may not be applicable to pod controllers.
To disable auto-generating rules for pod controllers set `pod-policies.kyverno.io/autogen-controllers` to the value `none`.
<small>*Read Next >> [Background Processing](/documentation/writing-policies-background.md)*</small>

20
documentation/writing-policies-background.md Normal file
View file

@ -0,0 +1,20 @@
<small>*[documentation](/README.md#documentation) / [Writing Policies](/documentation/writing-policies.md) / Background Processing*</small>
# Background processing
Kyverno applies policies during admission control and to existing resources in the cluster that may have been created before a policy was created. The application of policies to existing resources is referred to as `background` processing.
Note, that Kyverno does not mutate existing resources, and will only report policy violation for existing resources that do not match mutation, validation, or generation rules.
A policy is always enabled for processing during admission control. However, policy rules that rely on request information (e.g. `{{request.userInfo}}`) cannot be applied to existing resource in the `background` mode as the user information is not available outside of the admission controller. Hence, these rules must use the boolean flag `{spec.background}` to disable `background` processing.
```
spec:
background: true
rules:
- name: default-deny-ingress
```
The default value of `background` is `true`. When a policy is created or modified, the policy validation logic will report an error if a rule uses `userInfo` and does not set `background` to `false`.
<small>*Read Next >> [Testing Policies](/documentation/testing-policies.md)*</small>

3
documentation/writing-policies-generate.md
View file

@ -87,5 +87,6 @@ spec:
In this example, when the policy is applied, any new namespace will receive a NetworkPolicy based on the specified template that by default denies all inbound and outbound traffic.
---
<small>*Read Next >> [Testing Policies](/documentation/testing-policies.md)*</small>
<small>*Read Next >> [Variables](/documentation/writing-policies-variables.md)*</small>

2
documentation/writing-policies-mutate.md
View file

@ -2,7 +2,7 @@
# Mutate Configurations
The ```mutate``` rule contains actions that will be applied to matching resources. A mutate rule can be written as a JSON Patch or as an overlay.
The ```mutate``` rule can be used to add, replace, or delete elements in matching resources. A mutate rule can be written as a JSON Patch or as an overlay.
By using a ```patch``` in the (JSONPatch - RFC 6902)[http://jsonpatch.com/] format, you can make precise changes to the resource being created. Using an ```overlay``` is convenient for describing the desired state of the resource.

30
documentation/writing-policies-preconditions.md Normal file
View file

@ -0,0 +1,30 @@
<small>*[documentation](/README.md#documentation) / [Writing Policies](/documentation/writing-policies.md) / Preconditions*</small>
# Preconditions
Preconditions allow controlling policy rule execution based on variable values.
While `match` & `exclude` conditions allow filtering requests based on resource and user information, `preconditions` can be used to define custom filters for more granular control.
The following operators are currently supported for preconditon evaluation:
- Equal
- NotEqual
## Example
```yaml
- name: generate-owner-role
match:
resources:
kinds:
- Namespace
preconditions:
- key: "{{serviceAccountName}}"
operator: NotEqual
value: ""
```
In the above example, the rule is only applied to requests from service accounts i.e. when the `{{serviceAccountName}}` is not empty.
<small>*Read Next >> [Auto-Generation for Pod Controllers](/documentation/writing-policies-autogen.md)*</small>

35
documentation/writing-policies-variables.md Normal file
View file

@ -0,0 +1,35 @@
<small>*[documentation](/README.md#documentation) / [Writing Policies](/documentation/writing-policies.md) / Variables*</small>
# Variables
Sometimes it is necessary to vary the contents of a mutated or generated resource based on request data. To achieve this, variables can be used to reference attributes that are loaded in the rule processing context using a [JMESPATH](http://jmespath.org/) notation.
The policy engine will substitute any values with the format `{{<JMESPATH>}}` with the variable value before processing the rule.
The following data is available for use in context:
- Resource: `{{request.object}}`
- UserInfo: `{{request.userInfo}}`
## Pre-defined Variables
Kyverno automatically creates a few useful variables:
- `serviceAccountName` : the last part of a service account i.e. without the suffix `system:serviceaccount:<namespace>:` and stores the userName. For example, when processing a request from `system:serviceaccount:nirmata:user1` Kyverno will store the value `user1` in the variable `serviceAccountName`.
- `serviceAccountNamespace` : the `namespace` portion of the serviceAccount. For example, when processing a request from `system:serviceaccount:nirmata:user1` Kyverno will store `nirmata` in the variable `serviceAccountNamespace`.
## Examples
1. Reference a resource name (type string)
`{{request.object.metadata.name}}`
2. Build name from multiple variables (type string)
`"ns-owner-{{request.object.metadata.namespace}}-{{request.userInfo.username}}-binding"`
3. Reference the metadata (type object)
`{{request.object.metadata}}`
<small>*Read Next >> [Preconditions](/documentation/writing-policies-preconditions.md)*</small>

126
documentation/writing-policies.md
View file

@ -6,11 +6,17 @@ The following picture shows the structure of a Kyverno Policy:
![KyvernoPolicy](images/Kyverno-Policy-Structure.png)
Each Kyverno policy contains one or more rules. Each rule has a match clause, an optional excludes clause, and a mutate, validate, or generate clause.
Each Kyverno policy contains one or more rules. Each rule has a `match` clause, an optional `exclude` clause, and one of a `mutate`, `validate`, or `generate` clause.
The match / exclude clauses have the same structure, and can contain the following elements:
* resources: select resources by name, namespaces, kinds, and label selectors.
* subjects: select users and user groups
* roles: select namespaced roles
* clusterroles: select cluster wide roles
When Kyverno receives an admission controller request, i.e. a validation or mutation webhook, it first checks to see if the resource and user information matches or should be excluded from processing. If both checks pass, then the rule logic to mutate, validate, or generate resources is applied.
The following YAML provides an example for the match and validate clauses.
The following YAML provides an example for a match clause.
````yaml
apiVersion : kyverno.io/v1
@ -31,11 +37,11 @@ spec :
kinds: # Required, list of kinds
- Deployment
- StatefulSet
name: "mongo*" # Optional, a resource name is optional. Name supports wildcards * and ?
namespaces: # Optional, list of namespaces. Supports wilcards * and ?
name: "mongo*" # Optional, a resource name is optional. Name supports wildcards (* and ?)
namespaces: # Optional, list of namespaces. Supports wildcards (* and ?)
- "dev*"
- test
selector: # Optional, a resource selector is optional. Selector values support wildcards * and ?
selector: # Optional, a resource selector is optional. Values support wildcards (* and ?)
matchLabels:
app: mongodb
matchExpressions:
@ -47,116 +53,14 @@ spec :
# Optional, roles to be matched
roles:
# Optional, clusterroles to be matched
clusterroles:
# Resources that need to be excluded
exclude: # Optional, resources to be excluded from evaulation
resources:
kinds:
- Daemonsets
name: "*"
namespaces:
- prod
- "kube*"
selector:
matchLabels:
app: mongodb
matchExpressions:
- {key: tier, operator: In, values: [database]}
# Optional, subjects to be excluded
subjects:
# Optional, roles to be excluded
roles:
# Optional, clusterroles to be excluded
clusterroles:
- cluster-admin
- admin
# rule is evaluated if the preconditions are satisfied
# all preconditions are AND/&& operation
preconditions:
- key: name # compares (key operator value)
operator: Equal
value: name # constant "name" == "name"
- key: "{{serviceAccountName}}" # refer to a pre-defined variable serviceAccountName
operator: NotEqual
value: "user1" # if service
# Each rule can contain a single validate, mutate, or generate directive
...
clusterroles: cluster-admin
...
````
Each rule can validate, mutate, or generate configurations of matching resources. A rule definition can contain only a single **mutate**, **validate**, or **generate** child node. These actions are applied to the resource in described order: mutation, validation and then generation.
# Variables:
Variables can be used to reference attributes that are loaded in the context using a [JMESPATH](http://jmespath.org/) search path.
Format: `{{<JMESPATH>}}`
Resources available in context:
- Resource: `{{request.object}}`
- UserInfo: `{{request.userInfo}}`
## Pre-defined Variables
- `serviceAccountName` : the variable removes the suffix system:serviceaccount:<namespace>: and stores the userName.
Example userName=`system:serviceaccount:nirmata:user1` will store variable value as `user1`.
- `serviceAccountNamespace` : extracts the `namespace` of the serviceAccount.
Example userName=`system:serviceaccount:nirmata:user1` will store variable value as `nirmata`.
Examples:
1. Refer to resource name(type string)
`{{request.object.metadata.name}}`
2. Build name from multiple variables(type string)
`"ns-owner-{{request.object.metadata.namespace}}-{{request.userInfo.username}}-binding"`
3. Refer to metadata struct/object(type object)
`{{request.object.metadata}}`
# PreConditions:
Apart from using `match` & `exclude` conditions on resource to filter which resources to apply the rule on, `preconditions` can be used to define custom filters.
```yaml
- name: generate-owner-role
match:
resources:
kinds:
- Namespace
preconditions:
- key: "{{request.userInfo.username}}"
operator: NotEqual
value: ""
```
In the above example, if the variable `{{request.userInfo.username}}` is blank then we dont apply the rule on resource.
Operators supported:
- Equal
- NotEqual
# Background processing
Kyverno applies policies in foreground and background mode.
- `foreground`: leverages admission control webhooks to intercept, and apply policies on, API requests for resource changes.
- `background`: policy-controller applies policies on the existing resoruces after configured re-conciliation time.
A policy is always enabled for `foreground` processing, but `background` processing is configurable using a boolean flag at `{spec.background}`.
```
spec:
background: true
rules:
- name: default-deny-ingress
```
- Unless specified the default value is `true`
- As the userInformation is only avaiable in the incoming api-request, a policy using userInfo filters and variables reffering to `{{request.userInfo}}` can only be processed in foreground mode.
- When a new policy is created, the policy validation will throw an error if using `userInfo` with a policy defined in background mode.
# Auto generating rules for pod controllers
Writing policies on pods helps address all pod creation flows, but results in errors not being reported when a pod controller object is created. Kyverno solves this issue, by automatically generating rules for pod controllers from a rule written for a pod.
This behavior is controlled by the pod-policies.kyverno.io/autogen-controllers annotation. By default, Kyverno inserts an annotation `pod-policies.kyverno.io/autogen-controllers=all`, to generate an additional rule that is applied to pod controllers: DaemonSet, Deployment, Job, StatefulSet.
Change the annotation `pod-policies.kyverno.io/autogen-controllers` to customize the applicable pod controllers of the auto-gen rule. For example, Kyverno generates the rule for `Deployment` if the annotation of policy is defined as `pod-policies.kyverno.io/autogen-controllers=Deployment`. If `name` or `labelSelector` is specified in the match / exclude block, Kyverno skips generating pod controllers rule as these filters may not be applicable to pod controllers.
To disable auto-generating rules for pod controllers, set `pod-policies.kyverno.io/autogen-controllers=none`.
---
<small>*Read Next >> [Validate](/documentation/writing-policies-validate.md)*</small>