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 *1.* Creation of a Key Pair to use with Open Stack and RKE
  34
  35 *2.* Creation of OpenStack VMs to host Kubernetes Control Plane
  36
  37 *3.* Creation of OpenStack VMs to host Kubernetes Workers
  38
  39 *4.* Installation and configuration of RKE to setup an HA Kubernetes
  40
  41 *5.* Installation and configuration of kubectl
  42
  43 *5.* Installation and configuration of helm
  44
  45 *7.* 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   > 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
 261   INFO[0000] Initiating Kubernetes cluster
 262   INFO[0000] [certificates] Generating admin certificates and kubeconfig
 263   INFO[0000] Successfully Deployed state file at [./cluster.rkestate]
 264   INFO[0000] Building Kubernetes cluster
 265   INFO[0000] [dialer] Setup tunnel for host [10.12.6.82]
 266   INFO[0000] [dialer] Setup tunnel for host [10.12.6.249]
 267   INFO[0000] [dialer] Setup tunnel for host [10.12.6.74]
 268   INFO[0000] [dialer] Setup tunnel for host [10.12.6.85]
 269   INFO[0000] [dialer] Setup tunnel for host [10.12.6.238]
 270   INFO[0000] [dialer] Setup tunnel for host [10.12.6.89]
 271   INFO[0000] [dialer] Setup tunnel for host [10.12.5.11]
 272   INFO[0000] [dialer] Setup tunnel for host [10.12.6.90]
 273   INFO[0000] [dialer] Setup tunnel for host [10.12.6.244]
 274   INFO[0000] [dialer] Setup tunnel for host [10.12.5.165]
 275   INFO[0000] [dialer] Setup tunnel for host [10.12.6.126]
 276   INFO[0000] [dialer] Setup tunnel for host [10.12.6.111]
 277   INFO[0000] [dialer] Setup tunnel for host [10.12.5.160]
 278   INFO[0000] [dialer] Setup tunnel for host [10.12.5.191]
 279   INFO[0000] [dialer] Setup tunnel for host [10.12.6.195]
 280   INFO[0002] [network] Deploying port listener containers
 281   INFO[0002] [network] Pulling image [nexus3.onap.org:10001/rancher/rke-tools:v0.1.27] on host [10.12.6.85]
 282   INFO[0002] [network] Pulling image [nexus3.onap.org:10001/rancher/rke-tools:v0.1.27] on host [10.12.6.89]
 283   INFO[0002] [network] Pulling image [nexus3.onap.org:10001/rancher/rke-tools:v0.1.27] on host [10.12.6.90]
 284   INFO[0011] [network] Successfully pulled image [nexus3.onap.org:10001/rancher/rke-tools:v0.1.27] on host [10.12.6.89]
 285   . . . .
 286   INFO[0309] [addons] Setting up Metrics Server
 287   INFO[0309] [addons] Saving ConfigMap for addon rke-metrics-addon to Kubernetes
 288   INFO[0309] [addons] Successfully saved ConfigMap for addon rke-metrics-addon to Kubernetes
 289   INFO[0309] [addons] Executing deploy job rke-metrics-addon
 290   INFO[0315] [addons] Metrics Server deployed successfully
 291   INFO[0315] [ingress] Setting up nginx ingress controller
 292   INFO[0315] [addons] Saving ConfigMap for addon rke-ingress-controller to Kubernetes
 293   INFO[0316] [addons] Successfully saved ConfigMap for addon rke-ingress-controller to Kubernetes
 294   INFO[0316] [addons] Executing deploy job rke-ingress-controller
 295   INFO[0322] [ingress] ingress controller nginx deployed successfully
 296   INFO[0322] [addons] Setting up user addons
 297   INFO[0322] [addons] no user addons defined
 298   INFO[0322] Finished building Kubernetes cluster successfully
 299
 300 Install Kubectl
 301 ===============
 302
 303 Download and install kubectl. Binaries can be found here for Linux and Mac:
 304
 305 https://storage.googleapis.com/kubernetes-release/release/v1.13.5/bin/linux/amd64/kubectl
 306 https://storage.googleapis.com/kubernetes-release/release/v1.13.5/bin/darwin/amd64/kubectl
 307
 308 Validate deployment
 309 -------------------
 310   > cp kube_config_cluster.yml ~/.kube/config.onap
 311
 312   > export KUBECONFIG=~/.kube/config.onap
 313
 314   > kubectl config use-context onap
 315
 316   > kubectl get nodes -o=wide
 317
 318 .. code-block::
 319
 320   NAME             STATUS   ROLES               AGE     VERSION   INTERNAL-IP   EXTERNAL-IP   OS-IMAGE           KERNEL-VERSION      CONTAINER-RUNTIME
 321   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
 322   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
 323   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
 324   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
 325   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
 326   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
 327   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
 328   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
 329   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
 330   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
 331   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
 332   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
 333   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
 334   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
 335   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
 336
 337
 338 Install Helm
 339 ============
 340
 341 Example Helm client install on Linux:
 342   > wget http://storage.googleapis.com/kubernetes-helm/helm-v2.12.3-linux-amd64.tar.gz
 343
 344   > tar -zxvf helm-v2.12.3-linux-amd64.tar.gz
 345
 346   > sudo mv linux-amd64/helm /usr/local/bin/helm
 347
 348 Initialize Kubernetes Cluster for use by Helm
 349 ---------------------------------------------
 350   > kubectl -n kube-system create serviceaccount tiller
 351
 352   > kubectl create clusterrolebinding tiller --clusterrole=cluster-admin --serviceaccount=kube-system:tiller
 353
 354   > helm init --service-account tiller
 355
 356   > kubectl -n kube-system  rollout status deploy/tiller-deploy
 357
 358
 359
 360 Setting up an NFS share for Multinode Kubernetes Clusters
 361 =========================================================
 362 Deploying applications to a Kubernetes cluster requires Kubernetes nodes to
 363 share a common, distributed filesystem. In this tutorial, we will setup an
 364 NFS Master, and configure all Worker nodes a Kubernetes cluster to play
 365 the role of NFS slaves.
 366
 367 It is recommneded that a separate VM, outside of the kubernetes
 368 cluster, be used. This is to ensure that the NFS Master does not compete for
 369 resources with Kubernetes Control Plane or Worker Nodes.
 370
 371
 372 Launch new NFS Server VM instance
 373 ---------------------------------
 374 .. image:: images/nfs_server/nfs_server_1.png
 375
 376 Select Ubuntu 18.04 as base image
 377 ---------------------------------
 378 Select "No" on "Create New Volume"
 379
 380 .. image:: images/nfs_server/nfs_server_2.png
 381
 382 Select Flavor
 383 -------------
 384
 385 .. image:: images/nfs_server/nfs_server_3.png
 386
 387 Networking
 388 -----------
 389
 390 .. image:: images/nfs_server/nfs_server_4.png
 391
 392 Security Group
 393 ---------------
 394
 395 .. image:: images/nfs_server/nfs_server_5.png
 396
 397 Key Pair
 398 --------
 399 Assign the key pair that was created/selected previously (e.g. onap_key).
 400
 401 .. image:: images/nfs_server/nfs_server_6.png
 402
 403 Apply customization script for NFS Server VM
 404 --------------------------------------------
 405
 406 Click :download:`openstack-nfs-server.sh <openstack-nfs-server.sh>` to download the
 407 script.
 408
 409 .. literalinclude:: openstack-k8s-workernode.sh
 410    :language: bash
 411
 412 This customization script will:
 413
 414 * update ubuntu
 415 * install nfs server
 416
 417
 418 Launch Instance
 419 ---------------
 420
 421 .. image:: images/nfs_server/nfs_server_7.png
 422
 423
 424
 425 Assign Floating IP addresses
 426 ----------------------------
 427
 428 .. image:: images/nfs_server/nfs_server_8.png
 429
 430 Resulting floating IP assignments in this example.
 431
 432 .. image:: images/nfs_server/nfs_server_9.png
 433
 434
 435 To properly set up an NFS share on Master and Slave nodes, the user can run the
 436 scripts below.
 437
 438 Click :download:`master_nfs_node.sh <master_nfs_node.sh>` to download the
 439 script.
 440
 441 .. literalinclude:: master_nfs_node.sh
 442    :language: bash
 443
 444 Click :download:`slave_nfs_node.sh <slave_nfs_node.sh>` to download the script.
 445
 446 .. literalinclude:: slave_nfs_node.sh
 447    :language: bash
 448
 449 The master_nfs_node.sh script runs in the NFS Master node and needs the list of
 450 NFS Slave nodes as input, e.g.::
 451
 452     > sudo ./master_nfs_node.sh node1_ip node2_ip ... nodeN_ip
 453
 454 The slave_nfs_node.sh script runs in each NFS Slave node and needs the IP of
 455 the NFS Master node as input, e.g.::
 456
 457     > sudo ./slave_nfs_node.sh master_node_ip
 458
 459
 460 ONAP Deployment via OOM
 461 =======================
 462 Now that kubernetes and Helm are installed and configured you can prepare to
 463 deploy ONAP. Follow the instructions in the README.md_ or look at the official
 464 documentation to get started:
 465
 466 - :ref:`quick-start-label` - deploy ONAP on an existing cloud
 467 - :ref:`user-guide-label` - a guide for operators of an ONAP instance