docs/usecases/contiv/SECURITY.rst

   1 Security
   2 ========
   3
   4 There are two types of security that are utilized in Contiv, and are
   5 discussed in this section: `HTTP <#http-security>`__ and
   6 `ETCD <#etcd-security>`__.
   7
   8 HTTP Security
   9 -------------
  10
  11 By default, the access to endpoints (liveness, readiness probe,
  12 prometheus stats, …) served by Contiv-vswitch and Contiv-ksr is open to
  13 anybody. Contiv-vswitch exposes endpoints using port ``9999`` and
  14 contiv-ksr uses ``9191``.
  15
  16 To secure access to the endpoints, the SSL/TLS server certificate and
  17 basic auth (username password) can be configured.
  18
  19 In Contiv-VPP, this can be done using the Helm charts in `k8s/contiv-vpp
  20 folder <https://github.com/contiv/vpp/tree/master/k8s/contiv-vpp>`__.
  21
  22 To generate server certificate the approach described in `ETCD
  23 security <#etcd-security>`__ can be leveraged.
  24
  25 ETCD Security
  26 -------------
  27
  28 By default, the access to Contiv-VPP ETCD is open to anybody. ETCD gets
  29 deployed on the master node, on port ``12379``, and is exposed using the
  30 NodePort service on port ``32379``, on each node.
  31
  32 To secure access to ETCD, we recommend using the SSL/TLS certificates to
  33 authenticate both the client and server side, and encrypt the
  34 communication. In Contiv-VPP, this can be done using the Helm charts in
  35 `k8s/contiv-vpp
  36 folder <https://github.com/contiv/vpp/tree/master/k8s/contiv-vpp>`__.
  37
  38 The prerequisite for that is the generation of SSL certificates.
  39
  40 Generate Self-Signed Certificates
  41 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  42
  43 In order to secure ETCD, we need to create our own certificate
  44 authority, and then generate the private keys and certificates for both
  45 the ETCD server and ETCD clients.
  46
  47 This guide uses CloudFlare’s
  48 `cfssl <https://github.com/cloudflare/cfssl>`__ tools to do this job. It
  49 follows the steps described in this `CoreOS
  50 guide <https://github.com/coreos/docs/blob/master/os/generate-self-signed-certificates.md>`__.
  51
  52 Perform the following steps to generate private keys and certificates:
  53
  54 1. Install cfssl
  55 ^^^^^^^^^^^^^^^^
  56
  57 ::
  58
  59    mkdir ~/bin
  60    curl -s -L -o ~/bin/cfssl https://pkg.cfssl.org/R1.2/cfssl_linux-amd64
  61    curl -s -L -o ~/bin/cfssljson https://pkg.cfssl.org/R1.2/cfssljson_linux-amd64
  62    chmod +x ~/bin/{cfssl,cfssljson}
  63    export PATH=$PATH:~/bin
  64
  65 2. Initialize a Certificate Authority
  66 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  67
  68 ::
  69
  70    echo '{"CN":"CA","key":{"algo":"rsa","size":2048}}' | cfssl gencert -initca - | cfssljson -bare ca -
  71    echo '{"signing":{"default":{"expiry":"43800h","usages":["signing","key encipherment","server auth","client auth"]}}}' > ca-config.json
  72
  73 3. Generate Server Key + Certificate
  74 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  75
  76 Replace the IP address ``10.0.2.15`` below with the IP address of your
  77 master node:
  78
  79 ::
  80
  81    export ADDRESS=127.0.0.1,10.0.2.15
  82    export NAME=server
  83    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
  84
  85 4. Generate Client Key + Certificate
  86 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  87
  88 ::
  89
  90    export ADDRESS=
  91    export NAME=client
  92    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
  93
  94 The above commands produce the following files that will be needed in
  95 order to secure ETCD: - ``ca.pem``: certificate of the certificate
  96 authority - ``server.pem``: certificate of the ETCD server -
  97 ``server-key.pem``: private key of the ETCD server - ``client.pem``:
  98 certificate for the ETCD clients - ``client-key.pem``: private key for
  99 the ETCD clients
 100
 101 Distribute Certificates and Generate Contiv-VPP Deployment Yaml
 102 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 103
 104 There are two options for distributing the certificates to all nodes in
 105 a k8s cluster. You can either distribute the certificates
 106 `manually <#distribute-certificates-manually>`__, or embed the
 107 certificates into the deployment yaml file and distribute them as `k8s
 108 secrets <https://kubernetes.io/docs/concepts/configuration/secret/>`__.
 109
 110 Distribute Certificates Manually
 111 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 112
 113 In this case, you need to copy the ``ca.pem``, ``client.pem`` and
 114 ``client-key.pem`` files into a specific folder
 115 (``/var/contiv/etcd-secrets`` by default) on each worker node. On the
 116 master node, you also need to add the ``server.pem`` and
 117 ``server-key.pem`` into that location.
 118
 119 Then you can generate the Contiv-VPP deployment YAML as follows:
 120
 121 ::
 122
 123    cd k8s
 124    helm template --name my-release contiv-vpp --set etcd.secureTransport=True > contiv-vpp.yaml
 125
 126 Then you can go ahead and deploy Contiv-VPP using this yaml file.
 127
 128 Embed the certificates into deployment the yaml and use k8s secret to distribute them {: #Embed-certificates }
 129 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 130
 131 In this case, you need to copy all 5 generated files into the folder
 132 with helm definitions (``k8s/contiv-vpp``) and generate the Contiv-VPP
 133 deployment YAML as follows:
 134
 135 ::
 136
 137    cd k8s
 138    helm template --name my-release contiv-vpp --set etcd.secureTransport=True --set etcd.secrets.mountFromHost=False > contiv-vpp.yaml
 139
 140 Then just deploy Contiv-VPP using this yaml file.
 141
 142 Please note that the path of the mount folder with certificates, as well
 143 as the certificate file names can be customized using the config
 144 parameters of the Contiv-VPP chart, as described in `this
 145 README <https://github.com/contiv/vpp/blob/master/k8s/contiv-vpp/README.md>`__.