mirrors/kyverno
mirrors/kyverno
1
0
Fork 0
mirror of https://github.com/kyverno/kyverno.git synced 2025-03-06 16:06:56 +00:00
Code Activity

Merge pull request #467 from nirmata/453_update_docs

Browse source 
update main page and mutation docs
This commit is contained in:
Jim Bugwadia 2019-11-12 16:23:04 -08:00 • committed by GitHub
commit f0841e35b1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 75 additions and 49 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
README.md
View file

@ -6,9 +6,9 @@
Kyverno is a policy engine designed for Kubernetes.
Kubernetes supports declarative management of objects using configurations written in YAML or JSON. Often, parts of the configuration will need to vary based on the runtime environment. For portability, and for separation of concerns, its best to maintain environment specific configurations separately from workload configurations.
Kubernetes supports declarative validation, mutation, and generation of resource configurations using policies written as Kubernetes resources.
Kyverno allows cluster adminstrators to manage environment specific configurations independently of workload configurations and enforce configuration best practices for their clusters.
Kyverno can be used to scan existing workloads for best practices, or can be used to enforce best practices by blocking or mutating API requests.Kyverno allows cluster adminstrators to manage environment specific configurations independently of workload configurations and enforce configuration best practices for their clusters.
Kyverno policies are Kubernetes resources that can be written in YAML or JSON. Kyverno policies can validate, mutate, and generate any Kubernetes resources.
@ -115,29 +115,12 @@ spec:
### 4. More examples
Refer to a list of curated of [kyverno policies](/samples/README.md) to follow kubernetes best practices.
Refer to a list of curated of ***[sample policies](/samples/README.md)*** that can be applied to your cluster.
## License
[Apache License 2.0](https://github.com/nirmata/kyverno/blob/master/LICENSE)
## Status
*Kyverno is under active development and not ready for production use. Key components and policy definitions are likely to change as we complete core features.*
## Alternatives
### Open Policy Agent
[Open Policy Agent (OPA)](https://www.openpolicyagent.org/) is a general-purpose policy engine that can be used as a Kubernetes admission controller. It supports a large set of use cases. Policies are written using [Rego](https://www.openpolicyagent.org/docs/latest/how-do-i-write-policies#what-is-rego) a custom query language.
### Polaris
[Polaris](https://github.com/reactiveops/polaris) validates configurations for best practices. It includes several checks across health, networking, security, etc. Checks can be assigned a severity. A dashboard reports the overall score.
### External configuration management tools
Tools like [Kustomize](https://github.com/kubernetes-sigs/kustomize) can be used to manage variations in configurations outside of clusters. There are several advantages to this approach when used to produce variations of the same base configuration. However, such solutions cannot be used to validate or enforce configurations.
## Documentation
@ -150,14 +133,29 @@ Tools like [Kustomize](https://github.com/kubernetes-sigs/kustomize) can be used
* [Using kubectl](documentation/testing-policies.md#Test-using-kubectl)
* [Using the Kyverno CLI](documentation/testing-policies.md#Test-using-the-Kyverno-CLI)
## Alternatives
### Open Policy Agent
[Open Policy Agent (OPA)](https://www.openpolicyagent.org/) is a general-purpose policy engine that can be used as a Kubernetes admission controller. It supports a large set of use cases. Policies are written using [Rego](https://www.openpolicyagent.org/docs/latest/how-do-i-write-policies#what-is-rego) a custom query language.
### k-rail
[k-rail](https://github.com/cruise-automation/k-rail/) provides several ready to use policies for security and multi-tenancy. The policies are written in Golang. Several of the [Kyverno sample policies](/samples/README.md were inspired by k-rail policies.
### Polaris
[Polaris](https://github.com/reactiveops/polaris) validates configurations for best practices. It includes several checks across health, networking, security, etc. Checks can be assigned a severity. A dashboard reports the overall score.
### External configuration management tools
Tools like [Kustomize](https://github.com/kubernetes-sigs/kustomize) can be used to manage variations in configurations outside of clusters. There are several advantages to this approach when used to produce variations of the same base configuration. However, such solutions cannot be used to validate or enforce configurations.
## Roadmap
Here are some the major features we plan on completing before a 1.0 release:
* [Events](https://github.com/nirmata/kyverno/issues/14)
* [Policy Violations](https://github.com/nirmata/kyverno/issues/24)
* [Conditionals on existing resources](https://github.com/nirmata/kyverno/issues/57)
* [Extend CLI to operate on cluster resources ](https://github.com/nirmata/kyverno/issues/164)
See [Milestones](https://github.com/nirmata/kyverno/milestones) and [Issues](https://github.com/nirmata/kyverno/issues).
## Getting help
@ -166,7 +164,7 @@ Here are some the major features we plan on completing before a 1.0 release:
## Contributing
Welcome to our community and thanks for contributing!
Thanks for your interest in contributing!
* Please review and agree to abide with the [Code of Conduct](/CODE_OF_CONDUCT.md) before contributing.
* See the [Wiki](https://github.com/nirmata/kyverno/wiki) for developer documentation.

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

@ -2,17 +2,23 @@
# Mutate Configurations
The ```mutate``` rule contains actions that will be applied to matching resource before their creation. 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.
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.
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.
Resource mutation occurs before validation, so the validation rules should not contradict the changes performed by the mutation section.
## Anchors
| Anchor | Tag | Behavior |
|------------- |----- |--------------------------------------------- |
| Conditional | () | Add the specified tag |
| Add | +() | Add if the tag if not specified |
## Patches
## JSON Patch
A JSON Patch rule provides an alternate way to mutate resources.
[JSONPatch](http://jsonpatch.com/) supports the following operations (in the 'op' field):
* **add**
* **replace**
* **remove**
With Kyverno, the add and replace have the same behavior i.e. both operations will add or replace the target element.
This patch adds an init container to all deployments.
@ -37,14 +43,9 @@ spec :
name: "init-secrets"
````
[JSONPatch](http://jsonpatch.com/) supports the following operations (in the 'op' field):
* **add**
* **replace**
* **remove**
With Kyverno, the add and replace have the same behavior i.e. both operations will add or replace the target element.
Here is the example of a patch that removes a label from the secret:
````yaml
apiVersion : kyverno.io/v1alpha1
kind : ClusterPolicy
@ -65,9 +66,11 @@ spec :
Note, that if **remove** operation cannot be applied, then this **remove** operation will be skipped with no error.
## Overlay
## Mutate Overlay
A mutation overlay describes the desired form of resource. The existing resource values are replaced with the values specified in the overlay. If a value is specified in the overlay but not present in the target resource, then it will be added to the resource. The overlay cannot be used to delete values in a resource: use **patches** for this purpose.
A mutation overlay describes the desired form of resource. The existing resource values are replaced with the values specified in the overlay. If a value is specified in the overlay but not present in the target resource, then it will be added to the resource.
The overlay cannot be used to delete values in a resource: use **patches** for this purpose.
The following mutation overlay will add (or replace) the memory request and limit to 10Gi for every Pod with a label ```memory: high```:
@ -124,9 +127,26 @@ spec:
````
### Conditional logic using anchors
An **anchor** field, marked by parentheses, allows conditional processing of configurations. Processing stops when the anchor value does not match. Once processing stops, any child elements or any remaining siblings in a list, will not be processed.
An **anchor** field, marked by parentheses and an optional preceeding character, allows conditional processing for mutations.
The mutate overlay rules support two types of anchors:
| Anchor | Tag | Behavior |
|--------------------|----- |----------------------------------------------------- |
| Conditional | () | Use the tag and value as an "if" condition |
| Add if not present | +() | Add the tag value, if the tag is not already present |
The **anchors** values support **wildcards**:
1. `*` - matches zero or more alphanumeric characters
2. `?` - matches a single alphanumeric character
#### Conditional anchor
A `conditional anchor` evaluates to `true` if the anchor tag exists and if the value matches the specified value. Processing stops if a tag does not exist or when the value does not match. Once processing stops, any child elements or any remaining siblings in a list, will not be processed.
For example, this overlay will add or replace the value 6443 for the port field, for all ports with a name value that starts with "secure":
@ -150,16 +170,15 @@ spec :
port: 6443
````
The **anchors** values support **wildcards**:
1. `*` - matches zero or more alphanumeric characters
2. `?` - matches a single alphanumeric character
If the anchor tag value is an object or array, the entire object or array must match. In other words, the entire object or array becomes part of the "if" clause. Nested `conditional anchor` tags are not supported.
### Add if not present anchor
### Add if not present
A variation of an anchor, is to add a field value if it is not already defined. This is done by using the `add anchor` (short for `add if not present anchor`) with the notation ````+(...)```` for the tag.
A variation of an anchor, is to add a field value if it is not already defined. This is done by using the ````+(...)```` notation for the field.
An `add anchor` is processed as part of applying the mutation. Typically, every non-anchor tag-value is applied as part of the mutation. If the `add anchor` is set on a tag, the tag and value are only applied if they do not exist in the resource.
For example, this overlay will set the port to 6443, if a port is not already defined:
For example, this overlay will set the port to 6443, if a port is not already defined:
````yaml
apiVersion: kyverno.io/v1alpha1
@ -180,6 +199,15 @@ spec :
+(port): 6443
````
#### Anchor processing flow
The anchor processing behavior for mutate conditions is as follows:
1. First, all conditional anchors are processed. Processing stops when the first conditional anchor return a `false`. Mutation proceeds only of all conditional anchors return a `true`. Note that for `conditional anchor` tags with complex (object or array) values the entire value (child) object is treated as part of the condition, as explained above.
2. Next, all tag-values without anchors and all `add anchor` tags are processed to apply the mutation.
## Additional Details
Additional details on mutation overlay behaviors are available on the wiki: [Mutation Overlay](https://github.com/nirmata/kyverno/wiki/Mutation-Overlay)