Install Ryax on Kubernetes

We assume that you are comfortable with Kubernetes and therefore we do not provide too many details on the Kubernetes parts of the installation.

Requirements

All you need to install Ryax is a Kubernetes cluster. Supported versions are:

  • kubernetes > 1.19; <1.25

Hardware:

  • At least 2 CPU core

  • 4GB or memory

  • 40GB of disk available

Note that depending on the Actions that you run on your cluster you might need more resources.

Preparatory steps

  • Make sure your configuration point to the intended cluster: kubectl config current-context.

  • Make sure it is a Kubernetes cluster dedicated to Ryax: we offer no guarantee that Ryax runs smoothly alongside other applications.

  • Make sure you have complete admin access to the cluster. Try to run kubectl auth can-i create ns or kubectl auth can-i create pc, for instance.

$ kubectl auth can-i create ns
Warning: resource 'namespaces' is not namespace scoped
yes

Also, be sure that you have access to a DNS server where you can add a new A or CNAME entry for your cluster.

Warning

Special warning for EKS (AWS Elastic Kubernetes Service)

Ryax requires persistent storage and by default, EKS does not provide any storage driver. Please, install the EBS CSI plugin first.

Also be aware that you cannot use Fargate because it does not support persistent storage

Customize your installation

Installing Ryax is analogous to installing a Helm chart. To begin we will start with a default configuration, and make a few tweaks so that everything is compatible with your Kubernetes provider. Be assured however that you will be able to fine-tune your installation later on.

First create a directory to organize the Ryax installation.

mkdir ryax_install

Just like helm charts, we call “values” the configuration of a Ryax cluster. Let’s initialize a basic values file.

docker run -v $PWD/ryax_install:/data/volume -u $UID ryaxtech/ryax-adm:latest init --values volume/ryax_values.yaml

Edit the file with vim, or your favorite text editor.

vim ryax_install/ryax_values.yaml

The clusterName and domainName defines the name you give to your cluster, which is used in various places. One of those places is the URL of your cluster that will end up being <clusterName>.<domainName>, therefore it has to be consistent with your DNS. If you do not intend to configure a DNS cluster, just leave this to the default value and disable the certManager, and in this case be aware you will access Ryax through the IP address directly and https certificate will be self-signed.

Warning

Depending on your Kubernetes cluster setup, you might have issue with Cert Manager which is use to get a valid HTTPS certificate. See the Cert Manager compatibility documentation for more details.

If you want to deal with the certificate yourself, you can disable it with:

certManager:
  enabled: false

Set the version field with the Ryax version, for example: 23.03.0. The latest stable version is can be found in the releases page.

The Ryax installation is based on Helm charts, one for each service with a Helmfile to define the whole cluster configuration. To customize your installation. You can set any configuration field using the values keyword. A detailed description of all the values can be found in ryax-adm/helm-charts/values.yaml.

If not set, Ryax will use the default Storage Class provided by the Kubernetes cluster for all services. The volumes are used to store the internal database (datastore), object store for workflows IO (filestore), and a container registry for the Ryax Actions containers (registry). For better performance you can set each storage class independently. It is recommended to have SSD backed storage for the filestore to avoid delays on file transfers.

We recommend that you start small with the volume sizes, you can extend them later on with most Storage providers. The default values give comfortable volume sizes to start working on the platform.

An example of a simple values file for Ryax.

# File: ryax_install/ryax_values.yaml
# Set the Ryax version (just change this and apply update)
version: '23.03.0'

# The DNS of you cluster will be <clusterName>.<domainName>
clusterName: mybackend
domainName: example.com

# Enable HTTPS
tls:
  enabled: true

# Get a valid HTTPs certificate from Let's Encrypt (requires valid DNS)
certManager:
  enabled: true

# Set this tu debug to get more logs on all services
logLevel: info

# Size of the volumes attached to each services
datastore:
  pvcSize: 2Gi
filestore:
  pvcSize: 10Gi
registry:
  pvcSize: 10Gi

# Uncomment to choose the type of storage to use for persistency
# storageClass: default

# Enable the monitoring stack (Prometheus/Grafana)
monitoring:
  enabled: true

Install Ryax

First, be sure that your Kubernetes context is set properly. Make sure that either your KUBECONFIG variable is set and point to you cluster, or that the ~/.kube/config file contains you cluster configuration. See Preparatory steps to check you cluster access.

Warning

Depending on the Cloud provider you are using you might have to mount its configuration inside the container. For the following providers add the associated option:

  • Microsoft Azure: -v $HOME/.azure:/root/.azure

  • Google Cloud: -v $HOME/.config/gcloud:/root/.config/gcloud

  • AWS: -v $HOME/.aws:/root/.aws

Once you have customized your configuration you can install Ryax on your cluster (don’t forget to add extra option, see previous warning):

docker run -v $PWD/ryax_install:/data/volume -v $HOME/.kube/config:/data/kubeconfig.yml ryaxtech/ryax-adm:latest apply --values volume/ryax_values.yaml --retry 2 --suppress-diff

Note

Optionally you can populate your cluster with (don’t forget to add extra option, see previous warning):

docker run -v $PWD/ryax_install:/data/volume -v $HOME/.kube/config:/data/kubeconfig.yml --entrypoint=helm ryaxtech/ryax-adm:latest upgrade --install ryax-init ./helm-charts/ryax-init -n ryaxns

If the installation fails, check the logs, check your configuration and try again. If you are lost, or have any questions, please join our Discord server. We will be happy to help!

Configure your DNS

The last step is configuring your DNS so that you can connect to your cluster. The address you should register is <clusterName>.<domainName>.

To retrieve the external IP of your cluster, run this one-liner

kubectl -n kube-system get svc traefik -o jsonpath='{.status.loadBalancer.ingress[].ip}'

Or simply look at the response of kubectl -n kube-system get svc traefik, under “External IP”.

Depending on your Cloud provider you will have an IP address which requires a A entry, or a DNS (AWS) that requires you to create a CNAME entry.

Once you entry is created, and only if tls is enabled, you will have to wait for Let’s Encrypt to provide you a valid certificate. You can check with:

kubectl get certificates -n ryaxns

The state should be READY: true.

Access to your cluster

Now you can access to you cluster with https://<clusterName>.<domainName> on your web browser.

Default credentials are user1/pass1

Warning

Change this password and user as soon as you’re logged in!

Cluster Update

The Ryax configuration is declarative, so in order to update your cluster you just have to change the configuration and apply it.

Note

You need to configure your Kubernetes cluster access and to set the Cloud provider specific otions, see installation process for more details.

The Ryax configuration is stored as a secret inside your cluster after each successful apply. You can get the actual cluster configuration from the cluster itself with:

docker run -v $PWD/ryax_install:/data/volume -v $HOME/.config/gcloud:/root/.config/gcloud -v $HOME/.kube/config:/data/kubeconfig.yml ryaxtech/ryax-adm:latest init --from-cluster --values volume/ryax_values.yaml

``` warning:: Before any updates, do a backup with ryax-adm backup and have a look at the changlog to see if there is any extra step needed.

Now you can simply change the `version` field in the configuration before applying the configuration like in the installation steps described above.