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 .. contents::
  27    :depth: 1
  28    :local:
  29 ..
  30
  31 The result at the end of this tutorial will be:
  32
  33 #. Creation of a Key Pair to use with Open Stack and RKE
  34
  35 #. Creation of OpenStack VMs to host Kubernetes Control Plane
  36
  37 #. Creation of OpenStack VMs to host Kubernetes Workers
  38
  39 #. Installation and configuration of RKE to setup an HA Kubernetes
  40
  41 #. Installation and configuration of kubectl
  42
  43 #. Installation and configuration of helm
  44
  45 #. Creation of an NFS Server to be used by ONAP as shared persistance
  46
  47 There are many ways one can execute the above steps. Including automation through the use of HEAT to setup the OpenStack VMs.
  48 To better illustrate the steps involved, we have captured the manual creation of such an environment using the ONAP Wind River Open Lab.
  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
  67   > mv onap-key ~/.ssh
  68
  69   > chmod 600 ~/.ssh/onap-key
  70
  71
  72 Create Kubernetes Control Plane VMs
  73 ===================================
  74
  75 The following instructions describe how to create 3 OpenStack VMs to host the
  76 Highly-Available Kubernetes Control Plane.
  77 ONAP workloads will not be scheduled on these Control Plane nodes.
  78
  79 Launch new VM instances
  80 -----------------------
  81
  82 .. image:: images/cp_vms/control_plane_1.png
  83
  84 Select Ubuntu 18.04 as base image
  85 ---------------------------------
  86 Select "No" for "Create New Volume"
  87
  88 .. image:: images/cp_vms/control_plane_2.png
  89
  90 Select Flavor
  91 -------------
  92 The recommended flavor is at least 4 vCPU and 8GB ram.
  93
  94 .. image:: images/cp_vms/control_plane_3.png
  95
  96 Networking
  97 ----------
  98
  99 .. image:: images/cp_vms/control_plane_4.png
 100
 101 Security Groups
 102 ---------------
 103
 104 .. image:: images/cp_vms/control_plane_5.png
 105
 106 Key Pair
 107 --------
 108 Assign the key pair that was created/selected previously (e.g. onap_key).
 109
 110 .. image:: images/cp_vms/control_plane_6.png
 111
 112 Apply customization script for Control Plane VMs
 113 ------------------------------------------------
 114
 115 Click :download:`openstack-k8s-controlnode.sh <openstack-k8s-controlnode.sh>`
 116 to download the script.
 117
 118 .. literalinclude:: openstack-k8s-controlnode.sh
 119    :language: bash
 120
 121 This customization script will:
 122
 123 * update ubuntu
 124 * install docker
 125
 126 .. image:: images/cp_vms/control_plane_7.png
 127
 128 Launch Instance
 129 ---------------
 130
 131 .. image:: images/cp_vms/control_plane_8.png
 132
 133
 134
 135 Create Kubernetes Worker VMs
 136 ============================
 137 The following instructions describe how to create OpenStack VMs to host the
 138 Highly-Available Kubernetes Workers. ONAP workloads will only be scheduled on these nodes.
 139
 140 Launch new VM instances
 141 -----------------------
 142
 143 The number and size of Worker VMs is depenedent on the size of the ONAP deployment.
 144 By default, all ONAP applications are deployed. It's possible to customize the deployment
 145 and enable a subset of the ONAP applications. For the purpose of this guide, however,
 146 we will deploy 12 Kubernetes Workers that have been sized to handle the entire ONAP
 147 application workload.
 148
 149 .. image:: images/wk_vms/worker_1.png
 150
 151 Select Ubuntu 18.04 as base image
 152 ---------------------------------
 153 Select "No" on "Create New Volume"
 154
 155 .. image:: images/wk_vms/worker_2.png
 156
 157 Select Flavor
 158 -------------
 159 The size of Kubernetes hosts depend on the size of the ONAP deployment
 160 being installed.
 161
 162 If a small subset of ONAP applications are being deployed
 163 (i.e. for testing purposes), then 16GB or 32GB may be sufficient.
 164
 165 .. image:: images/wk_vms/worker_3.png
 166
 167 Networking
 168 -----------
 169
 170 .. image:: images/wk_vms/worker_4.png
 171
 172 Security Group
 173 ---------------
 174
 175 .. image:: images/wk_vms/worker_5.png
 176
 177 Key Pair
 178 --------
 179 Assign the key pair that was created/selected previously (e.g. onap_key).
 180
 181 .. image:: images/wk_vms/worker_6.png
 182
 183 Apply customization script for Kubernetes VM(s)
 184 -----------------------------------------------
 185
 186 Click :download:`openstack-k8s-workernode.sh <openstack-k8s-workernode.sh>` to download the
 187 script.
 188
 189 .. literalinclude:: openstack-k8s-workernode.sh
 190    :language: bash
 191
 192 This customization script will:
 193
 194 * update ubuntu
 195 * install docker
 196 * install nfs common
 197
 198
 199 Launch Instance
 200 ---------------
 201
 202 .. image:: images/wk_vms/worker_7.png
 203
 204
 205
 206
 207 Assign Floating IP addresses
 208 ----------------------------
 209 Assign Floating IPs to all Control Plane and Worker VMs.
 210 These addresses provide external access to the VMs and will be used by RKE
 211 to configure kubernetes on to the VMs.
 212
 213 Repeat the following for each VM previously created:
 214
 215 .. image:: images/floating_ips/floating_1.png
 216
 217 Resulting floating IP assignments in this example.
 218
 219 .. image:: images/floating_ips/floating_2.png
 220
 221
 222
 223
 224 Configure Rancher Kubernetes Engine (RKE)
 225 =========================================
 226
 227 Install RKE
 228 -----------
 229 Download and install RKE on a VM, desktop or laptop.
 230 Binaries can be found here for Linux and Mac: https://github.com/rancher/rke/releases/tag/v0.2.1
 231
 232 RKE requires a *cluster.yml* as input. An example file is show below that
 233 describes a Kubernetes cluster that will be mapped onto the OpenStack VMs
 234 created earlier in this guide.
 235
 236 Example: **cluster.yml**
 237
 238 .. image:: images/rke/rke_1.png
 239
 240 Click :download:`cluster.yml <cluster.yml>` to download the
 241 configuration file.
 242
 243 .. literalinclude:: cluster.yml
 244    :language: yaml
 245
 246 Prepare cluster.yml
 247 -------------------
 248 Before this configuration file can be used the external **address**
 249 and the **internal_address** must be mapped for each control and worker node
 250 in this file.
 251
 252 Run RKE
 253 -------
 254 From within the same directory as the cluster.yml file, simply execute::
 255
 256   > rke up
 257
 258 The output will look something like::
 259
 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
 310 ::
 311
 312   > cp kube_config_cluster.yml ~/.kube/config.onap
 313
 314   > export KUBECONFIG=~/.kube/config.onap
 315
 316   > kubectl config use-context onap
 317
 318   > kubectl get nodes -o=wide
 319
 320 ::
 321
 322   NAME             STATUS   ROLES               AGE     VERSION   INTERNAL-IP   EXTERNAL-IP   OS-IMAGE           KERNEL-VERSION      CONTAINER-RUNTIME
 323   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
 324   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
 325   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
 326   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
 327   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
 328   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
 329   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
 330   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
 331   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
 332   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
 333   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
 334   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
 335   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
 336   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
 337   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
 338
 339
 340 Install Helm
 341 ============
 342
 343 Example Helm client install on Linux::
 344
 345   > wget http://storage.googleapis.com/kubernetes-helm/helm-v2.12.3-linux-amd64.tar.gz
 346
 347   > tar -zxvf helm-v2.12.3-linux-amd64.tar.gz
 348
 349   > sudo mv linux-amd64/helm /usr/local/bin/helm
 350
 351 Initialize Kubernetes Cluster for use by Helm
 352 ---------------------------------------------
 353
 354 ::
 355
 356   > kubectl -n kube-system create serviceaccount tiller
 357
 358   > kubectl create clusterrolebinding tiller --clusterrole=cluster-admin --serviceaccount=kube-system:tiller
 359
 360   > helm init --service-account tiller
 361
 362   > kubectl -n kube-system  rollout status deploy/tiller-deploy
 363
 364
 365
 366 Setting up an NFS share for Multinode Kubernetes Clusters
 367 =========================================================
 368 Deploying applications to a Kubernetes cluster requires Kubernetes nodes to
 369 share a common, distributed filesystem. In this tutorial, we will setup an
 370 NFS Master, and configure all Worker nodes a Kubernetes cluster to play
 371 the role of NFS slaves.
 372
 373 It is recommneded that a separate VM, outside of the kubernetes
 374 cluster, be used. This is to ensure that the NFS Master does not compete for
 375 resources with Kubernetes Control Plane or Worker Nodes.
 376
 377
 378 Launch new NFS Server VM instance
 379 ---------------------------------
 380 .. image:: images/nfs_server/nfs_server_1.png
 381
 382 Select Ubuntu 18.04 as base image
 383 ---------------------------------
 384 Select "No" on "Create New Volume"
 385
 386 .. image:: images/nfs_server/nfs_server_2.png
 387
 388 Select Flavor
 389 -------------
 390
 391 .. image:: images/nfs_server/nfs_server_3.png
 392
 393 Networking
 394 -----------
 395
 396 .. image:: images/nfs_server/nfs_server_4.png
 397
 398 Security Group
 399 ---------------
 400
 401 .. image:: images/nfs_server/nfs_server_5.png
 402
 403 Key Pair
 404 --------
 405 Assign the key pair that was created/selected previously (e.g. onap_key).
 406
 407 .. image:: images/nfs_server/nfs_server_6.png
 408
 409 Apply customization script for NFS Server VM
 410 --------------------------------------------
 411
 412 Click :download:`openstack-nfs-server.sh <openstack-nfs-server.sh>` to download the
 413 script.
 414
 415 .. literalinclude:: openstack-k8s-workernode.sh
 416    :language: bash
 417
 418 This customization script will:
 419
 420 * update ubuntu
 421 * install nfs server
 422
 423
 424 Launch Instance
 425 ---------------
 426
 427 .. image:: images/nfs_server/nfs_server_7.png
 428
 429
 430
 431 Assign Floating IP addresses
 432 ----------------------------
 433
 434 .. image:: images/nfs_server/nfs_server_8.png
 435
 436 Resulting floating IP assignments in this example.
 437
 438 .. image:: images/nfs_server/nfs_server_9.png
 439
 440
 441 To properly set up an NFS share on Master and Slave nodes, the user can run the
 442 scripts below.
 443
 444 Click :download:`master_nfs_node.sh <master_nfs_node.sh>` to download the
 445 script.
 446
 447 .. literalinclude:: master_nfs_node.sh
 448    :language: bash
 449
 450 Click :download:`slave_nfs_node.sh <slave_nfs_node.sh>` to download the script.
 451
 452 .. literalinclude:: slave_nfs_node.sh
 453    :language: bash
 454
 455 The master_nfs_node.sh script runs in the NFS Master node and needs the list of
 456 NFS Slave nodes as input, e.g.::
 457
 458     > sudo ./master_nfs_node.sh node1_ip node2_ip ... nodeN_ip
 459
 460 The slave_nfs_node.sh script runs in each NFS Slave node and needs the IP of
 461 the NFS Master node as input, e.g.::
 462
 463     > sudo ./slave_nfs_node.sh master_node_ip
 464
 465
 466 ONAP Deployment via OOM
 467 =======================
 468 Now that kubernetes and Helm are installed and configured you can prepare to
 469 deploy ONAP. Follow the instructions in the README.md_ or look at the official
 470 documentation to get started:
 471
 472 - :ref:`quick-start-label` - deploy ONAP on an existing cloud
 473 - :ref:`user-guide-label` - a guide for operators of an ONAP instance