Installation and Configuration of Axual Platform
This guide is the entry point for installing the Axual Platform: what to prepare, the order the layers go in, which components are required, when to install governance only, and where to go when a stage fails. For what the platform is made of before any of it is installed, see Axual Architecture & Components.
Type |
Reference |
Goal |
Find the stage of the installation you are at, and the guides that stage needs. |
Audience |
Platform Operators installing or extending an Axual Platform on Kubernetes or OpenShift. |
When to use |
Start here before the first chart is installed, and come back to find the next stage. |
Contents
The sections below follow an installation from an empty cluster to a platform people can use:
The installation order
Every installation moves through the same stages, and each assumes the previous one is finished. The table names each stage, the guides that cover it, whether an installation needs it, and the state the stage leaves behind:
| Stage | Guides | Required | Finished when |
|---|---|---|---|
Before 1 |
Yes |
You have decided whether the charts run under Helm or a GitOps workflow, and how many Kafka clusters the installation needs. Both decisions apply to every stage below, which is why they carry no stage number of their own. |
|
1 |
Yes |
The cluster meets the infrastructure requirements and carries the operators, ingress controller and certificates the Axual charts expect. |
|
2 |
Yes |
You know whether the installation needs stage 3, or Governance manages a Kafka cluster you already run. |
|
3 |
Unless governance only |
Brokers are reachable, topics can be created, and Apicurio Registry answers when enabled. |
|
4 |
Yes |
Self-Service is reachable through the API Gateway. |
|
5 |
No |
The optional components you need are running. Any subset of them, or none at all. Its five component families do not depend on each other, so install them in any order, at any point after stage 4. |
|
6 |
Yes |
Keycloak realms and the first Self-Service resources exist, so people can start using the platform. Vault is set up when the installation uses it. |
|
7 |
Before go-live |
Logs, metrics, traces and alerts reach your monitoring stack. This stage can run alongside stages 3 to 5, and belongs before go-live. |
Stages 3 and 4 install the two halves of the platform separately because they serve different jobs: Streaming is the data plane, the Kafka cluster that holds the data, and Governance is the control plane that manages one or more of those clusters. Each half has its own Helm chart, so a Governance installation can manage a Kafka cluster it did not deploy.
The "Before 1" row is a decision rather than a stage: Helm or GitOps changes how every later stage is applied, so it belongs before the first chart and outside the numbering.
Certificates outlive the installation. Stage 1 only gets the first set in place; Certificate Management covers reading, rotating and replacing them on a platform that is already running.
Required components
Within the stages, some components serve every installation and others serve one feature. The table lists the components of stages 3, 4 and 6 and what each one is needed for. Every stage 5 component is optional, and stage 7 has no components of its own:
| Component | Stage | Required | Needed for |
|---|---|---|---|
Axual Kafka |
3 |
Unless governance only |
The Kafka cluster that holds the data. |
Apicurio Registry |
3 |
No |
Topics with Avro, Protobuf or JSON Schema data. |
Rest Proxy |
3 |
No |
Clients that produce and consume over HTTP. |
Platform Manager, Platform UI, API Gateway |
4 |
Yes |
Self-Service and its API. |
Keycloak |
4 |
Yes |
Sign-in to Self-Service. |
MySQL for Platform Manager and Keycloak |
4 |
Yes, or an external database |
Storage for Platform Manager and Keycloak. |
Topic Browse |
4 |
No |
Browsing topic messages in Self-Service. |
Metrics Exposer |
4 |
No |
Insights in Self-Service. Reads from the monitoring stack of stage 7. |
Vault |
4 and 6 |
No |
Credentials of Simple Authentication and Security Layer (SASL) clusters and of connectors. |
Local realm in Keycloak |
6 |
Yes |
Sign-up of the first users. |
Single sign-on (SSO) realm |
6 |
No |
Sign-in through your own identity provider. |
Governance only
Axual Governance can manage a Kafka cluster it did not deploy. It supports Apache Kafka, Strimzi and Red Hat AMQ Streams clusters, on premises or in a private cloud. When you already run one of those, skip stage 3, install Governance in stage 4, and register your cluster with Kafka Cluster Onboarding Guide.
On OpenShift, install Governance with Deploying Axual Governance on OpenShift. It uses the Red Hat certified Helm chart, together with the database, Keycloak and Vault the governance layer needs there.
To look at the platform before installing it, use Axual Desktop. It runs a full local instance, including a Kafka cluster, on Docker Compose and needs no Kubernetes cluster.
When a stage fails
Troubleshooting covers the failures these stages produce, from an ingress that cannot be reached to a connector that starts but moves no data. It is a destination from any stage above rather than a stage of its own.
Once the platform is live, Acting on Alerts is the runbook for an alert that has already fired.