Preparations

This guide shows you how to prepare a cluster for the Axual charts: creating the namespace and the image pull Secret, and installing the Strimzi operator the Kafka brokers need.

Type

How-to guide

Goal

Get a cluster ready for the Axual Streaming and Governance charts to be installed.

Audience

Platform Operator with permission to create namespaces and Secrets, and Helm access to the cluster.

When to use

Use this guide once per installation, after the cluster-level prerequisites are in place.

The sections below cover each task in this guide:

Prerequisites
Create a namespace and Docker Registry Secret
Install Strimzi Operator with custom Axual Kafka image
Verify the preparation

Prerequisites

Confirm the following before you begin.

Access and permissions required

You need the following access and permissions:

Permission to create namespaces and Secrets in the target cluster.
Credentials for the Axual Harbor Registry, which the image pull Secret is built from.

Tools and versions required

You need the following tools:

Docker Engine v20.10.12 or newer (docker -v reports the version).
Kubernetes v1.24.0 or newer (kubectl version reports the version). Docker Desktop is a convenient way to run Kubernetes locally.
Helm v3 or newer (helm version reports the version).

Resources that must exist before starting

The following must already be in place:

An ingress controller, from Install an Ingress Controller.
On a local macOS installation, the loopback alias from How to Set Up a Local Loopback Alias. Skip this on a cluster installation.
Enough resources allocated to Docker: 4 CPUs and 8 GB of RAM as a minimum, and more depending on which components you run.

These charts support a single-cluster platform with no distribution in place. On Docker Desktop, make sure Use gRPC FUSE for file sharing is disabled.

Create a namespace and Docker Registry Secret

The streaming charts install into kafka and the governance charts into axual, so each layer needs its own namespace and its own copy of the pull Secret. The steps below create them for kafka; repeat both with axual before installing the governance layer.

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 kafka
```
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 kafka                          \
    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.

Install Strimzi Operator with custom Axual Kafka image

The Kafka brokers run under the Strimzi operator, using the custom Axual Kafka image. Install the operator before the streaming charts create any Kafka resources.

Installing the Strimzi Operator with Helm deploys Kafka and the Custom Resource Definitions (CRDs) it needs on a Kubernetes cluster.

Axual does not supply Strimzi. Replace <STRIMZI_VERSION> with a version Axual supports, which is stated per chart release in Axual Kafka README. That page is generated from the chart, so it is the version to trust when sources disagree.

Add the Strimzi repository to helm:

helm repo add strimzi https://strimzi.io/charts/

Update the repo:
```
helm repo update
```
Install the operator. A multi-tenant installation needs the custom Axual Kafka image, because it bakes in the PrincipalBuilder class that identifies a principal by its full certificate chain instead of its Distinguished Name (DN) alone. Without it, certificates issued by different tenants' Certificate Authorities can carry the same DN and get treated as the same principal. See Principal Chain Builder for the detail:
```
helm install strimzi strimzi/strimzi-kafka-operator \
  --version=<STRIMZI_VERSION> \
  --namespace kafka \
  --set kafka.image.registry=registry.axual.io \
  --set kafka.image.repository=axual/streaming/strimzi \
  --set image.imagePullSecrets='axualdockercred'
```
Without multi-tenancy support, the standard images are enough:
```
helm install strimzi strimzi/strimzi-kafka-operator \
  --namespace kafka --version=<STRIMZI_VERSION>
```

Verify the preparation

Run the three checks below before installing any Axual chart. They cover the kafka namespace; repeat the first two against axual.

Confirm the namespace exists:
```
kubectl get namespace kafka
```
Expected result: the namespace is listed with status Active. A NotFound error means the create step ran against a different cluster or context.
Confirm the image pull Secret exists in that namespace:
```
kubectl get secret axualdockercred --namespace kafka
```
Expected result: the Secret is listed with type kubernetes.io/dockerconfigjson. A NotFound error means it was created in another namespace, which surfaces later as ImagePullBackOff on the first Axual pod.
Confirm the Strimzi operator is installed and its CRDs are registered:
```
helm list --namespace kafka
kubectl get crd kafkas.kafka.strimzi.io
```
Expected result: the strimzi release is listed with status deployed, and the kafkas.kafka.strimzi.io CRD exists. Without that CRD the streaming charts cannot create a Kafka cluster.