Installation

There are two ways to run the Stackable Listener Operator:

Helm managed Docker container deployment on Kubernetes
Build from source

Prerequisites

You will need:

a Kubernetes cluster
kubectl
Helm

Resource sizing depends on cluster type(s), usage and scope, but as a starting point we recommend a minimum of the following resources for this operator:

0.2 cores (e.g. i5 or similar)
256MB RAM

ListenerClass presets

When installing the listener-operator you need to choose a ListenerClass preset (or use the default one). A ListenerClass controls two important aspects:

Service type: Determines whether ClusterIP, NodePort or LoadBalancer is used
Pinning: When using NodePorts (and only then) if pinning is enabled, the Pods are bound to a specific Kubernetes node. This allows the Pods to always start on the same node and keep a stable endpoint without the need for an (e.g. expensive) LoadBalancer. However, this pinning can cause problems during node rotation (e.g. on a regular basis), as Pod will be stuck in Pending when the node they are pinned to is gone.

Use the following decision tree to decide on the ListenerClass preset to use:

flowchart LR LB{LoadBalancer supported?} LB -->|yes| ephermal-nodes[Use ephermal-nodes] LB -->|no| node-rotation{Nodes regularly rotated?} node-rotation -->|yes| complicated[Use stable-nodes to prefer NodePort
over LoadBalancers.
However, don't use the
external-stable ListenerClass at all,
use external-unstable instead] node-rotation -->|no| stable-nodes[Use stable-nodes]

stackablectl

The recommended way to install the operator is using stackablectl. Starting with 1.2.0 it automatically detects kind and k3s cluster and uses stable-nodes

Helm

As stackablectl internally invokes Helm, you can absolutely install the operator only using Helm. Helm allows you to download and deploy Stackable operators on Kubernetes.

helm repo subcommands are not supported for OCI registries. The operators are installed directly, without adding the Helm Chart repository first.

Install the Stackable Listener Operator

$ helm install listener-operator oci://oci.stackable.tech/sdp-charts/listener-operator

Helm will deploy the operator in Kubernetes containers and apply the CRDs. You’re now ready to expose services!

Microk8s

Microk8s uses a non-standard Kubelet state directory. Installing listener-operator on Microk8s requires the argument --set kubeletDir=/var/snap/microk8s/common/var/lib/kubelet to be added to the helm install command.

HUAWEI cloud

In some cases HUAWEI cloud has the kubelet directory located at /mnt/paas/kubernetes/kubelet, resulting in the following error:

failed to publish volume error=status: Unavailable, message: "failed to create secret parent dir /mnt/paas/kubernetes/kubelet/pods/<POD_ID>/volumes/kubernetes.io~csi/pvc-<PVC_ID>/mount: No such file or directory (os error 2)"

In case you are encountering the mentioned error (or listener-operator does not work on your HUAWEI cloud at all), you need to add the argument --set kubeletDir=/mnt/paas/kubernetes/kubelet to the helm install command.

IBM cloud

In some cases IBM cloud has the kubelet directory located at /var/data/kubelet/, resulting in the following error:

failed to publish volume error=status: Unavailable, message: "failed to create secret parent dir /var/data/kubelet/pods/<POD_ID>/volumes/kubernetes.io~csi/pvc-<PVC_ID>/mount: No such file or directory (os error 2)"

In case you are encountering the mentioned error (or listener-operator does not work on your IBM cloud at all), you need to add the argument --set kubeletDir=/var/data/kubelet to the helm install command.

VMware Tanzu

VMware Tanzu uses a non-standard Kubelet state directory. Installing listener-operator on Tanzu requires the argument --set kubeletDir=/var/vcap/data/kubelet to be added to the helm install command.