Ways of deploying Axual (Best practices)

Kubernetes

Previously, the Axual Platform was deployed as containers on virtual machines using install scripts, but Kubernetes was quickly adopted to become the preferred way to install Axual thanks to the incredible resilience benefits of Kubernetes.

As an operator, to understand and operate the Axual Platform, basic understanding of Kubernetes is expected.

All moving parts of the platform are deployed as Kubernetes components that can be inspected through interactions with kubectl, oc (if on OpenShift) or through k9s for example.

Helm Charts

In order to create, update and remove Kubernetes components such as Deployments, Secrets and IngressControllers, Axual relies on Helm Charts. Helm Charts can be considered blueprints of many cooperating Kubernetes components that can be configured from a single configuration file. The files Chart.yaml and values.yaml are the blueprint and the configuration file respectively. The Chart.yaml contains things like default configurations and component versions that may be overruled by the values.yaml.

During the installation phase of the platform, the Chart.yaml generally stays static while the values.yaml is heavily modified to fit the installation requirements.
However, during the running phase the values.yaml stays relatively static and mainly the version used inside the Chart.yaml will be changed during platform releases or upgrades.

If you decide to modify the YAML files, please be aware that YAML is based around indentation, one space too many or little, and the entire configuration file will be deemed "corrupt". If this happens, the error isn’t really explicit, as it will not be able to precisely explain where this has happened (ie. give the wrong line number in the configuration file). Be sure to have an equivalent to "show whitespaces" setting enabled when editing these types of files.

Directly installing Helm Charts

It is possible to install the Axual Helm charts directly, using helm install <installation name> -n <namespace> <helm charts> -f <values.yaml path>, for example:

helm install governance -n kafka axual-helm-stable/axual-governance -f axual-governance/values.yaml
NAME: governance
LAST DEPLOYED: Tue Jul 16 09:22:31 2024
NAMESPACE: kafka
STATUS: deployed
REVISION: 1
NOTES:
Thank you for installing Axual Governance!
Now that you have deployed Axual Governance, you should look over the docs on using
Axual with Kubernetes available here:
https://docs.axual.io/operations/2023.2/index.html

Once a Helm chart is installed, it is possible to upgrade the deployment on any changes to the values.yaml or Chart.
The Helm diff plugin will improve direct Helm installations, but due to the large number of Kubernetes objects in the Axual Helm charts, it is advised to move to a deployment pipeline (see below).

There is a Working with Helm charts guide to get you familiarized with the Axual Helm charts.

GitOps & CI/CD

A massive benefit of having a values-file based configuration is that all installation details can be stored in git, that allows all changes to be stored and safeguarded into a declarative GitOps workflow.
Part of that workflow is a CI/CD tool that ensures the deployment state within Kubernetes matches the configuration in git. For that purpose Argo CD or Flux CD are great tools.

These CD tools allow for automatic application of changes in git onto the Kubernetes cluster, however within Axual we prefer to make use of the diff function instead, to get a preview of the changes that will be applied.
Automatic synchronization on a mission-critical platform may result in unforeseen side effects with significant impact.

During any Troubleshooting sessions, it may be beneficial to let go of GitOps for a while and modify Kubernetes objects directly to avoid having to do a whole cycle of change, push, review, merge, refresh CD, diff, apply for every configuration change. Of course once a solution is found, the correct configuration needs to be added to git to avoid it being lost.

In this documentation helm apply commands and examples using Argo CD are used, these can be replaced by different CI/CD workflows that suit your organization.

For live clusters used with business data, using protected git branches and merge requests is advised to avoid accidental (possibly breaking) changes to the platform.

Change workflow example

When the solutions mentioned above are in place, upgrading Axual Platform becomes very convenient, because all changes are clearly visible and rollbacks can be as easy as returning to a previous git commit.
For example, follow this guide on upgrading Axual Platform