kyverno/documentation/installation.md

<small>*[documentation](/README.md#documentation) / Installation*</small>

# Installation

To install Kyverno in your cluster run the following command on a host with kubectl access:

````sh
kubectl create -f https://github.com/nirmata/kyverno/raw/master/definitions/install.yaml
````

To check the Kyverno controller status, run the command:

````sh
kubectl get pods -n kyverno
````

If the Kyverno controller is not running, you can check its status and logs for errors:

````sh
kubectl describe pod <kyverno-pod-name> -n kyverno
````

````sh
kubectl logs <kyverno-pod-name> -n kyverno
````

# Installing in a Development Environment

To build and run Kyverno in a development environment see: https://github.com/nirmata/kyverno/wiki/Building

To check if the controller is working, find it in the list of kyverno pods:

`kubectl get pods -n kyverno`

# Try Kyverno without a Kubernetes cluster

The [Kyverno CLI](documentation/testing-policies-cli.md) allows you to write and test policies without installing Kyverno in a Kubernetes cluster.

# Pre-Requisites
Kyverno installs an admission webhook that requires a CA-signed certificate and key to setup TLS communication with the kube-apiserver. In-cluster mode, there are 2 ways to configure the admission webhook TLS configuration:
* Kyverno generates certificate and key pair for user, and a signed certificate is issued against the certificate signing request generated by Kyverno. This setup requires a 'certificate signer' configured in the cluster. The kube-controller-manager provides a default implementation of a signer which can be used to issue certificates. To verify if it is enabled, check if the command args `--cluster-signing-cert-file` and `--cluster-signing-key-file` are passed to the controller manager with paths to your CA's key-pair.
* Use self-signed certificates.

## Use self-signed certificates
To create a root CA, generate signed certificate and key using openssl:
1. `openssl genrsa -out rootCA.key 4096`
2. `openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.crt  -subj "/C=US/ST=test/L=test /O=test /OU=PIB/CN=*.kyverno.svc/emailAddress=test@test.com"`
3. `openssl genrsa -out webhook.key 4096`
4. `openssl req -new -key webhook.key -out webhook.csr  -subj "/C=US/ST=test /L=test /O=test /OU=PIB/CN=kyverno-svc.kyverno.svc/emailAddress=test@test.com"`
5. `openssl x509 -req -in webhook.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out webhook.crt -days 1024 -sha256`

the following files are generated and are used to create kubernetes secrets:
- rootCA.crt
- webhooks.crt
- webhooks.key	

To create the required secrets:
1. `kubectl create ns kyverno`
2. `kubectl -n kyverno create secret tls kyverno-svc.kyverno.svc.kyverno-tls-pair --cert=webhook.crt --key=webhook.key `
3. `kubectl annotate secret kyverno-svc.kyverno.svc.kyverno-tls-pair  -n kyverno self-signed-cert=true`
4. `kubectl -n kyverno create secret generic kyverno-svc.kyverno.svc.kyverno-tls-ca --from-file=rootCA.crt`

*The annotation on the TLS pair secret is used by Kyverno to identify the use of self-signed certificates and checks for the required root CA secret*

Secret | Data | Content
------------ | ------------- | -------------
`kyverno-svc.kyverno.svc.kyverno-tls-pair` | rootCA.crt | root CA used to sign the certificate
`kyverno-svc.kyverno.svc.kyverno-tls-ca` | tls.key & tls.crt  | key and signed certificate

Kyverno uses secrets created above to define the TLS configuration for the webserver hook and specify the CA bundle used to validate the webhook's server certificate in the admission webhook configurations.

To deploy the Kyverno project, run `kubectl create -f definitions/install.yaml`. You can ignore the error 'namespaces "kyverno" already exists', which occurs as we previously created the namespace while creating the secrets.

*If tls pair secret is created and secret for root CA is not defined, then Kyverno follows its default behaviour of generating new tls pair and generate certificate signing request for issuer to issue certificate.*

Script to generate self-signed certificate and corresponding kubernetes secrets: [helper script](/scripts/generate-self-signed-cert-and-k8secrets.sh)

---
<small>*Read Next >> [Writing Policies](/documentation/writing-policies.md)*</small>