Deploying Axual Governance on Kubernetes

This guide walks you through installing Axual Governance on Kubernetes, initialising its Vault, onboarding the Kafka cluster you already run, preparing Self-Service, and verifying that a message reaches a topic.

Type

Tutorial

Goal

Have Axual Governance running on your own cluster, managing a Kafka cluster you already had.

Audience

Platform Operators evaluating Axual against an existing Kafka cluster on Kubernetes, with no prior Axual experience.

When to use

Stage 2 of The installation order, on the trial path rather than the full installation.

The sections below cover the whole run, in order:

Prerequisites
Installation procedure

Prerequisites

To install Axual Governance in your own infrastructure, you need:

Credentials for the Axual Harbor Registry (https://registry.axual.io/)

If you do not have credentials yet, contact Axual Support at support@axual.com.
A Kubernetes cluster (version 1.24 or above) with an ingress controller, described in Install an Ingress Controller, or an OpenShift cluster (version 4.12 or above)
Helm (version 3 or above), and enough familiarity with Kubernetes and Helm charts to read what the commands below do
A terminal
For the Kafka cluster you are onboarding:
- Connectivity information (endpoint, port)
- Security information (certificates, or Simple Authentication and Security Layer (SASL) credentials)

Kafka and Apicurio Registry authentication

The prerequisites depend on the type of authentication enabled on Kafka and on Apicurio Registry. Check the prerequisites for your authentication type below.

Kafka authentication

The two supported authentication types need different material, so use the column that matches your brokers:

Mutual TLS (mTLS)	Simple Authentication and Security Layer (SASL)
Authenticating to Kafka with mTLS needs the following: The Certificate Authority (CA) certificate that signed the broker certificate, in PEM format The certificate and private key Platform Manager (Self-Service) uses to authenticate to Kafka The Platform Manager certificate Distinguished Name (DN), added as a superuser in Kafka (see Apache Kafka authorisation documentation)	Authenticating to Kafka with SASL needs the following: The CA certificate that signed the broker certificate The SASL username and password to authenticate to Kafka That username, added as a superuser in Kafka (see Apache Kafka authorisation documentation)

Mutual TLS (mTLS)

Simple Authentication and Security Layer (SASL)

Authenticating to Kafka with mTLS needs the following:

The Certificate Authority (CA) certificate that signed the broker certificate, in PEM format
The certificate and private key Platform Manager (Self-Service) uses to authenticate to Kafka
The Platform Manager certificate Distinguished Name (DN), added as a superuser in Kafka (see Apache Kafka authorisation documentation)

Authenticating to Kafka with SASL needs the following:

The CA certificate that signed the broker certificate
The SASL username and password to authenticate to Kafka
That username, added as a superuser in Kafka (see Apache Kafka authorisation documentation)

Apicurio Registry authentication

Authentication on the Apicurio Registry interface needs the following information:

Basic authentication	TLS
The username and password to authenticate to Apicurio Registry	The CA certificate (PEM) that signed the Apicurio Registry certificate The certificate and private key Platform Manager (Self-Service) uses to authenticate to Apicurio Registry

Basic authentication

TLS

The username and password to authenticate to Apicurio Registry

The CA certificate (PEM) that signed the Apicurio Registry certificate
The certificate and private key Platform Manager (Self-Service) uses to authenticate to Apicurio Registry

Axual Governance supports X.509 certificates in PEM format and PKCS8 private keys in PEM format only. The file extension can be anything, for example .crt, .pem, .key or .p8.

Installation procedure

The steps below deploy Axual Governance first, then onboard your own Kafka cluster to it. The last steps set up the Self-Service resources that people in your organisation need to start using the platform.

Step 1: Preparations

The Axual Governance Helm charts need two preparations: a namespace holding a registry Secret, and a login to the chart registry.

Create a namespace and Docker Registry Secret

A namespace provides an isolation layer within a Kubernetes cluster. An image pull Secret is namespaced, so it has to exist in the same namespace as the charts that use it: run these steps once per namespace you install into.

Create the namespace.
```
kubectl create namespace axual
```
Obtain the credentials for the registry. The Secret uses the CLI secret associated with your user in Harbor, not your password. Log in to Harbor with your AzureAD credentials, open the User Profile modal from the top left menu, and either generate a new secret or copy the existing one.

If that link is not reachable, contact the Axual support team for a set of credentials to use.

Create the image pull Secret in that namespace.

kubectl -n axual                          \
    create secret docker-registry axualdockercred     \
    --docker-server=registry.axual.io                 \
    --docker-username=<YOUR_EMAIL>                    \
    --docker-password=<YOUR_CLI_SECRET>

Replace <YOUR_EMAIL> and <YOUR_CLI_SECRET> with your own credentials for the Axual Harbor Registry.

Pull the charts

Helm pulls charts from the Axual Harbor Registry only after you log in to it.

Log in to the Axual Harbor Registry. Replace <USERNAME> with your Axual Harbor Registry username; Helm then prompts for the password.
```
helm registry login registry.axual.io --username <USERNAME>
```

After you log in, you can pull the Axual Helm charts.

Step 2: Deploying Axual Governance

Deploy the governance layer against the Apache Kafka cluster you already have.

Download the example axual-governance.values.yaml

Click to open axual-governance.values.yaml

global:
  # -- Globally override the list of ImagePullSecrets provided.
  imagePullSecrets:
    - name: axualdockercred

  platform-manager-mysql:
    enabled: true

  platform-manager-vault:
    enabled: true

  keycloak-mysql:
    enabled: true

  keycloak:
    enabled: true

  # -- Axual Components toggles
  platform-manager:
    enabled: true

  platform-ui:
    enabled: true

  api-gateway:
    enabled: true

  topic-browse:
    enabled: true

## Keycloak DB
keycloak-mysql:
  fullnameOverride: "axual-keycloak-mysql"
  auth:
    rootPassword: "rootpassword"
    database: "keycloak-db"
    username: "keycloak"
    password: "Passw0rd1!"

## Keycloak
keycloak:
  autoscaling:
    enabled: false
  database:
    vendor: "mysql"
    hostname: "axual-keycloak-mysql"
    database: "keycloak-db"
    port: "3306"
    username: "keycloak"
    password: "Passw0rd1!"
  extraEnv: |
    - name: KEYCLOAK_ADMIN
      value: "admin"
    - name: KEYCLOAK_ADMIN_PASSWORD
      value: "admin123"
    - name: JAVA_OPTS_APPEND
      value: -Djgroups.dns.query={{ template "keycloak.serviceDnsName" . }}
    - name: KC_HTTP_ENABLED
      value: "true"
    - name: KC_HOSTNAME_STRICT
      value: "false"

  # This control access to the Keycloak Admin Console
  ingress:
    enabled: false
    # NOTE: "nginx" refers to the community ingress-nginx controller, deprecated March 2026.
    # Axual has migrated to a supported enterprise-grade ingress controller.
    # Update this value to match the ingress class configured in your cluster.
    ingressClassName: "nginx"
    rules:
      - # -- The fully qualified domain name of a network host.
        host: "axual.<domain>"
        paths:
          - # -- Matched against the path of an incoming request.
            path: "/auth"
            # -- Determines the interpretation of the Path matching.
            # Can be one of the following values: `Exact`, `Prefix`, `ImplementationSpecific`.
            pathType: "ImplementationSpecific"
    tls: [ ]

## Platform Manager DB
platform-manager-mysql:
  fullnameOverride: "axual-platform-manager-mysql"
  auth:
    rootPassword: "rootpassword"
    database: "selfservice-db"
    username: "fluxmaster"
    password: "Passw0rd"

## Platform Manager
platform-manager:
  serviceMonitor:
    enabled: false
  
  prometheusRule:
    enabled: false
  # Enable Remote Debug with Platform Manager
  debug:
    enabled: false

  config:
    spring:
      # Spring Datasource
      datasource:
        name: "fluxdb"
        url: "jdbc:mysql://axual-platform-manager-mysql:3306/selfservice-db?useSSL=false&useLegacyDatetimeCode=false&serverTimezone=UTC"
        username: "fluxmaster"
        password: "Passw0rd"
        driver-class-name: "com.mysql.cj.jdbc.Driver"
      # Spring JPA
      jpa.database-platform: "org.hibernate.dialect.MySQLDialect"
      # Flyway Configuration
      flyway:
        locations: "classpath:db/migration/mysql"

    # Axual Platform Manager
    axual:
      api.available.auth.methods: "SSL, SCRAM_SHA_512"
      # Instance Manager Configuration
      instance-api:
        available: false
      # Application Operation Manager Configuration
      operation-manager:
        available: false
      # Connect Configuration
      connect:
        available: false
      # Keycloak Configuration
      organization-manager:
        auth-provider: "keycloak"
        keycloak:
          url: "http://governance-keycloak-http/auth"
          username: "admin"
          password: "admin123"

      # Security Configuration
      security:
        header-based-auth: true # Disable Keycloak and rely on headers passed from API Gateway

    # Governance Vault Configuration
    governance:
      vault:
        enabled: false
        uri: "http://axual-governance-platform-manager-vault:8200"
        path: "governance"
        roleId: "885d808c-6c58-33fe-fe4f-592b32eaa763"
        secretId: "efb8dc0a-f16a-913c-6f7c-99dbf77ccce1"

    # Vault Configuration for Connectors
    vault:
      enabled: false

    # Subscription Management Configuration
    subscription-management:
      enabled: false

    # Server Security
    server:
      ssl:
        enabled: false
      forward-headers-strategy: framework

## Self-Service UI
platform-ui:
  serviceMonitor:
    enabled: false
  
  prometheusRule:
    enabled: false

  # Auth0 Function Qualified Domain
  auth0:
    fqdn: "axual.<domain>"

  # PlatformManager Function Qualified Domain
  platformManager:
    fqdn: "axual-governance-platform-manager"

  # Window.ENV Configuration
  config:
    mgmtApiUrl: "https://axual.<domain>/api"
    # this URL needs no ending `/`
    mgmtUiUrl: "https://axual.<domain>"
    topicBrowseUrl: 'https://axual.<domain>/api/stream_configs'

    # Feature Flags
    billingEnabled: false
    insightsEnabled: false
    streamBrowseEnabled: false
    # This is for deciding on SB/CB(false) or TB(true)
    topicBrowseEnabled: true
    dataClassificationEnabled: false
    connectEnabled: true

    subscriptionEnabled: false

    # Keycloak Configuration
    oidcEndpoint: "https://axual.<domain>"
    oidcScopes: "openid profile email"
    configurationType: "remote"
    responseTypes: "code"
    clientId: "self-service"
    clientSecret: "notSecret"

    # OM Configuration
    organizationManagerUrl: 'https://axual.<domain>/api/organizations'
    organizationShortNameEditEnabled: true

    # Wizard Providers Configuration
    enabledKafkaProviders:
      - apache_kafka

## Topic Browse
topic-browse:
  serviceMonitor:
    enabled: false
  
  prometheusRule:
    enabled: false

## Api GateWay
api-gateway:
  serviceMonitor:
    enabled: false
  
  prometheusRule:
    enabled: false

  debug:
    enabled: false
  # -- Configuration passed to the container.
  # Contents get injected to a ConfigMap, which gets mounted as an `application.yml` file.
  config:
    spring:
      cloud:
        gateway:
          httpclient:
            ssl:
              use-insecure-trust-manager: true

    permissions-api:
      url: "http://axual-governance-platform-manager/api/auth"

    topic-browse-config-api:
      url: "http://axual-governance-platform-manager/api/stream_configs/{id}/browse-config"

    gateway:
      endpoints:
        platformManager:
          enabled: true
          url: "http://axual-governance-platform-manager"
        organizationManager:
          enabled: false
        topicBrowse:
          enabled: true
          url: "http://axual-governance-topic-browse"
        billing:
          enabled: false
        metricsExposer:
          enabled: false
        platformUi:
          enabled: true
          url: "http://axual-governance-platform-ui"
        keycloak:
          enabled: true
          url: "http://axual-governance-keycloak-http"

    # This defines the Local Realm for user registration
    # when UI doesn't provide a Realm header -> LOCAL
    local:
      auth:
        # Outside URL for Authentication Server
        issuerUrlForValidation: https://axual.<domain>/auth/realms/local
        # Kubernetes Service Name if running Keycloak
        jwkSetUri: http://axual-governance-keycloak-http/auth/realms/local/protocol/openid-connect/certs

    # when UI provides a Realm header -> SSO
    # Keycloak Authentication Server
    sso:
      keycloak:
        advertisedBaseUrl: https://axual.<domain>
        internalBaseUrl: http://axual-governance-keycloak-http
        useInsecureTrustManager: true
    logging:
      filter:
        enabled: false

  # Only Api Gateway has an active ingress
  ingress:
    enabled: true
    # NOTE: "nginx" refers to the community ingress-nginx controller, deprecated March 2026.
    # Axual has migrated to a supported enterprise-grade ingress controller.
    # Update this value to match the ingress class configured in your cluster.
    className: "nginx"
    hosts:
      - # -- The fully qualified domain name of a network host.
        host: "axual.<domain>"
        paths:
          - # -- Matched against the path of an incoming request.
            path: "/"
            # -- Determines the interpretation of the Path matching.
            # Can be one of the following values: `Exact`, `Prefix`, `ImplementationSpecific`.
            pathType: "ImplementationSpecific"
    tls: [ ]

Determine the domain you use throughout the deployment. The domain forms the URLs of the interfaces you deploy. Set it in your shell, so the next command can template the values.yaml. Replace <YOUR_DOMAIN> with your own domain.
```
export DOMAIN=<YOUR_DOMAIN>
```
Apply your domain to the axual-governance.values.yaml you downloaded
```
sed -i '' -e "s/<domain>/$DOMAIN/g" axual-governance.values.yaml
```
The example sed command above works with bash on macOS. Use the sed syntax that matches your shell and operating system.

Install Axual Governance

helm install axual-governance oci://registry.axual.io/axual-charts/axual-governance --version 1.3.0 -f ./axual-governance.values.yaml -n axual

Axual Governance stores the credentials of the Kafka cluster you are onboarding in HashiCorp Vault. The steps below initialise it.

Create an alias for the Vault command-line interface (CLI), then initialise Vault. The later steps reuse the alias.
```
alias v='kubectl -n axual exec --stdin=true axual-governance-platform-manager-vault-0 -- '
v vault operator init -key-shares=1 -key-threshold=1
```
Keep the values for Unseal Key and Root Token in a safe place. The next steps need them.
Log in to Vault with the unseal key and root token. Replace <UNSEAL_KEY> and <ROOT_TOKEN> with the values from the previous step.
```
v vault operator unseal <UNSEAL_KEY>
v vault login <ROOT_TOKEN>
```

Prepare Vault for the platform. Run the commands below:

v vault secrets enable -path=governance kv-v2
v vault auth enable approle
echo 'path "governance/*" {capabilities = ["read","create","update","delete"]}' | v vault policy write platform-manager -
v vault write auth/approle/role/platform-manager token_policies="platform-manager"
v vault read auth/approle/role/platform-manager/role-id
v vault write -force auth/approle/role/platform-manager/secret-id

Find the role_id and secret_id in the output of the command above and store them in a safe place.

Update the platform-manager configuration in axual-governance.values.yaml to use the role_id and secret_id from the previous step. Set vault.enabled to true at the same time.

platform-manager:
  config:
    governance:
      vault:
        enabled: true
        uri: "http://axual-governance-platform-manager-vault:8200"
        path: "governance"
        roleId: "<ROLE_ID>"     # the `role_id` from the command above
        secretId: "<SECRET_ID>" # the `secret_id` from the command above

enabled must be true, or Platform Manager does not read the credentials from Vault.

Apply the changes to the axual-governance.values.yaml file.

helm upgrade --install axual-governance oci://registry.axual.io/axual-charts/axual-governance --version 1.3.0 -f ./axual-governance.values.yaml -n axual

Log in to the Self-Service interface at https://axual.<domain>;. The following screen appears:
Click Register user to register a tenant admin user. This user has administrative privileges on the platform. The following screen appears:
Register the tenant admin on your platform. Enter details for the following fields
1. First name
2. Last name
3. Email
4. Username: you will use this to log in next time
5. Password
6. Confirm password
Click Register to add the tenant admin. The following screen appears:
Add the details of your organisation and click Continue. Self-Service redirects you to the dashboard.

By completing the steps above, you have deployed Axual Governance and prepared Self-Service to log in as a tenant admin.

You can now continue with Step 3: Onboarding your own Kafka cluster.

Step 3: Onboarding your own Kafka cluster

Onboard your own Kafka cluster in Axual Governance. Self-Service can then create and configure topics on that cluster, and authorise applications against it.

This onboarding procedure supports one case only: onboarding an existing Kafka cluster for new topics and Access Control Lists (ACLs).

Only continue the onboarding when the following prerequisites are met:

There is connectivity between the Platform Manager service running in namespace axual and your Kafka cluster
The hostname and port of the Kafka cluster bootstrap server are known
The hostname and port of Apicurio Registry are known (if applicable)
Authentication details for Kafka and Apicurio Registry are known (see Kafka and Apicurio Registry authentication)

Onboarding the cluster

Self-Service does not know about your existing Kafka cluster until you register it. These steps create that record.

Log in to Self-Service using the tenant admin credentials.
Expand the menu to see all items. The following screen appears:
Click Clusters, followed by Add cluster. The following screen appears:
Fill in the following information for your cluster:
1. Name: the name you refer to the cluster by
2. Description: a description of this cluster, for example dev
3. Location: extra metadata that helps you recognise it
Select Apache Kafka as the provider.
Provide the following information:
1. Kafka bootstrap URL: the URL and port on which Platform Manager reaches the brokers
2. Publicly Trusted CA: select this when the CA of the brokers is publicly trusted, otherwise provide the CA (PEM)
3. CA (PEM): the PEM file of the CA certificate that signed the broker certificate
Choose your authentication method.
1. For TLS, provide the Certificate (PEM) and associated Private Key which Platform Manager uses to authenticate to the brokers
2. For SASL:
  1. Select the SASL mechanism (PLAIN, SCRAM_SHA_256 and SCRAM_SHA_512 are supported)
  2. Provide the Username and Password
Click Verify to check the details you entered. Continue when the verify action returns "Broker connection verified".
Leave Shared cluster as it is.
Set the SSL Authentication Mode to certificate.
Use the following patterns for multi-environment support, described in Topic, Consumer Group and Transactional ID Patterns:
1. Topic pattern: {tenant}-{instance}-{environment}-{topic}
2. Consumer Group pattern: {tenant}-{instance}-{environment}-{group}
3. Transactional ID pattern: {tenant}-{instance}-{environment}-\{transactional.id\}
Click Add cluster to save the information.

Preparing Self-Service

Topics and Applications exist in Environments, so an environment has to exist before anyone can use Self-Service. Follow the steps in Create the Instance, then Schema Registry Configuration, then Create the Environment. Use the cluster you onboarded in the previous step.

You have now concluded the first time setup of Self-Service for topic management. Before you invite anyone in the organisation to start using it, complete Step 4: Functional verification.

Step 4: Functional verification

The platform is installed and your cluster is onboarded. This step proves the two work together, by moving a message through a topic you create.

In this step you:

create a topic using the Self-Service interface
authorise an application to produce data to it
produce messages to the topic you created
verify the messages have arrived on the topic

Creating and configuring a topic

Follow Create the Topic to create a test topic named mytopic in the environment you set up.

Creating and authorising the application

Follow Create the Application to create and authorise a producer application.

When selecting the Application type, use Custom, followed by Java.

The application is ready and authorised to produce. Complete the verification by producing data on the topic.

Producing some data

The kcat command-line tool produces data to the topic.

Install kcat on your machine. See the kcat installation instructions.

Create a file named kcat.conf with the following contents:

# Bootstrap server URL and port
bootstrap.servers=bootstrap.servers.url:port
security.protocol=SSL
# For ssl.key.location and ssl.certificate.location, use the private key and certificate of the app (PEM)
# It is the same certificate you uploaded when you created and authorised the application above
ssl.key.location=clients-ca.key
ssl.certificate.location=clients-ca.crt
# For ssl.ca.location, use the certificate of the CA which signed the broker's certificate
ssl.ca.location=cluster-ca.crt

Produce some messages to the topic with the following command:
```
echo "Test message contents" | kcat -F kcat.conf -m 60 -P -t loc-test-mytopic -k "Test key"

# If you are unsure what the topic name is, list the topics
kcat -F kcat.conf -L -m 60 | grep topic
```
-m 60 raises the metadata timeout to 60 seconds, which a local cluster usually needs.

Use the topic name that matches the pattern. The example above produces a message to topic mytopic in environment test, instance loc.
A successful run prints no errors. The final verification happens in Self-Service, in the next section.

Verification

The last verification step happens in Self-Service, using Topic Browse and search.

Find the topic in Self-Service and open its detail page.
Click the Messages tab.
Click Search to accept the default search options and browse the messages on the topic. When the configuration is correct, the messages appear below the search controls.

Click a row to expand it and show the details of that message.

Conclusion and Next steps

You have now concluded the first time setup of Self-Service for topic management on Kubernetes, and you have verified the integration between Axual Governance and your Kafka cluster.

Preparing for a production-like setup

A production-like setup needs more advanced configuration of the platform. That falls outside this guide. See Install Axual Governance.

Need support?

To raise a support request for your trial, go to the Axual Support portal and select Additional, then Product trial questions.