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
## Configure controller manager certificate signer
When the cluster ca & key is not passed as arguments(mostly for in-cluster mode), the TLS communicate between admission webhook and api-server a certificate signer configured to issue certificate to a certificate signing request(CSR) generated by Kyverno.
The Kubernetes controller manager provides a default implementation of a signer. 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 Certificate Authority’s keypair. 

## Use self-signed certificates to test kyverno.
To create root CA and generate certificate & key pair using it via 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 generated files are used to create secrets:
- rootCA.crt
- webhooks.crt
- webhooks.key	

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

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

Here, we create the project namespace ‘kyverno’, followed by secrets for CA and TLS pair(cert,key). If the above secrets are defined then the kyverno Webhooks would use these to define the TLS pair for web server and CA bundle used to validate the webhook's server certificate in the Mutating/Validating Webhooks configuration.

To deploy the kyverno project, run `kubectl create -f definitions/install.yaml`. You can ignore the error 'namespaces "kyverno" already exists', as we have already created the namespace 'kyverno' while defining the secrets the previous step.

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