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-grade and scalable deployments. It is highly recommended that you 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, named data-plane-1, and the other for control-plane, named control-plane-1. Note that you can obtain the Kubernetes node information via the command kubectl get nodes.

1. Label the data-plane node to be used as a data-plane node by Octelium as follows:

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

2. Label the control-plane node to be used as a control-plane node by Octelium as follows:

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

3. Taint the data-plane node with the key octelium.com/gateway-init and the effect NO_SCHEDULE to prevent the node from hosting Services until the GatewayAgent is deployed as follows:

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

4. If the data-plane node (i.e. data-plane-1 in our case) is behind NAT, you might want to inform the Cluster of the node's public IP address (read more here) as follows:

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

5. 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.

6. 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:

1
spec:
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. By default, octops init installs the latest Octelium Cluster version. If you want to override that behavior 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 1.2.3

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 to enable it to receive requests from 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 to enable it to receive requests from 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 to Managing the Cluster here.
• Managing Services here.
• Access control and Policies here.
• Adding IdentityProviders here.