Installing a Cluster - Octelium Docs

In this guide, we are going to install an Octelium Cluster on top of an already running Kubernetes cluster via the octops init command for production and scalable deployments. It is highly recommended for you to read the pre-installation considerations here before installing your first production Cluster.

Prepare Kubernetes Cluster

Prepare the Kubernetes cluster nodes. In this guide, we assume that we're going to use only 2 Kubernetes nodes. One for data plane with the name of data-plane-1 and the other for control plane control-plane-1. Note that you can obtain the Kubernetes node information via the command kubectl get nodes.

Label the data plane node in order to be used as a data plane node by Octelium as follows:

kubectl label nodes data-plane-1 octelium.com/node-mode-dataplane=

Label the control plane node in order to be used as a control plane node by Octelium as follows:

kubectl label nodes control-plane-1 octelium.com/node-mode-controlplane=

Taint the data plane node with the key octelium.com/gateway-init and the effect NO_SCHEDULE in order for the node to not start hosting Services until the GatewayAgent is deployed as follows:

kubectl taint nodes data-plane-1 octelium.com/gateway-init=true:NoSchedule

If the data plane node (i.e. data-plane-1 in our case) is behind NAT and the default interfaces are set to a private IP, Octelium will try to obtain the node public addresses first by using the values set in node.status.addresses[] whose type field is set to ExternalIP. If such value does not exist or is set to a private IP, then you must manually add the public IP of the data plane node as an annotation as follows:

kubectl annotate node data-plane-1 octelium.com/public-ip=1.2.3.4

Install a CNI plugin if your Kubernetes cluster does not already have one. You can for example install Cilium as illustrated here. Another popular option is Calico which you can install as illustrated here.
Install Multus CNI. If your Kubernetes cluster uses containerd as the container runtime (which is the default option in many Kubernetes deployments) you need to install Multus as follows:

kubectl apply -f https://raw.githubusercontent.com/k8snetworkplumbingwg/multus-cni/master/deployments/multus-daemonset.yml

However, if your Kubernetes cluster uses CRI-O instead of containerd, then you need to install Multus as follows:

kubectl apply -f https://raw.githubusercontent.com/k8snetworkplumbingwg/multus-cni/master/deployments/multus-daemonset-crio.yml

Prepare a Bootstrap Config File

Prepare a Bootstrap config file. A minimal production Bootstrap config file can contain only the storage information of your PostgreSQL and Redis stores. Here is an example:

1spec:
2  primaryStorage:
3    postgresql:
4      username: postgres
5      password: password
6      host: pg.provider.example.com
7      port: 5432
8      database: octelium
9      isTLS: true
10  secondaryStorage:
11    redis:
12      username: redis-user
13      password: password
14      host: 1.2.3.4
15      port: 6379
16      database: 0
17      isTLS: true

Installation

We can now install the Cluster via the command octops init as follows:

octops init <DOMAIN> --bootstrap /PATH/TO/BOOTSTRAP_CONFIG.yaml

Note that by default, octops init command uses the kubeconfig that is located at $HOME/.kube/config. You can override that location via the --kubeconfig flag as follows:

octops init <DOMAIN> --kubeconfig /path/to/kubeconfig --bootstrap /PATH/TO/BOOTSTRAP_CONFIG.yaml

You can also set the kubeconfig context via the --kubecontext flag. Note that by default, octops init installs the latest Octelium Cluster version. If you want to override that behaviour and install a certain version you can do so via the --version flag as follows:

octops init <DOMAIN> --bootstrap /PATH/TO/BOOTSTRAP_CONFIG.yaml --version v0.9.0

NOTE

If you're installing the Cluster on top of a single node VM, as opposed to a managed Kubernetes cluster with a managed load balancer, whose public IP address is used as an external IP for the Cluster's Ingress, you can simply inform octops init command of the public IP address of the node via the OCTELIUM_REGION_EXTERNAL_IP environment variable. Here is an example:

OCTELIUM_REGION_EXTERNAL_IP=1.2.3.4 octops init <DOMAIN> --kubeconfig /path/to/kubeconfig --bootstrap /PATH/TO/BOOTSTRAP_CONFIG.yaml

This operation usually takes a few minutes to complete depending on the performance and specs of the underlying infrastructure of the Kubernetes cluster nodes. This command installs all the Octelium dependencies, components, resources, etc... using the in-Cluster installer component called Genesis and then waits for the Octelium Cluster to become ready for use.

Setting Public DNS

By the end of the installation, you must set the public DNS for the Cluster domain in order for it to be able to receive requests by Users publicly over the internet. You can read more about how to obtain the public IP address used to set the public DNS entry of the Cluster domain here.

Setting Cluster TLS Certificate

By the end of the installation, you must also set the TLS certificate for the Cluster domain in order for it to be able to receive requests by Users publicly over the internet. You can read more about how to obtain the public IP address used to set the public DNS entry of the Cluster domain here.

What Now?

Now our Cluster has been successfully installed and is now running. You can learn more about how to manage and use the Cluster in the following guides:

First Steps Managing the Cluster here.
Managing Services here.
Access control and Policies here
Adding IdentityProviders here