1 files changed, 145 insertions, 0 deletions
diff --git a/docs/usecases/contiv/SECURITY.rst b/docs/usecases/contiv/SECURITY.rst
new file mode 100644
index 00000000000..8e8308e8ba5
--- /dev/null
+++ b/docs/usecases/contiv/SECURITY.rst
@@ -0,0 +1,145 @@
+Security
+========
+
+There are two types of security that are utilized in Contiv, and are
+discussed in this section: `HTTP <#http-security>`__ and
+`ETCD <#etcd-security>`__.
+
+HTTP Security
+-------------
+
+By default, the access to endpoints (liveness, readiness probe,
+prometheus stats, …) served by Contiv-vswitch and Contiv-ksr is open to
+anybody. Contiv-vswitch exposes endpoints using port ``9999`` and
+contiv-ksr uses ``9191``.
+
+To secure access to the endpoints, the SSL/TLS server certificate and
+basic auth (username password) can be configured.
+
+In Contiv-VPP, this can be done using the Helm charts in `k8s/contiv-vpp
+folder <https://github.com/contiv/vpp/tree/master/k8s/contiv-vpp>`__.
+
+To generate server certificate the approach described in `ETCD
+security <#etcd-security>`__ can be leveraged.
+
+ETCD Security
+-------------
+
+By default, the access to Contiv-VPP ETCD is open to anybody. ETCD gets
+deployed on the master node, on port ``12379``, and is exposed using the
+NodePort service on port ``32379``, on each node.
+
+To secure access to ETCD, we recommend using the SSL/TLS certificates to
+authenticate both the client and server side, and encrypt the
+communication. In Contiv-VPP, this can be done using the Helm charts in
+`k8s/contiv-vpp
+folder <https://github.com/contiv/vpp/tree/master/k8s/contiv-vpp>`__.
+
+The prerequisite for that is the generation of SSL certificates.
+
+Generate Self-Signed Certificates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to secure ETCD, we need to create our own certificate
+authority, and then generate the private keys and certificates for both
+the ETCD server and ETCD clients.
+
+This guide uses CloudFlare’s
+`cfssl <https://github.com/cloudflare/cfssl>`__ tools to do this job. It
+follows the steps described in this `CoreOS
+guide <https://github.com/coreos/docs/blob/master/os/generate-self-signed-certificates.md>`__.
+
+Perform the following steps to generate private keys and certificates:
+
+1. Install cfssl
+^^^^^^^^^^^^^^^^
+
+::
+
+   mkdir ~/bin
+   curl -s -L -o ~/bin/cfssl https://pkg.cfssl.org/R1.2/cfssl_linux-amd64
+   curl -s -L -o ~/bin/cfssljson https://pkg.cfssl.org/R1.2/cfssljson_linux-amd64
+   chmod +x ~/bin/{cfssl,cfssljson}
+   export PATH=$PATH:~/bin
+
+2. Initialize a Certificate Authority
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+   echo '{"CN":"CA","key":{"algo":"rsa","size":2048}}' | cfssl gencert -initca - | cfssljson -bare ca -
+   echo '{"signing":{"default":{"expiry":"43800h","usages":["signing","key encipherment","server auth","client auth"]}}}' > ca-config.json
+
+3. Generate Server Key + Certificate
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Replace the IP address ``10.0.2.15`` below with the IP address of your
+master node:
+
+::
+
+   export ADDRESS=127.0.0.1,10.0.2.15
+   export NAME=server
+   echo '{"CN":"'$NAME'","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -config=ca-config.json -ca=ca.pem -ca-key=ca-key.pem -hostname="$ADDRESS" - | cfssljson -bare $NAME
+
+4. Generate Client Key + Certificate
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+   export ADDRESS=
+   export NAME=client
+   echo '{"CN":"'$NAME'","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -config=ca-config.json -ca=ca.pem -ca-key=ca-key.pem -hostname="$ADDRESS" - | cfssljson -bare $NAME
+
+The above commands produce the following files that will be needed in
+order to secure ETCD: - ``ca.pem``: certificate of the certificate
+authority - ``server.pem``: certificate of the ETCD server -
+``server-key.pem``: private key of the ETCD server - ``client.pem``:
+certificate for the ETCD clients - ``client-key.pem``: private key for
+the ETCD clients
+
+Distribute Certificates and Generate Contiv-VPP Deployment Yaml
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are two options for distributing the certificates to all nodes in
+a k8s cluster. You can either distribute the certificates
+`manually <#distribute-certificates-manually>`__, or embed the
+certificates into the deployment yaml file and distribute them as `k8s
+secrets <https://kubernetes.io/docs/concepts/configuration/secret/>`__.
+
+Distribute Certificates Manually
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In this case, you need to copy the ``ca.pem``, ``client.pem`` and
+``client-key.pem`` files into a specific folder
+(``/var/contiv/etcd-secrets`` by default) on each worker node. On the
+master node, you also need to add the ``server.pem`` and
+``server-key.pem`` into that location.
+
+Then you can generate the Contiv-VPP deployment YAML as follows:
+
+::
+
+   cd k8s
+   helm template --name my-release contiv-vpp --set etcd.secureTransport=True > contiv-vpp.yaml
+
+Then you can go ahead and deploy Contiv-VPP using this yaml file.
+
+Embed the certificates into deployment the yaml and use k8s secret to distribute them {: #Embed-certificates }
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In this case, you need to copy all 5 generated files into the folder
+with helm definitions (``k8s/contiv-vpp``) and generate the Contiv-VPP
+deployment YAML as follows:
+
+::
+
+   cd k8s
+   helm template --name my-release contiv-vpp --set etcd.secureTransport=True --set etcd.secrets.mountFromHost=False > contiv-vpp.yaml
+
+Then just deploy Contiv-VPP using this yaml file.
+
+Please note that the path of the mount folder with certificates, as well
+as the certificate file names can be customized using the config
+parameters of the Contiv-VPP chart, as described in `this
+README <https://github.com/contiv/vpp/blob/master/k8s/contiv-vpp/README.md>`__.