From cda425bcdd513e94b46fb09ee7ec7bc973a52069 Mon Sep 17 00:00:00 2001 From: Mohammed Naser Date: Sun, 2 Aug 2020 12:52:40 -0400 Subject: [PATCH] Add initial deployment guide Change-Id: If86858123fa4dd18d9de01077065b458fe58efee --- doc/requirements.txt | 2 + doc/source/conf.py | 11 + doc/source/deployment-guide.rst | 19 + doc/source/deployment-guide/install-cni.rst | 31 + .../deployment-guide/install-docker.rst | 20 + .../deployment-guide/install-kubernetes.rst | 96 ++ .../deployment-guide/setup-load-balancer.rst | 49 + .../deployment-guide/setup-virtual-ip.rst | 37 + doc/source/index.rst | 1 + doc/source/manifests/calico.yaml | 842 ++++++++++++++++++ 10 files changed, 1108 insertions(+) create mode 100644 doc/source/deployment-guide.rst create mode 100644 doc/source/deployment-guide/install-cni.rst create mode 100644 doc/source/deployment-guide/install-docker.rst create mode 100644 doc/source/deployment-guide/install-kubernetes.rst create mode 100644 doc/source/deployment-guide/setup-load-balancer.rst create mode 100644 doc/source/deployment-guide/setup-virtual-ip.rst create mode 100644 doc/source/manifests/calico.yaml diff --git a/doc/requirements.txt b/doc/requirements.txt index af0b462e..25808345 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,2 +1,4 @@ doc8 sphinx +sphinx-copybutton +sphinx-tabs diff --git a/doc/source/conf.py b/doc/source/conf.py index b29762e2..8e3b6071 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,3 +1,14 @@ project = 'OpenStack Operator' copyright = '2020, VEXXHOST, Inc.' author = 'VEXXHOST, Inc.' + +html_extra_path = [ + 'manifests/calico.yaml', +] + +extensions = [ + 'sphinx_copybutton', + 'sphinx_tabs.tabs' +] + +copybutton_prompt_text = "$ " diff --git a/doc/source/deployment-guide.rst b/doc/source/deployment-guide.rst new file mode 100644 index 00000000..1a8e7440 --- /dev/null +++ b/doc/source/deployment-guide.rst @@ -0,0 +1,19 @@ +Deployment Guide +================ + +The OpenStack operator requires that you have a functional Kuberentes cluster +in order to be able to deploy it. The following steps out-line the +installation of a cluster and the operator. + +The deployment of the OpenStack operator is highly containerised, even for the +components not managed by the operator. The steps to get started involve +deploying Docker for running the underlying infrastructure, installing a +load balancer to access the Kubernetes API, deploying Kubernetes itself and +then the operator which should start the OpenStack deployment. + +.. highlight:: console +.. include:: deployment-guide/install-docker.rst +.. include:: deployment-guide/setup-virtual-ip.rst +.. include:: deployment-guide/setup-load-balancer.rst +.. include:: deployment-guide/install-kubernetes.rst +.. include:: deployment-guide/install-cni.rst diff --git a/doc/source/deployment-guide/install-cni.rst b/doc/source/deployment-guide/install-cni.rst new file mode 100644 index 00000000..0afc41e7 --- /dev/null +++ b/doc/source/deployment-guide/install-cni.rst @@ -0,0 +1,31 @@ +Install CNI +----------- +The tested and supported CNI for the OpenStack operator is Calico due to it's +high performance and support for ``NetworkPolicy``. You can deploy it onto +the cluster by running the following:: + + $ iptables -I DOCKER-USER -j ACCEPT + $ kubectl apply -f https://docs.opendev.org/vexxhost/openstack-operator/calico.yaml + +.. note:: + + The first command overrides Docker's behaviour of disabling all traffic + routing if it is enabled, as this is necessary for the functioning on the + Kubernetes cluster. + +Once the CNI is deployed, you'll have to make sure that Calico detected the +correct interface to build your BGP mesh, you can run this command and make +sure that all systems are on the right network:: + + $ kubectl describe nodes | grep IPv4Address + +If they are not on the right IP range or interface, you can run the following +command and edit the ``calico-node`` DaemonSet:: + + $ kubectl -n kube-system edit ds/calico-node + +You'll need to add an environment variable to the container definition which +skips the interfaces you don't want, something similar to this:: + + - name: IP_AUTODETECTION_METHOD + value: skip-interface=bond0 diff --git a/doc/source/deployment-guide/install-docker.rst b/doc/source/deployment-guide/install-docker.rst new file mode 100644 index 00000000..5f140187 --- /dev/null +++ b/doc/source/deployment-guide/install-docker.rst @@ -0,0 +1,20 @@ +Install Docker +-------------- +Docker is used by many different components of the underlying infrastructure, +so it must be installed before anything to bootstrap the system. + +It must be installed on all the machines that you intend to manage using the +OpenStack operator. It will also be used to deploy infrastructure components +such as the virtual IP and Ceph. + +.. tabs:: + + .. code-tab:: console Debian + + $ apt-get install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common + $ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add - + $ sudo add-apt-repository "deb https://download.docker.com/linux/debian $(lsb_release -cs) stable" + $ apt-get update + $ apt-get install -y docker-ce + $ apt-mark hold docker-ce + diff --git a/doc/source/deployment-guide/install-kubernetes.rst b/doc/source/deployment-guide/install-kubernetes.rst new file mode 100644 index 00000000..20fcf6ef --- /dev/null +++ b/doc/source/deployment-guide/install-kubernetes.rst @@ -0,0 +1,96 @@ +Install Kubernetes +------------------ +The recommended container runtime for the operator is ``containerd``, it is +also what is used in production. This document outlines the installation of +Kubernetes using ``kubeadm``. You'll need to start by installing the +Kubernetes components on all of the systems. + +.. tabs:: + + .. code-tab:: console Debian + + $ curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add - + $ sudo add-apt-repository "deb https://apt.kubernetes.io/ kubernetes-xenial main" + $ apt-get update + $ apt-get install -y kubelet kubeadm kubectl + $ apt-mark hold containerd.io kubelet kubeadm kubectl + $ containerd config default > /etc/containerd/config.toml + $ systemctl restart containerd + +Once this is done, you'll need to start off by preparing the configuration file +for ``kubeadm``, which should look somethig like this:: + + $ cat < 18s v1.18.6 + kvm2 NotReady 10s v1.18.6 + kvm3 NotReady 2s v1.18.6 diff --git a/doc/source/deployment-guide/setup-load-balancer.rst b/doc/source/deployment-guide/setup-load-balancer.rst new file mode 100644 index 00000000..05346186 --- /dev/null +++ b/doc/source/deployment-guide/setup-load-balancer.rst @@ -0,0 +1,49 @@ +Setup Load Balancer +------------------- +The load balancer which will be distributing requests across all of the +Kubernetes API servers will be HAproxy. + +.. note:: + + We do not suggest using HAproxy to distribute load across all of the + ingress controllers. The primary reason being that it introduces an extra + hop in the network for no large benefit. The ingress should be bound + directly on the virtual IP. + +The following example assumes that you have 3 controllers, with their IP +addresses being ``10.0.0.1``, ``10.0.0.2``, ``10.0.0.3``. It also assumes that +all of the Kubernetes API servers will be listening on port ``16443`` and it +will be listening on port ``6443``. + +You'll have to create a configuration file on the local system first:: + + $ mkdir /etc/haproxy + $ cat <