README.rst

   1 ..
   2       Licensed under the Apache License, Version 2.0 (the "License"); you may
   3       not use this file except in compliance with the License. You may obtain
   4       a copy of the License at
   5
   6           http://www.apache.org/licenses/LICENSE-2.0
   7
   8       Unless required by applicable law or agreed to in writing, software
   9       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  10       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  11       License for the specific language governing permissions and limitations
  12       under the License.
  13
  14       Convention for heading levels in Integrated Edge Cloud documentation:
  15
  16       =======  Heading 0 (reserved for the title in a document)
  17       -------  Heading 1
  18       ~~~~~~~  Heading 2
  19       +++++++  Heading 3
  20       '''''''  Heading 4
  21
  22       Avoid deeper levels because they do not render well.
  23
  24
  25 =================================
  26 IEC Reference Foundation Overview
  27 =================================
  28
  29 This document provides a general description about the reference foundation of IEC.
  30 The Integrated Edge Cloud (IEC) will enable new functionalities and business models
  31 on the network edge. The benefits of running applications on the network edge are
  32 - Better latencies for end users
  33 - Less load on network since more data can be processed locally
  34 - Fully utilize the computation power of the edge devices
  35
  36 .. _Kubernetes: https://kubernetes.io/
  37 .. _Calico: https://www.projectcalico.org/
  38 .. _Contiv: https://github.com/contiv/vpp
  39 .. _OVN-kubernetes: https://github.com/openvswitch/ovn-kubernetes
  40
  41 Currently, the chosen operating system(OS) is Ubuntu 16.04 and/or 18.04.
  42 The infrastructure orchestration of IEC is based on Kubernetes_, which is a
  43 production-grade container orchestration with rich running eco-system.
  44 The current container networking mechanism (CNI) choosed for Kubernetes is project
  45 Calico, which is a high performance, scalable, policy enabled and widely used container
  46 networking solution with rather easy installation and arm64 support. In the future,
  47 Contiv/VPP or OVN-Kubernetes would also be candidates for Kubernetes networking.
  48
  49
  50 Kubernetes Install for Ubuntu
  51 -----------------------------
  52
  53 Install Docker as Prerequisite
  54 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  55
  56 .. _Docker: https://www.docker.com/
  57 .. _install: https://docs.docker.com/install/linux/docker-ce/ubuntu/
  58
  59 Docker_ is used for Kuberntes docker images management. The installation script for docker
  60 version 18.06 is given below. More docker install information can be found in the install_
  61 guide::
  62     DOCKER_VERSION=18.06.1
  63     ARCH=arm64
  64     curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
  65     sudo apt-key fingerprint 0EBFCD88
  66     sudo add-apt-repository \
  67      "deb [arch=${ARCH}] https://download.docker.com/linux/ubuntu \
  68      $(lsb_release -cs) \
  69      stable"
  70     sudo apt-get update
  71     sudo apt-get install -y docker-ce=${DOCKER_VERSION}~ce~3-0~ubuntu
  72
  73
  74 Disable swap on your machine
  75 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  76
  77 Turn off all swap devices and files with::
  78
  79    sudo swapoff -a
  80
  81 .. _kubeadm: https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/
  82
  83
  84 Install Kubernetes with Kubeadm
  85 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  86
  87 kubeadm_ helps you bootstrap a minimum viable Kubernetes cluster that conforms
  88 to best practices which a preferred installation method for IEC currently.
  89 Now we choose v1.13.0 as a current stable version of Kubernetes for arm64.
  90 Usually the current host(edge server/gateway)'s management interface is chosen as
  91 the Kubeapi-server advertise address which is indicated here as ``$MGMT_IP``.
  92
  93 The common installation steps for both Kubernetes master and slave node are given
  94 as Linux shell scripts::
  95
  96    sudo bash
  97    apt-get update && apt-get install -y apt-transport-https curl
  98    curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key add -
  99    cat <<EOF >/etc/apt/sources.list.d/kubernetes.list
 100    deb https://apt.kubernetes.io/ kubernetes-xenial main
 101    EOF
 102    apt-get update
 103    apt-get install -y kubelet=1.13.0-00 kubeadm=1.13.0-00 kubectl=1.13.0-00
 104    apt-mark hold kubelet kubeadm kubectl
 105    sysctl net.bridge.bridge-nf-call-iptables=1
 106
 107 For host setup as Kubernetes `master`::
 108
 109    sudo kubeadm config images pull
 110    sudo kubeadm init --pod-network-cidr=192.168.0.0/16 --apiserver-advertise-address=$MGMT_IP \
 111    --service-cidr=172.16.1.0/24
 112
 113 To start using your cluster, you need to run (as a regular user)::
 114
 115    mkdir -p $HOME/.kube
 116    sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
 117    sudo chown $(id -u):$(id -g) $HOME/.kube/config
 118
 119 or if you are the ``root`` user::
 120
 121    export KUBECONFIG=/etc/kubernetes/admin.conf
 122
 123 For hosts setup as Kubernetes `slave`::
 124
 125    kubeadm join --token <token> <master-ip>:6443 --discovery-token-ca-cert-hash sha256:<hash>
 126
 127 in which the token is given in the master's ``kubeadm init``.
 128
 129 or using following command which will skip ca-cert verification::
 130
 131    kubeadm join --token <token> <master_ip>:6443 --discovery-token-unsafe-skip-ca-verification
 132
 133 After the `slave` joining the Kubernetes cluster, in the master node, you could check the cluster
 134 node with the command::
 135    kubectl get nodes
 136
 137
 138 Install the Calico CNI Plugin to Kubernetes Cluster
 139 ---------------------------------------------------
 140
 141 Now we install a Calico_ network add-on so that Kubernetes pods can communicate with each other.
 142 The network must be deployed before any applications. Kubeadm only supports Container Networking
 143 Interface(CNI) based networks for which Calico has supported.
 144
 145 Install the Etcd Database
 146 ~~~~~~~~~~~~~~~~~~~~~~~~~
 147
 148 ::
 149
 150    kubectl apply -f https://raw.githubusercontent.com/Jingzhao123/arm64TemporaryCalico/temporay_arm64/
 151    v3.3/getting-started/kubernetes/installation/hosted/etcd-arm64.yaml
 152
 153 Install the RBAC Roles required for Calico
 154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 155
 156 ::
 157
 158    kubectl apply -f https://docs.projectcalico.org/v3.3/getting-started/kubernetes/installation/rbac.yaml
 159
 160 Install Calico to system
 161 ~~~~~~~~~~~~~~~~~~~~~~~~
 162
 163 Firstly, we should get the configuration file from web site and modify the corresponding image
 164 from amd64 to arm64 version. Then, by using kubectl, the calico pod will be created.
 165 ::
 166    wget https://docs.projectcalico.org/v3.3/getting-started/kubernetes/installation/hosted/calico.yaml
 167
 168 Since the "quay.io/calico" image repo does not support does not multi-arch, we have
 169 to replace the “quay.io/calico” image path to "calico" which supports multi-arch.
 170 ::
 171    sed -i "s/quay.io\/calico/calico/" calico.yaml
 172
 173 Deploy the Calico using following command::
 174
 175    kubectl apply -f calico.yaml
 176
 177 .. Attention::
 178
 179    In calico.yaml file, there is an option "IP_AUTODETECTION_METHOD" about choosing
 180    network interface. The default value is "first-found" which means the first valid
 181    IP address (except local interface, docker bridge). So if the number of network-interface
 182    is more than 1 on your server, you should configure it depends on your networking
 183    environments. If it does not configure it properly, there are some error about
 184    calico-node pod: "BGP not established with X.X.X.X".
 185
 186
 187 Remove the taints on master node
 188 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 189
 190 ::
 191
 192    kubectl taint nodes --all node-role.kubernetes.io/master-
 193
 194
 195 Verification for the Work of Kubernetes
 196 ---------------------------------------
 197
 198 Now we can verify the work of Kubernetes and Calico with Kubernets pod and service creation and accessing
 199 based on Nginx which is a widely used web server.
 200
 201 Firstly, create a file named nginx-app.yaml to describe a Pod and service by::
 202
 203   $ cat <<EOF >~/nginx-app.yaml
 204   apiVersion: v1
 205   kind: Service
 206   metadata:
 207     name: nginx
 208     labels:
 209       app: nginx
 210   spec:
 211     type: NodePort
 212     ports:
 213     - port: 80
 214       protocol: TCP
 215       name: http
 216     selector:
 217       app: nginx
 218   ---
 219   apiVersion: v1
 220   kind: ReplicationController
 221   metadata:
 222     name: nginx
 223   spec:
 224     replicas: 2
 225     template:
 226       metadata:
 227         labels:
 228           app: nginx
 229       spec:
 230         containers:
 231         - name: nginx
 232           image: nginx
 233           ports:
 234           - containerPort: 80
 235   EOF
 236
 237 then test the Kubernetes working status with the script::
 238
 239    set -ex
 240    kubectl create -f ~/nginx-app.yaml
 241    kubectl get nodes
 242    kubectl get services
 243    kubectl get pods
 244    kubectl get rc
 245    r="0"
 246    while [ $r -ne "2" ]
 247    do
 248       r=$(kubectl get pods | grep Running | wc -l)
 249       sleep 60
 250    done
 251    svcip=$(kubectl get services nginx  -o json | grep clusterIP | cut -f4 -d'"')
 252    sleep 10
 253    wget http://$svcip
 254    kubectl delete -f ./examples/nginx-app.yaml
 255    kubectl delete -f ./nginx-app.yaml
 256    kubectl get rc
 257    kubectl get pods
 258    kubectl get services
 259
 260 .. _Helm: https://github.com/helm/helm
 261
 262 Helm Install on Arm64
 263 ---------------------
 264
 265 Helm_ is a tool for managing Kubernetes charts. Charts are packages of pre-configured
 266 Kubernetes resources. The installation of Helm on arm64 is as followes::
 267
 268    wget https://storage.googleapis.com/kubernetes-helm/helm-v2.12.3-linux-arm64.tar.gz
 269    xvf helm-v2.12.3-linux-arm64.tar.gz
 270    sudo cp linux-arm64/helm /usr/bin
 271    sudo cp linux-arm64/tiller /usr/bin
 272
 273
 274 Further Information
 275 -------------------
 276
 277 We would like to provide a walk through shell script to automate the installation of Kubernetes
 278 and Calico in the future. But this README is still useful for IEC developers and users.
 279
 280 For issues or anything on the reference foundation stack of IEC, you could contact:
 281
 282 Trevor Tao: trevor.tao@arm.com
 283
 284 Jingzhao Ni: jingzhao.ni@arm.com
 285
 286 Jianlin Lv:  jianlin.lv@arm.com