Deployment Strategy
This guide explains why Axual deploys the platform on Kubernetes with Helm, how many Kafka clusters an installation needs, what a values-file based configuration buys you, and why Axual prefers a reviewed GitOps workflow over automatic synchronisation.
Type |
Explanation |
Goal |
Understand the deployment model the rest of the installation documentation assumes. |
Audience |
Platform Operators and architects deciding how the platform will be deployed and maintained. |
When to use |
Read before the first installation, and when setting up the deployment pipeline. |
Kubernetes
The Axual Platform once ran as containers on virtual machines, installed by scripts. Kubernetes replaced that as the preferred way to install Axual, for the reasons set out in Kubernetes mechanisms.
| Operating the Axual Platform requires a basic understanding of Kubernetes. |
Every moving part of the platform runs as a Kubernetes object, which you inspect with kubectl, with oc on OpenShift, or through a tool such as k9s.
Everything from here on, Quick Setup and the full installation, assumes a Kubernetes or OpenShift cluster, because that is what a real deployment runs on. Trying the platform does not require one. Axual Desktop runs a full local instance, including a Kafka cluster, directly on Docker Compose. It needs one command, no cluster, no Helm chart, and none of the values-file decisions the guides below cover. That makes it the fastest way to reproduce a bug or try a change before touching a real environment. Nothing about it carries over to a Kubernetes installation. Move to Quick Setup or the full installation once Kubernetes itself, or a component’s behaviour under it, is what you need to see.
How many Kafka clusters
Every Streaming installation stands up one more Kafka cluster, so this decision shapes how many times stages 3 and 4 repeat. Each additional cluster needs its own broker and controller node group; Cluster capacity sizes what one cluster requires.
The table below covers the three reasons to add or share a cluster, and where each is explained in full:
| Reason | What it buys you | Detail |
|---|---|---|
Consolidate environments or tenants onto one cluster |
Avoids the cost and deployment complexity of running more clusters, at the price of isolation. Topic, consumer group and transactional ID naming patterns, such as |
|
Share a cluster across tenants |
Needs the Principal Chain Builder and the custom Axual Kafka image, because a plain certificate Distinguished Name (DN) does not uniquely identify a principal when different tenants' Certificate Authorities (CAs) can issue certificates with the same DN. |
|
Span one Instance across more than one cluster |
Buys resilience rather than consolidation: several in-sync Kafka clusters kept synchronised by the Axual Distributor, so applications can fail over between them. |
Governance and Streaming do not have to match one-to-one. A Streaming installation deploys exactly one Kafka cluster, but a single Governance installation can manage several of them, including clusters it did not deploy itself. The common shape is one Governance installation managing every Kafka cluster centrally, rather than one Governance installation per cluster; see The installation order.
Helm Charts
To create, update and remove Kubernetes objects such as Deployments, Secrets and IngressControllers, Axual relies on Helm Charts. A Helm Chart is a blueprint of many cooperating Kubernetes objects that one configuration file drives. Chart.yaml is the blueprint and values.yaml is the configuration file. Chart.yaml pins the component versions the chart installs, and the values.yaml you supply overrules the chart’s own defaults.
During the installation phase the Chart.yaml stays static while the values.yaml changes heavily to fit the installation requirements.
During the running phase the values.yaml stays relatively static, and the version inside the Chart.yaml is what changes at a platform release or an upgrade. See Axual Platform Releases and Upgrading Axual.
| YAML is built around indentation, so one space too many or too few makes the whole configuration file invalid. The resulting error is not explicit and often names the wrong line, so enable a "show whitespace" setting in your editor before changing these files. |
Directly installing Helm Charts
Installing a chart by hand with helm install works, and Install a chart directly gives the commands.
That route does not scale past a trial. The Axual charts template a large number of Kubernetes objects, so an upgrade applied without a preview is hard to review. A change made at a terminal also leaves no record of who made it or why. The deployment pipeline below solves both.
GitOps & CI/CD
A values-file based configuration puts every installation detail in git, which keeps the full history of changes under a declarative GitOps workflow.
A Continuous Integration and Continuous Delivery (CI/CD) tool completes that workflow by keeping the deployment state in Kubernetes matched to the configuration in git. Argo CD and Flux CD both do this.
These Continuous Delivery tools can apply a git change to the cluster automatically. Axual prefers the diff function instead, to preview the changes before applying them.
| Automatic synchronisation on a mission-critical platform risks unforeseen side effects with significant impact. |
During a Troubleshooting session, step outside GitOps and modify Kubernetes objects directly rather than running a whole cycle of change, push, review, merge, refresh CD, diff, apply for every configuration change. Edit a ConfigMap or a Deployment with kubectl edit, or through the Argo CD interface. The next synchronisation reverts the edit, so once you have a solution, put the correct configuration into git or it is lost.
This documentation uses helm upgrade --install commands and Argo CD examples. Replace either with the CI/CD workflow that suits your organisation.
|
On live clusters holding business data, use protected git branches and merge requests to keep accidental, and possibly breaking, changes off the platform.
What this buys you on a change
With the values in git and a CD tool watching them, a platform change is a merge request. The diff shows exactly which Kubernetes objects move, a reviewer sees it before it reaches the cluster, and a rollback is a revert to the previous commit rather than a reconstruction from memory.
Upgrading Axual walks a real upgrade through that workflow.