src/foundation/hot/README

   1 Foreword:
   2 ---------
   3 This is a set of Openstack Heat templates which creates a simple topology of
   4 virtual machines to be used to deploy Kubernetes and Calico.
   5
   6 It consists of one master VM and 2 optional slave VMs. In the future it might
   7 be possible to configure the number of slaves but for now it is fixed.
   8
   9
  10 Prerequisites:
  11 --------------
  12 In order to run these templates, you need an Openstack deployment (at least
  13 Ocata version, later is preferred), either a single node installation or
  14 multinode).
  15
  16 The job of the Heat stacks is to spawn either 1 or 3 VMs which will form a
  17 Kubernetes cluster. The base image is required to exist, by default the stacks
  18 will expect a Glance image named "xenial" to exist.
  19
  20 It is required to upload an image prior to using the templates. Currently the
  21 templates operate on the assumption that an Ubuntu Xenial cloud image will be
  22 used, as such it installs the required packages using apt.
  23
  24 See the main control.sh script to start/stop the set of stacks and various
  25 run-time options, like DPDK support.
  26
  27
  28 Usage:
  29 ------
  30 For a DPDK enabled deployment, it is usually necessary to pass an extra metadata
  31 in the flavor (e.g. hw:mem_page_size=large). For DPDK usecase you also have to
  32 create a host aggregate which has the pinned=true metadata and add the desired
  33 compute nodes to this host aggregate.
  34
  35 For floating IP support, you need to specify the name of the external network,
  36 otherwise the script will use the default "external".
  37
  38 Example of running the script on a DPDK deployment:
  39   has_dpdk=true external_net=ext_net ./control.sh start
  40
  41 The set of templates currently define three stacks, which can be skipped from
  42 starting or stopping, if so desired. This makes it useful to skip deleting
  43 the nets or for starting the setup using one host only (master). E.g:
  44   skip_k8s_net=1 ./control.sh stop
  45   skip_k8s_slaves=1 ./control.sh start
  46
  47 Networking:
  48 -----------
  49 Have a look at k8s_net.yaml for the network configurations.
  50
  51 Currently the Heat templates define 2 networks:
  52 - k8s_mgmt_net: this is primarily used for sshing into the node, but it also
  53   serves as the access to the external network. Thus the floating IPs (which are
  54   activated by default) will be assigned to the ports from this network
  55 - k8s_int_net: kubernetes internal network, which is used by the nodes to join
  56   the cluster.
  57
  58 Separating the traffic into two networks makes sense in an Openstack environment
  59 by hiding the internal traffic from the outside world.
  60 Thus, for accessing the services inside the clusters, it will be required to use
  61 the floating IPs assigned to the Kubernetes servers.
  62
  63 In terms of CNI, there will be two additional networks involved, which are
  64 defined in k8s_net.yaml. These networks are not visible from outside of the Heat
  65 stacks, Kubernetes and Calico will encapsulate packets on these networks using
  66 IP-in-IP. In fact, to Openstack these are virtual networks, the only reason to
  67 have them in k8s_pod_net.yaml is to have a central view of all the network
  68 parameters.
  69 The two networks are described by Heat stack output variables, as follows:
  70 - k8s_pod_net_cidr: the POD network, passed to kubeadm init --pod-network-cidr
  71 - k8s_svc_net_cidr: the service network, passed to kubeadm init --service-cidr
  72
  73
  74 Calico networking:
  75 ------------------
  76 In terms of Calico, k8s_net.yaml defines yet another stack output variable:
  77 - k8s_cluster_ip: corresponds to the etcd_endpoints parameter in calico.yaml
  78
  79
  80 Network security:
  81 -----------------
  82 For the moment, for ease of operation, the stacks ports will have port security
  83 disabled. It should be possible to enable it, and provide a set of security
  84 groups rule to allow all TCP and UDP traffic for the internal network.
  85
  86
  87 Cluster setup:
  88 --------------
  89 The clusters configures itself automatically and installs the base IEC platform
  90 together with the needed resources for Helm. SEBA or other applications will
  91 have to be installed manually afterwards.
  92
  93 For the K8s cluster setup, the Master VM will print the join command in a file
  94 in /home/ubuntu/joincmd. Then the slave VMs will connect to the Master VM using
  95 ssh and read the joincmd file.
  96
  97 All of these are achieved by using cloud-init scripts that run at startup. You
  98 can follow the progress of the init scripts by looking at the console log, which
  99 right now are very verbose.
 100 After the setup is completed, you can look for the joincmd string in the output.
 101
 102
 103 Using the cluster:
 104 ------------------
 105 Once the setup is complete, you can login to the k8s_master VM. Use the Horizon
 106 interface or ssh into the floating ip, using the default credentials:
 107 ubuntu:ubuntu
 108
 109 A public key is also generated, and a private key saved in a file called
 110 ak-key.pem but for now password logins are permitted for ease of operation.
 111
 112 Once logged into the master VM, you need to become root.
 113   sudo su -
 114
 115 From here it is possible to run the usual kubernetes and helm tools, thanks to
 116 having the KUBECONFIG env variable exported through /root/.profile.
 117
 118 It is also possible to use kubernetes as non-root, in which case you need to
 119 manually create ~/.kube/ and copy the kubernetes config:
 120   mkdir -p $HOME/.kube
 121   sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
 122   sudo chown $(id -u):$(id -g) $HOME/.kube/config
 123
 124 The most basic operation you can run is verifying the nodes in the cluster:
 125   kubectl get nodes
 126   kubcetl describe node k8s-master