docs/oom_setup_kubernetes_rancher.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2018 Amdocs, Bell Canada
   4
   5 .. Links
   6 .. _HELM Best Practices Guide: https://docs.helm.sh/chart_best_practices/#requirements
   7 .. _kubectl Cheat Sheet: https://kubernetes.io/docs/reference/kubectl/cheatsheet/
   8 .. _Kubernetes documentation for emptyDir: https://kubernetes.io/docs/concepts/storage/volumes/#emptydir
   9 .. _Docker DevOps: https://wiki.onap.org/display/DW/Docker+DevOps#DockerDevOps-DockerBuild
  10 .. _http://cd.onap.info:30223/mso/logging/debug: http://cd.onap.info:30223/mso/logging/debug
  11 .. _Onboarding and Distributing a Vendor Software Product: https://wiki.onap.org/pages/viewpage.action?pageId=1018474
  12 .. _README.md: https://gerrit.onap.org/r/gitweb?p=oom.git;a=blob;f=kubernetes/README.md
  13
  14 .. figure:: oomLogoV2-medium.png
  15    :align: right
  16
  17 .. _onap-on-kubernetes-with-rancher:
  18
  19 ONAP on HA Kubernetes Cluster
  20 #############################
  21
  22 This guide provides instructions on how to setup a Highly-Available Kubernetes Cluster.
  23 For this, we are hosting our cluster on OpenStack VMs and using the Rancher Kubernetes Engine (RKE)
  24 to deploy and manage our Kubernetes Cluster.
  25
  26 The result at the end of this tutorial will be:
  27
  28 *1.* Creation of a Key Pair to use with Open Stack and RKE
  29
  30 *2.* Creation of OpenStack VMs to host Kubernetes Control Plane
  31
  32 *3.* Creation of OpenStack VMs to host Kubernetes Workers
  33
  34 *4.* Installation and configuration of RKE to setup an HA Kubernetes
  35
  36 *5.* Installation and configuration of kubectl
  37
  38 *5.* Installation and configuration of helm
  39
  40 *7.* Creation of an NFS Server to be used by ONAP as shared persistance
  41
  42 There are many ways one can execute the above steps. Including automation through the use of HEAT to setup the OpenStack VMs.
  43 To better illustrate the steps involved, we have captured the manual creation of such an environment using the ONAP Wind River Open Lab.
  44
  45 .. contents::
  46    :depth: 1
  47    :local:
  48 ..
  49
  50 Create Key Pair
  51 ===============
  52 A Key Pair is required to access the created OpenStack VMs and will be used by
  53 RKE to configure the VMs for Kubernetes.
  54
  55 Use an existing key pair, import one or create a new one to assign.
  56
  57 .. image:: images/keys/key_pair_1.png
  58
  59 .. Note::
  60   If you're creating a new Key Pair, ensure to create a local copy of the Private Key through the use of "Copy Private Key to Clipboard".
  61
  62 For the purpose of this guide, we will assume a new local key called "onap-key"
  63 has been downloaded and is copied into **~/.ssh/**, from which it can be referenced.
  64
  65 Example:
  66   $ mv onap-key ~/.ssh
  67
  68   $ chmod 600 ~/.ssh/onap-key
  69
  70
  71 Create Kubernetes Control Plane VMs
  72 ===================================
  73
  74 The following instructions describe how to create 3 OpenStack VMs to host the
  75 Highly-Available Kubernetes Control Plane.
  76 ONAP workloads will not be scheduled on these Control Plane nodes.
  77
  78 Launch new VM instances
  79 -----------------------
  80
  81 .. image:: images/cp_vms/control_plane_1.png
  82
  83 Select Ubuntu 18.04 as base image
  84 ---------------------------------
  85 Select "No" for "Create New Volume"
  86
  87 .. image:: images/cp_vms/control_plane_2.png
  88
  89 Select Flavor
  90 -------------
  91 The recommended flavor is at least 4 vCPU and 8GB ram.
  92
  93 .. image:: images/cp_vms/control_plane_3.png
  94
  95 Networking
  96 ----------
  97
  98 .. image:: images/cp_vms/control_plane_4.png
  99
 100 Security Groups
 101 ---------------
 102
 103 .. image:: images/cp_vms/control_plane_5.png
 104
 105 Key Pair
 106 --------
 107 Assign the key pair that was created/selected previously (e.g. onap_key).
 108
 109 .. image:: images/cp_vms/control_plane_6.png
 110
 111 Apply customization script for Control Plane VMs
 112 ------------------------------------------------
 113
 114 Click :download:`openstack-k8s-controlnode.sh <openstack-k8s-controlnode.sh>`
 115 to download the script.
 116
 117 .. literalinclude:: openstack-k8s-controlnode.sh
 118    :language: bash
 119
 120 This customization script will:
 121
 122 * update ubuntu
 123 * install docker
 124
 125 .. image:: images/cp_vms/control_plane_7.png
 126
 127 Launch Instance
 128 ---------------
 129
 130 .. image:: images/cp_vms/control_plane_8.png
 131
 132
 133
 134 Create Kubernetes Worker VMs
 135 ============================
 136 The following instructions describe how to create OpenStack VMs to host the
 137 Highly-Available Kubernetes Workers. ONAP workloads will only be scheduled on these nodes.
 138
 139 Launch new VM instances
 140 -----------------------
 141
 142 The number and size of Worker VMs is depenedent on the size of the ONAP deployment.
 143 By default, all ONAP applications are deployed. It's possible to customize the deployment
 144 and enable a subset of the ONAP applications. For the purpose of this guide, however,
 145 we will deploy 12 Kubernetes Workers that have been sized to handle the entire ONAP
 146 application workload.
 147
 148 .. image:: images/wk_vms/worker_1.png
 149
 150 Select Ubuntu 18.04 as base image
 151 ---------------------------------
 152 Select "No" on "Create New Volume"
 153
 154 .. image:: images/wk_vms/worker_2.png
 155
 156 Select Flavor
 157 -------------
 158 The size of Kubernetes hosts depend on the size of the ONAP deployment
 159 being installed.
 160
 161 If a small subset of ONAP applications are being deployed
 162 (i.e. for testing purposes), then 16GB or 32GB may be sufficient.
 163
 164 .. image:: images/wk_vms/worker_3.png
 165
 166 Networking
 167 -----------
 168
 169 .. image:: images/wk_vms/worker_4.png
 170
 171 Security Group
 172 ---------------
 173
 174 .. image:: images/wk_vms/worker_5.png
 175
 176 Key Pair
 177 --------
 178 Assign the key pair that was created/selected previously (e.g. onap_key).
 179
 180 .. image:: images/wk_vms/worker_6.png
 181
 182 Apply customization script for Kubernetes VM(s)
 183 -----------------------------------------------
 184
 185 Click :download:`openstack-k8s-workernode.sh <openstack-k8s-workernode.sh>` to download the
 186 script.
 187
 188 .. literalinclude:: openstack-k8s-workernode.sh
 189    :language: bash
 190
 191 This customization script will:
 192
 193 * update ubuntu
 194 * install docker
 195 * install nfs common
 196
 197
 198 Launch Instance
 199 ---------------
 200
 201 .. image:: images/wk_vms/worker_7.png
 202
 203
 204
 205
 206 Assign Floating IP addresses
 207 ----------------------------
 208 Assign Floating IPs to all Control Plane and Worker VMs.
 209 These addresses provide external access to the VMs and will be used by RKE
 210 to configure kubernetes on to the VMs.
 211
 212 Repeat the following for each VM previously created:
 213
 214 .. image:: images/floating_ips/floating_1.png
 215
 216 Resulting floating IP assignments in this example.
 217
 218 .. image:: images/floating_ips/floating_2.png
 219
 220
 221
 222
 223 Configure Rancher Kubernetes Engine (RKE)
 224 =========================================
 225
 226 Install RKE
 227 -----------
 228 Download and install RKE on a VM, desktop or laptop.
 229 Binaries can be found here for Linux and Mac: https://github.com/rancher/rke/releases/tag/v0.2.1
 230
 231 RKE requires a *cluster.yml* as input. An example file is show below that
 232 describes a Kubernetes cluster that will be mapped onto the OpenStack VMs
 233 created earlier in this guide.
 234
 235 Example: **cluster.yml**
 236
 237 .. image:: images/rke/rke_1.png
 238
 239 Click :download:`cluster.yml <cluster.yml>` to download the
 240 configuration file.
 241
 242 .. literalinclude:: cluster.yml
 243    :language: yaml
 244
 245 Prepare cluster.yml
 246 -------------------
 247 Before this configuration file can be used the external **address**
 248 and the **internal_address** must be mapped for each control and worker node
 249 in this file.
 250
 251 Run RKE
 252 -------
 253 From within the same directory as the cluster.yml file, simply execute:
 254
 255   $ rke up
 256
 257 The output will look something like:
 258
 259 .. code-block::
 260   INFO[0000] Initiating Kubernetes cluster
 261   INFO[0000] [certificates] Generating admin certificates and kubeconfig
 262   INFO[0000] Successfully Deployed state file at [./cluster.rkestate]
 263   INFO[0000] Building Kubernetes cluster
 264   INFO[0000] [dialer] Setup tunnel for host [10.12.6.82]
 265   INFO[0000] [dialer] Setup tunnel for host [10.12.6.249]
 266   INFO[0000] [dialer] Setup tunnel for host [10.12.6.74]
 267   INFO[0000] [dialer] Setup tunnel for host [10.12.6.85]
 268   INFO[0000] [dialer] Setup tunnel for host [10.12.6.238]
 269   INFO[0000] [dialer] Setup tunnel for host [10.12.6.89]
 270   INFO[0000] [dialer] Setup tunnel for host [10.12.5.11]
 271   INFO[0000] [dialer] Setup tunnel for host [10.12.6.90]
 272   INFO[0000] [dialer] Setup tunnel for host [10.12.6.244]
 273   INFO[0000] [dialer] Setup tunnel for host [10.12.5.165]
 274   INFO[0000] [dialer] Setup tunnel for host [10.12.6.126]
 275   INFO[0000] [dialer] Setup tunnel for host [10.12.6.111]
 276   INFO[0000] [dialer] Setup tunnel for host [10.12.5.160]
 277   INFO[0000] [dialer] Setup tunnel for host [10.12.5.191]
 278   INFO[0000] [dialer] Setup tunnel for host [10.12.6.195]
 279   INFO[0002] [network] Deploying port listener containers
 280   INFO[0002] [network] Pulling image [nexus3.onap.org:10001/rancher/rke-tools:v0.1.27] on host [10.12.6.85]
 281   INFO[0002] [network] Pulling image [nexus3.onap.org:10001/rancher/rke-tools:v0.1.27] on host [10.12.6.89]
 282   INFO[0002] [network] Pulling image [nexus3.onap.org:10001/rancher/rke-tools:v0.1.27] on host [10.12.6.90]
 283   INFO[0011] [network] Successfully pulled image [nexus3.onap.org:10001/rancher/rke-tools:v0.1.27] on host [10.12.6.89]
 284   . . . .
 285   INFO[0309] [addons] Setting up Metrics Server
 286   INFO[0309] [addons] Saving ConfigMap for addon rke-metrics-addon to Kubernetes
 287   INFO[0309] [addons] Successfully saved ConfigMap for addon rke-metrics-addon to Kubernetes
 288   INFO[0309] [addons] Executing deploy job rke-metrics-addon
 289   INFO[0315] [addons] Metrics Server deployed successfully
 290   INFO[0315] [ingress] Setting up nginx ingress controller
 291   INFO[0315] [addons] Saving ConfigMap for addon rke-ingress-controller to Kubernetes
 292   INFO[0316] [addons] Successfully saved ConfigMap for addon rke-ingress-controller to Kubernetes
 293   INFO[0316] [addons] Executing deploy job rke-ingress-controller
 294   INFO[0322] [ingress] ingress controller nginx deployed successfully
 295   INFO[0322] [addons] Setting up user addons
 296   INFO[0322] [addons] no user addons defined
 297   INFO[0322] Finished building Kubernetes cluster successfully
 298
 299 Install Kubectl
 300 ===============
 301
 302 Download and install kubectl. Binaries can be found here for Linux and Mac:
 303
 304 https://storage.googleapis.com/kubernetes-release/release/v1.13.5/bin/linux/amd64/kubectl
 305 https://storage.googleapis.com/kubernetes-release/release/v1.13.5/bin/darwin/amd64/kubectl
 306
 307 Validate deployment
 308 -------------------
 309   $ cp kube_config_cluster.yml ~/.kube/config.onap
 310
 311   $ export KUBECONFIG=~/.kube/config.onap
 312
 313   $ kubectl config use-context onap
 314
 315   $ kubectl get nodes -o=wide
 316
 317 .. code-block::
 318   NAME             STATUS   ROLES               AGE     VERSION   INTERNAL-IP   EXTERNAL-IP   OS-IMAGE           KERNEL-VERSION      CONTAINER-RUNTIME
 319   onap-control-1   Ready    controlplane,etcd   3h53m   v1.13.5   10.0.0.8      <none>        Ubuntu 18.04 LTS   4.15.0-22-generic   docker://18.9.5
 320   onap-control-2   Ready    controlplane,etcd   3h53m   v1.13.5   10.0.0.11     <none>        Ubuntu 18.04 LTS   4.15.0-22-generic   docker://18.9.5
 321   onap-control-3   Ready    controlplane,etcd   3h53m   v1.13.5   10.0.0.12     <none>        Ubuntu 18.04 LTS   4.15.0-22-generic   docker://18.9.5
 322   onap-k8s-1       Ready    worker              3h53m   v1.13.5   10.0.0.14     <none>        Ubuntu 18.04 LTS   4.15.0-22-generic   docker://18.9.5
 323   onap-k8s-10      Ready    worker              3h53m   v1.13.5   10.0.0.16     <none>        Ubuntu 18.04 LTS   4.15.0-22-generic   docker://18.9.5
 324   onap-k8s-11      Ready    worker              3h53m   v1.13.5   10.0.0.18     <none>        Ubuntu 18.04 LTS   4.15.0-22-generic   docker://18.9.5
 325   onap-k8s-12      Ready    worker              3h53m   v1.13.5   10.0.0.7      <none>        Ubuntu 18.04 LTS   4.15.0-22-generic   docker://18.9.5
 326   onap-k8s-2       Ready    worker              3h53m   v1.13.5   10.0.0.26     <none>        Ubuntu 18.04 LTS   4.15.0-22-generic   docker://18.9.5
 327   onap-k8s-3       Ready    worker              3h53m   v1.13.5   10.0.0.5      <none>        Ubuntu 18.04 LTS   4.15.0-22-generic   docker://18.9.5
 328   onap-k8s-4       Ready    worker              3h53m   v1.13.5   10.0.0.6      <none>        Ubuntu 18.04 LTS   4.15.0-22-generic   docker://18.9.5
 329   onap-k8s-5       Ready    worker              3h53m   v1.13.5   10.0.0.9      <none>        Ubuntu 18.04 LTS   4.15.0-22-generic   docker://18.9.5
 330   onap-k8s-6       Ready    worker              3h53m   v1.13.5   10.0.0.17     <none>        Ubuntu 18.04 LTS   4.15.0-22-generic   docker://18.9.5
 331   onap-k8s-7       Ready    worker              3h53m   v1.13.5   10.0.0.20     <none>        Ubuntu 18.04 LTS   4.15.0-22-generic   docker://18.9.5
 332   onap-k8s-8       Ready    worker              3h53m   v1.13.5   10.0.0.10     <none>        Ubuntu 18.04 LTS   4.15.0-22-generic   docker://18.9.5
 333   onap-k8s-9       Ready    worker              3h53m   v1.13.5   10.0.0.4      <none>        Ubuntu 18.04 LTS   4.15.0-22-generic   docker://18.9.5
 334
 335
 336 Install Helm
 337 ============
 338
 339   $ kubectl -n kube-system create serviceaccount tiller
 340
 341   $ kubectl create clusterrolebinding tiller --clusterrole=cluster-admin --serviceaccount=kube-system:tiller
 342
 343   $ helm init --service-account tiller
 344
 345   $ kubectl -n kube-system  rollout status deploy/tiller-deploy
 346
 347
 348
 349 Setting up an NFS share for Multinode Kubernetes Clusters
 350 =========================================================
 351 Deploying applications to a Kubernetes cluster requires Kubernetes nodes to
 352 share a common, distributed filesystem. In this tutorial, we will setup an
 353 NFS Master, and configure all Worker nodes a Kubernetes cluster to play
 354 the role of NFS slaves.
 355
 356 It is recommneded that a separate VM, outside of the kubernetes
 357 cluster, be used. This is to ensure that the NFS Master does not compete for
 358 resources with Kubernetes Control Plane or Worker Nodes.
 359
 360
 361 Launch new NFS Server VM instance
 362 ---------------------------------
 363 .. image:: images/nfs_server/nfs_server_1.png
 364
 365 Select Ubuntu 18.04 as base image
 366 ---------------------------------
 367 Select "No" on "Create New Volume"
 368
 369 .. image:: images/nfs_server/nfs_server_2.png
 370
 371 Select Flavor
 372 -------------
 373
 374 .. image:: images/nfs_server/nfs_server_3.png
 375
 376 Networking
 377 -----------
 378
 379 .. image:: images/nfs_server/nfs_server_4.png
 380
 381 Security Group
 382 ---------------
 383
 384 .. image:: images/nfs_server/nfs_server_5.png
 385
 386 Key Pair
 387 --------
 388 Assign the key pair that was created/selected previously (e.g. onap_key).
 389
 390 .. image:: images/nfs_server/nfs_server_6.png
 391
 392 Apply customization script for NFS Server VM
 393 --------------------------------------------
 394
 395 Click :download:`openstack-nfs-server.sh <openstack-nfs-server.sh>` to download the
 396 script.
 397
 398 .. literalinclude:: openstack-k8s-workernode.sh
 399    :language: bash
 400
 401 This customization script will:
 402
 403 * update ubuntu
 404 * install nfs server
 405
 406
 407 Launch Instance
 408 ---------------
 409
 410 .. image:: images/nfs_server/nfs_server_7.png
 411
 412
 413
 414 Assign Floating IP addresses
 415 ----------------------------
 416
 417 .. image:: images/nfs_server/nfs_server_8.png
 418
 419 Resulting floating IP assignments in this example.
 420
 421 .. image:: images/nfs_server/nfs_server_9.png
 422
 423
 424 To properly set up an NFS share on Master and Slave nodes, the user can run the
 425 scripts below.
 426
 427 Click :download:`master_nfs_node.sh <master_nfs_node.sh>` to download the
 428 script.
 429
 430 .. literalinclude:: master_nfs_node.sh
 431    :language: bash
 432
 433 Click :download:`slave_nfs_node.sh <slave_nfs_node.sh>` to download the script.
 434
 435 .. literalinclude:: slave_nfs_node.sh
 436    :language: bash
 437
 438 The master_nfs_node.sh script runs in the NFS Master node and needs the list of
 439 NFS Slave nodes as input, e.g.::
 440
 441     $ sudo ./master_nfs_node.sh node1_ip node2_ip ... nodeN_ip
 442
 443 The slave_nfs_node.sh script runs in each NFS Slave node and needs the IP of
 444 the NFS Master node as input, e.g.::
 445
 446     $ sudo ./slave_nfs_node.sh master_node_ip
 447
 448
 449 ONAP Deployment via OOM
 450 =======================
 451 Now that kubernetes and Helm are installed and configured you can prepare to
 452 deploy ONAP. Follow the instructions in the README.md_ or look at the official
 453 documentation to get started:
 454
 455 - :ref:`quick-start-label` - deploy ONAP on an existing cloud
 456 - :ref:`user-guide-label` - a guide for operators of an ONAP instance