docs/oom_setup_kubernetes_rancher.rst

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