Installation

Want to learn more about the Voithos software architecture before installing? Check out the Architecture section.

Prerequisites

First, ensure you have the Kubernetes CLI, Helm, a Kubernetes Cluster, and a few other dependencies installed.

Kubectl

Kubectl is a command line interface for running commands against Kubernetes clusters, visit kubectl docs to see how to install it.

Next, ensure you have access to a cluster. Do this by using kubectl to check your Kubernetes version:

kubectl version

Kubernetes Cluster

If you don’t have a Kubernetes cluster, here’s a official guide to set one up.

Voithos requires Kubernetes 1.23 or higher

We recommend clusters with >= 2vCPU | 4Gi RAM | 5GB storage

If you are just wanting to give Voithos a test drive, you can do so by spinning up a minikube or kind cluster on your local machine.

Helm

Helm is a package manager for Kubernetes. If you already use helm 3, skip to the next section, if not you can follow these instructions to install it.

Helm v2 is deprecated, Voithos can be installed via Helm v3.

Cert Manager

Voithos has only one external dependency, Cert Manager, which its storage layer uses internally (your data does not leave your cluster!). If you already have Cert Manager installed you can skip to the next section, you’ll just need to make Voithos aware of the namespace in which it is installed ("cert-manager" is the default).

To install the Cert Manager, follow these instructions, and make sure to pass the --set installCRDs=true flag to the helm install command.

Virtex Account

If you’ve already created a Virtex account you can skip to the next section. If not, create an account here.

Generate an API Key

If you already have a Virtex api key you can skip to the next section.

Login to your Virtex account by clicking the Account tab in the top navbar. In the accounts console click the Profile tab in the left navbar, and then click New Api Key. This will generate the API key that your Voithos agent will use for authorization with the Virtex API.

Virtex api keys do not expire, but your account has a single valid key. If/when you refresh your API key, make sure to run helm update to avoid any disruption in service. The Voithos agent allows intermitant failed authorization attempts, however it will halt after several failed attempts!

Voithos Helm Chart

Next, install the Voithos helm chart using your Virtex account credentials.

export VIRTEX_ACCT_EMAIL="<your-acct-email>"
export VIRTEX_API_TOKEN="<your-api-token>"

helm registry login registry.virtex.ai/voithos \
    --username "robot_$(echo -n ${VIRTEX_ACCT_EMAIL} | sed 's\@\_at_\g')" \
    --password "$(echo ${VIRTEX_API_KEY##*.})"

Storage

Voithos will provision persistent volumes in your cluster. If you are evaluating Voithos in a non production environment, you can just point Voithos at the default storage class (e.g., storage.storageClass="standard"). In large production environments, we recommend plugging Voithos into a more performant storage tier, commensurate with the size of your cluster. Below are starting points for storage class configurations you might consider using on the major cloud providers.

The default storage class setting is storage.storageClass="standard"

Whenever possible, set storage.volumeAccessMode="ReadWriteMany". By default Voithos installs with a value of "ReadWriteOnce", as this is the only storage driver agnostic setting. Before changing to "ReadWriteMany", ensure that the storage driver referenced in your storageclass (under the .provisioner field) allows this access mode (see this compatibility table).

In production settings, use xfs formatted disks when possible.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: "<sc-name>"
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
reclaimPolicy: Retain
provisioner: ebs.csi.aws.com
parameters:
  csi.storage.k8s.io/fstype: xfs
  type: io1
  iopsPerGB: "50"

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: "<sc-name>"
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
reclaimPolicy: Retain
provisioner: kubernetes.io/gce-pd
parameters:
  type: pd-ssd
  fstype: xfs
  replication-type: none

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: "<sc-name>"
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
reclaimPolicy: Retain
provisioner: kubernetes.io/azure-file
parameters:
  skuName: Standard_LRS
  fsType: xfs

Install Voithos

Once you’ve created/selected a storage class, you can install Voithos with the following helm command.

For a full list of helm chart configuration options, refer to the chart configuration section

helm upgrade voithos oci://registry.virtex.ai/voithos/voithos \
    -n "voithos-system" \
    --install \
    --create-namespace \
    --set auth.virtexAccountEmail="<virtex account email>" \
    --set auth.virtexApiKey="<api key>" \
    --set storage.storageClass="<sc-name>"

Verify Installation

The helm installation can take up to 10 minutes to complete. Next, verify the installation:

kubectl -n voithos-system rollout status deployment controller --timeout=300s
kubectl -n voithos-system rollout status deployment dashboard

If you’re installing Voithos into a resource constrained cluster, you may need to adjust the resources that Voithos installs with. See .components.*.resources in the values.yaml. Chicken and egg.

What’s next?

After Voithos is installed, you’ll want to customize it for your specific applications. To learn more about how to do this, head over to the Configuration and Tutorial sections.