mirror of
https://github.com/kyverno/kyverno.git
synced 2025-03-30 19:35:06 +00:00
update README.md - community and restructure
This commit is contained in:
Jim Bugwadia
parent
ed52bd3d9f
commit
29d9425272
5 changed files with 189 additions and 140 deletions
211
README.md
211
README.md
|
|
@ -1,158 +1,91 @@
|
|||
# Kyverno - Kubernetes Native Policy Management
|
||||
|
||||
[](https://travis-ci.org/nirmata/kyverno) [](https://goreportcard.com/report/github.com/nirmata/kyverno)
|
||||
[](https://travis-ci.org/nirmata/kyverno) [](https://goreportcard.com/report/github.com/nirmata/kyverno) 
|
||||
|
||||
|
||||
|
||||
Kyverno is a policy engine designed for Kubernetes.
|
||||
|
||||
Kyverno supports declarative validation, mutation, and generation of resource configurations using policies written as Kubernetes resources.
|
||||
|
||||
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.
|
||||
|
||||
Kyverno runs as a [dynamic admission controller](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/) in a Kubernetes cluster. Kyverno receives validating and mutating admission webhook HTTP callbacks from the kube-apiserver and applies matching policies to return results that enforce admission policies or reject requests.
|
||||
|
||||
Kyverno policies can match resources using the resource kind, name, and label selectors. Wildcards are supported in names.
|
||||
|
||||
Mutating policies can be written as overlays (similar to [Kustomize](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/#bases-and-overlays)) or as a [JSON Patch](http://jsonpatch.com/). Validating policies also use an overlay style syntax, with support for pattern matching and conditional (if-then-else) processing.
|
||||
|
||||
Policy enforcement is captured using Kubernetes events. Kyverno also reports policy violations for existing resources.
|
||||
|
||||
**NOTE** : Your Kubernetes cluster version must be above v1.14 which adds webook timeouts. To check the version, enter `kubectl version`.
|
||||
Kyverno is a `no-code` policy engine built for Kubernetes:
|
||||
* policies as Kubernetes resources (no additional language!)
|
||||
* validate, mutate, or generate any resource
|
||||
* match resources using label selectors and wildcards
|
||||
* validate and mutate using overlays (like Kustomize!)
|
||||
* generate and synchronize defaults across namespaces
|
||||
* block or report violations
|
||||
* test using kubectl
|
||||
|
||||
## Quick Start
|
||||
|
||||
**NOTE** : Your Kubernetes cluster version must be above v1.14 which adds webook timeouts. To check the version, enter `kubectl version`.
|
||||
|
||||
Install Kyverno:
|
||||
```console
|
||||
kubectl create -f https://github.com/nirmata/kyverno/raw/master/definitions/install.yaml
|
||||
```
|
||||
|
||||
You can also install using the [Helm chart](https://github.com/nirmata/kyverno/blob/master/documentation/installation.md#install-kyverno-using-helm). As a next step, import [sample policies](https://github.com/nirmata/kyverno/blob/master/samples/README.md) and learn about [writing policies](https://github.com/nirmata/kyverno/blob/master/documentation/writing-policies.md). You can test policies using the [Kyverno cli](https://github.com/nirmata/kyverno/blob/master/documentation/kyverno-cli.md). See [docs](https://github.com/nirmata/kyverno/#documentation) for more details.
|
||||
|
||||
## Examples
|
||||
You can also install Kyverno using a [Helm chart](https://github.com/nirmata/kyverno/blob/master/documentation/installation.md#install-kyverno-using-helm).
|
||||
|
||||
### 1. Validating resources
|
||||
Add the policy below. It requires that all pods have a `app.kubernetes.io/name` label:
|
||||
|
||||
This policy requires that all pods have CPU and memory resource requests and limits:
|
||||
|
||||
```yaml
|
||||
```console
|
||||
apiVersion: kyverno.io/v1
|
||||
kind: ClusterPolicy
|
||||
metadata:
|
||||
name: check-cpu-memory
|
||||
spec:
|
||||
# `enforce` blocks the request. `audit` reports violations
|
||||
validationFailureAction: enforce
|
||||
rules:
|
||||
- name: check-pod-resources
|
||||
match:
|
||||
resources:
|
||||
kinds:
|
||||
- Pod
|
||||
validate:
|
||||
message: "CPU and memory resource requests and limits are required"
|
||||
pattern:
|
||||
spec:
|
||||
containers:
|
||||
# 'name: *' selects all containers in the pod
|
||||
- name: "*"
|
||||
resources:
|
||||
limits:
|
||||
# '?' requires 1 alphanumeric character and '*' means that
|
||||
# there can be 0 or more characters. Using them together
|
||||
# e.g. '?*' requires at least one character.
|
||||
memory: "?*"
|
||||
cpu: "?*"
|
||||
requests:
|
||||
memory: "?*"
|
||||
cpu: "?*"
|
||||
```
|
||||
|
||||
This policy prevents users from changing default network policies:
|
||||
|
||||
```yaml
|
||||
apiVersion: kyverno.io/v1
|
||||
kind: ClusterPolicy
|
||||
metadata:
|
||||
name: deny-netpol-changes
|
||||
name: require-labels
|
||||
spec:
|
||||
validationFailureAction: enforce
|
||||
background: false
|
||||
rules:
|
||||
- name: check-netpol-updates
|
||||
match:
|
||||
resources:
|
||||
kinds:
|
||||
- NetworkPolicy
|
||||
name:
|
||||
- *-default
|
||||
exclude:
|
||||
clusterRoles:
|
||||
- cluster-admin
|
||||
validate:
|
||||
message: "Changing default network policies is not allowed"
|
||||
deny: {}
|
||||
- name: check-for-labels
|
||||
match:
|
||||
resources:
|
||||
kinds:
|
||||
- Pod
|
||||
validate:
|
||||
message: "label `app.kubernetes.io/name` is required"
|
||||
pattern:
|
||||
metadata:
|
||||
labels:
|
||||
app.kubernetes.io/name: "?*"
|
||||
```
|
||||
|
||||
Try creating a deployment without the required label:
|
||||
|
||||
### 2. Mutating resources
|
||||
```console
|
||||
kubectl create deployment nginx --image=nginx
|
||||
```
|
||||
|
||||
This policy sets the imagePullPolicy to Always if the image tag is latest:
|
||||
You should see an error:
|
||||
```console
|
||||
Error from server: admission webhook "nirmata.kyverno.resource.validating-webhook" denied the request:
|
||||
|
||||
```yaml
|
||||
apiVersion: kyverno.io/v1
|
||||
kind: ClusterPolicy
|
||||
resource Deployment/default/nginx was blocked due to the following policies
|
||||
|
||||
require-labels:
|
||||
autogen-check-for-labels: 'Validation error: label `app.kubernetes.io/name` is required;
|
||||
Validation rule autogen-check-for-labels failed at path /spec/template/metadata/labels/app.kubernetes.io/name/'
|
||||
```
|
||||
|
||||
Create a pod with the required label. For example from this YAML:
|
||||
```console
|
||||
kind: "Pod"
|
||||
apiVersion: "v1"
|
||||
metadata:
|
||||
name: set-image-pull-policy
|
||||
name: nginx
|
||||
labels:
|
||||
app.kubernetes.io/name: nginx
|
||||
spec:
|
||||
rules:
|
||||
- name: set-image-pull-policy
|
||||
match:
|
||||
resources:
|
||||
kinds:
|
||||
- Pod
|
||||
mutate:
|
||||
overlay:
|
||||
spec:
|
||||
containers:
|
||||
# match images which end with :latest
|
||||
- (image): "*:latest"
|
||||
# set the imagePullPolicy to "Always"
|
||||
imagePullPolicy: "Always"
|
||||
containers:
|
||||
- name: "nginx"
|
||||
image: "nginx:latest"
|
||||
```
|
||||
|
||||
### 3. Generating resources
|
||||
This pod is allowed. Clean up by deleting all cluster policies:
|
||||
|
||||
This policy sets the Zookeeper and Kafka connection strings for all namespaces.
|
||||
|
||||
```yaml
|
||||
apiVersion: kyverno.io/v1
|
||||
kind: ClusterPolicy
|
||||
metadata:
|
||||
name: "zk-kafka-address"
|
||||
spec:
|
||||
rules:
|
||||
- name: "zk-kafka-address"
|
||||
match:
|
||||
resources:
|
||||
kinds:
|
||||
- Namespace
|
||||
generate:
|
||||
kind: ConfigMap
|
||||
name: zk-kafka-address
|
||||
# generate the resource in the new namespace
|
||||
namespace: "{{request.object.metadata.name}}"
|
||||
synchronize : true
|
||||
data:
|
||||
kind: ConfigMap
|
||||
data:
|
||||
ZK_ADDRESS: "192.168.10.10:2181,192.168.10.11:2181,192.168.10.12:2181"
|
||||
KAFKA_ADDRESS: "192.168.10.13:9092,192.168.10.14:9092,192.168.10.15:9092"
|
||||
```console
|
||||
kubectl delete cpol --all
|
||||
```
|
||||
|
||||
**For more examples, refer to a list of curated of **_[sample policies](/samples/README.md)_** that can be applied to your cluster.**
|
||||
As a next step, browse the [sample policies](https://github.com/nirmata/kyverno/blob/master/samples/README.md) and learn about [writing policies](https://github.com/nirmata/kyverno/blob/master/documentation/writing-policies.md). You can test policies using the [Kyverno cli](https://github.com/nirmata/kyverno/blob/master/documentation/kyverno-cli.md). See [docs](https://github.com/nirmata/kyverno/#documentation) for complete details.
|
||||
|
||||
|
||||
## Documentation
|
||||
|
||||
|
|
@ -171,6 +104,13 @@ spec:
|
|||
- [Kyverno CLI](documentation/kyverno-cli.md)
|
||||
- [Sample Policies](/samples/README.md)
|
||||
|
||||
## License
|
||||
|
||||
[Apache License 2.0](https://github.com/nirmata/kyverno/blob/master/LICENSE)
|
||||
|
||||
## Community Call
|
||||
|
||||
To attend our next monthly community meeting join the [Kyverno group](https://groups.google.com/g/kyverno). You will then be sent a meeting invite and get access to the [agenda and meeting notes](https://docs.google.com/document/d/10Hu1qTip1KShi8Lf_v9C5UVQtp7vz_WL3WVxltTvdAc/edit#).
|
||||
|
||||
## Presentations and Articles
|
||||
|
||||
|
|
@ -181,10 +121,20 @@ spec:
|
|||
- [Virtual Rejekts Video](https://www.youtube.com/watch?v=caFMtSg4A6I)
|
||||
- [TGIK Video](https://www.youtube.com/watch?v=ZE4Zu9WQET4&list=PL7bmigfV0EqQzxcNpmcdTJ9eFRPBe-iZa&index=18&t=0s)
|
||||
|
||||
## Getting help
|
||||
|
||||
## License
|
||||
- For feature requests and bugs, file an [issue](https://github.com/nirmata/kyverno/issues).
|
||||
- For discussions or questions, join the **#kyverno** channel on the [Kubernetes Slack](https://kubernetes.slack.com/) or the [mailing list](https://groups.google.com/g/kyverno).
|
||||
|
||||
## Contributing
|
||||
|
||||
Thanks for your interest in contributing!
|
||||
|
||||
- Please review and agree to abide with the [Code of Conduct](/CODE_OF_CONDUCT.md) before contributing.
|
||||
- We encourage all contributions and encourage you to read our [contribution guidelines](./CONTRIBUTING.md).
|
||||
- See the [Wiki](https://github.com/nirmata/kyverno/wiki) for developer documentation.
|
||||
- Browse through the [open issues](https://github.com/nirmata/kyverno/issues)
|
||||
|
||||
[Apache License 2.0](https://github.com/nirmata/kyverno/blob/master/LICENSE)
|
||||
|
||||
## Alternatives
|
||||
|
||||
|
|
@ -208,16 +158,3 @@ Tools like [Kustomize](https://github.com/kubernetes-sigs/kustomize) can be used
|
|||
|
||||
See [Milestones](https://github.com/nirmata/kyverno/milestones) and [Issues](https://github.com/nirmata/kyverno/issues).
|
||||
|
||||
## Getting help
|
||||
|
||||
- For feature requests and bugs, file an [issue](https://github.com/nirmata/kyverno/issues).
|
||||
- For discussions or questions, join the **#kyverno** channel on the [Kubernetes Slack](https://kubernetes.slack.com/) or the [mailing list](https://groups.google.com/forum/#!forum/kyverno)
|
||||
|
||||
## Contributing
|
||||
|
||||
Thanks for your interest in contributing!
|
||||
|
||||
- Please review and agree to abide with the [Code of Conduct](/CODE_OF_CONDUCT.md) before contributing.
|
||||
- We encourage all contributions and encourage you to read our [contribution guidelines](./CONTRIBUTING.md).
|
||||
- See the [Wiki](https://github.com/nirmata/kyverno/wiki) for developer documentation.
|
||||
- Browse through the [open issues](https://github.com/nirmata/kyverno/issues)
|
||||
|
|
|
|||
|
|
@ -2,9 +2,11 @@
|
|||
|
||||
# Auto Generating Rules for Pod Controllers
|
||||
|
||||
Note: The Auto-Gen feature is only supported for validation rules with patterns and mutation rules with overlay. Validate - Deny rules and Generate rules are not supported.
|
||||
**Note: The auto-gen feature is only supported for validation rules with patterns and mutation rules with overlay. Validate - Deny rules and Generate rules are not supported.**
|
||||
|
||||
Writing policies on pods helps address all pod creation flows. However, when pod controllers are used, pod level policies result in errors not being reported when the pod controller object is created.
|
||||
Writing policies on pods helps address all pod creation flows.
|
||||
|
||||
However, when pod controllers 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -6,8 +6,34 @@ The ```generate``` rule can used to create additional resources when a new resou
|
|||
|
||||
The `generate` rule supports `match` and `exclude` blocks, like other rules. Hence, the trigger for applying this rule can be the creation of any resource and its possible to match or exclude API requests based on subjects, roles, etc.
|
||||
|
||||
Currently, the generate rule only triggers during an API request and does not support [background processing](/documentation/writing-policies-background.md). To keep resources synchronized across changes, you can use `synchronize : true`. Synchronize is disabled for the pre-existing generate policy that means User has to manually add `synchronize: true` for pre-existing generate policy
|
||||
The generate rule triggers during a API CREATE operation and does not support [background processing](/documentation/writing-policies-background.md). To keep resources synchronized across changes you can use `synchronize : true`.
|
||||
|
||||
This policy sets the Zookeeper and Kafka connection strings for all namespaces.
|
||||
|
||||
```yaml
|
||||
apiVersion: kyverno.io/v1
|
||||
kind: ClusterPolicy
|
||||
metadata:
|
||||
name: "zk-kafka-address"
|
||||
spec:
|
||||
rules:
|
||||
- name: "zk-kafka-address"
|
||||
match:
|
||||
resources:
|
||||
kinds:
|
||||
- Namespace
|
||||
generate:
|
||||
synchronize: true
|
||||
kind: ConfigMap
|
||||
name: zk-kafka-address
|
||||
# generate the resource in the new namespace
|
||||
namespace: "{{request.object.metadata.name}}"
|
||||
data:
|
||||
kind: ConfigMap
|
||||
data:
|
||||
ZK_ADDRESS: "192.168.10.10:2181,192.168.10.11:2181,192.168.10.12:2181"
|
||||
KAFKA_ADDRESS: "192.168.10.13:9092,192.168.10.14:9092,192.168.10.15:9092"
|
||||
```
|
||||
|
||||
## Example 1
|
||||
|
||||
|
|
|
|||
|
|
@ -8,6 +8,29 @@ By using a ```patch``` in the [JSONPatch - RFC 6902](http://jsonpatch.com/) form
|
|||
|
||||
Resource mutation occurs before validation, so the validation rules should not contradict the changes performed by the mutation section.
|
||||
|
||||
This policy sets the imagePullPolicy to Always if the image tag is latest:
|
||||
|
||||
```yaml
|
||||
apiVersion: kyverno.io/v1
|
||||
kind: ClusterPolicy
|
||||
metadata:
|
||||
name: set-image-pull-policy
|
||||
spec:
|
||||
rules:
|
||||
- name: set-image-pull-policy
|
||||
match:
|
||||
resources:
|
||||
kinds:
|
||||
- Pod
|
||||
mutate:
|
||||
overlay:
|
||||
spec:
|
||||
containers:
|
||||
# match images which end with :latest
|
||||
- (image): "*:latest"
|
||||
# set the imagePullPolicy to "Always"
|
||||
imagePullPolicy: "Always"
|
||||
```
|
||||
|
||||
## JSON Patch
|
||||
|
||||
|
|
|
|||
|
|
@ -7,6 +7,67 @@ A validation rule can be used to validate resources or to deny API requests base
|
|||
|
||||
To validate resource data, define a [pattern](#patterns) in the validation rule. To deny certain API requests define a [deny](#deny-rules) element in the validation rule along a set of conditions that control when to allow or deny the request.
|
||||
|
||||
This policy requires that all pods have CPU and memory resource requests and limits:
|
||||
|
||||
```yaml
|
||||
apiVersion: kyverno.io/v1
|
||||
kind: ClusterPolicy
|
||||
metadata:
|
||||
name: check-cpu-memory
|
||||
spec:
|
||||
# `enforce` blocks the request. `audit` reports violations
|
||||
validationFailureAction: enforce
|
||||
rules:
|
||||
- name: check-pod-resources
|
||||
match:
|
||||
resources:
|
||||
kinds:
|
||||
- Pod
|
||||
validate:
|
||||
message: "CPU and memory resource requests and limits are required"
|
||||
pattern:
|
||||
spec:
|
||||
containers:
|
||||
# 'name: *' selects all containers in the pod
|
||||
- name: "*"
|
||||
resources:
|
||||
limits:
|
||||
# '?' requires 1 alphanumeric character and '*' means that
|
||||
# there can be 0 or more characters. Using them together
|
||||
# e.g. '?*' requires at least one character.
|
||||
memory: "?*"
|
||||
cpu: "?*"
|
||||
requests:
|
||||
memory: "?*"
|
||||
cpu: "?*"
|
||||
```
|
||||
|
||||
This policy prevents users from changing default network policies:
|
||||
|
||||
```yaml
|
||||
apiVersion: kyverno.io/v1
|
||||
kind: ClusterPolicy
|
||||
metadata:
|
||||
name: deny-netpol-changes
|
||||
spec:
|
||||
validationFailureAction: enforce
|
||||
background: false
|
||||
rules:
|
||||
- name: check-netpol-updates
|
||||
match:
|
||||
resources:
|
||||
kinds:
|
||||
- NetworkPolicy
|
||||
name:
|
||||
- *-default
|
||||
exclude:
|
||||
clusterRoles:
|
||||
- cluster-admin
|
||||
validate:
|
||||
message: "Changing default network policies is not allowed"
|
||||
deny: {}
|
||||
```
|
||||
|
||||
## Patterns
|
||||
|
||||
A validation rule that checks resource data is defined as an overlay pattern that provides the desired configuration. Resource configurations must match fields and expressions defined in the pattern to pass the validation rule. The following rules are followed when processing the overlay pattern:
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue