Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

WEKA Operator full deployment workflow

Deploy WEKA on Kubernetes end-to-end: from environment preparation and operator installation through resource provisioning and post-deployment storage configuration.

Workflow

Step
Task
Description

1

Obtain setup information

Collect registry credentials and version tags.

2

Prepare Kubernetes environment

Configure control plane readiness, HugePages, Kubelet settings, image pull secrets, and failure domains.

3

Install the WEKA Operator

Deploy the operator and set the required drive type configuration.

4

Manage driver distribution

Select external or local driver distribution and apply the required policy.

5

Discover and sign drives

Detect available drives and apply the required signing policy.

6

Provision WEKA resources

Deploy the WekaCluster, create the optional client secret, and install the WekaClient when needed.

7

Manage the WEKA cluster management proxy

Optionally expose WEKA management endpoints through an operator-managed Service and Ingress.

8

Assign network space proxy subnets

Assign unique proxy subnets when multiple WEKA clusters share the same Kubernetes environment.

9

Perform post-deployment storage configuration on WEKA client

Configure CSI behavior and storage provisioning for WEKA clients.

1. Obtain setup information

Identify and record the credentials required to pull WEKA container images and the specific version tags for your deployment.

Before you begin

Contact the WEKA Customer Success Team to receive your authorized registry credentials.

Procedure

  1. Access WEKA Operator page to identify the latest WEKA_OPERATOR_VERSION and WEKA_IMAGE_VERSION_TAG.

  2. Record the following credentials for your image pull secret:

    • Registry: quay.io

    • QUAY_USERNAME

    • QUAY_PASSWORD

    • QUAY_SECRET_KEY: Typically quay-io-robot-secret.

Replace all placeholders in your setup files with these values before proceeding.

Example: WEKA Operator page on get.weka.io

2. Prepare Kubernetes environment

Ensure the infrastructure meets the performance and resiliency requirements of the WEKA data plane. This step covers control plane configuration, node hardware and software requirements, HugePages, port requirements, and Kubelet CPU policy.

Control plane high availability

Configure the Kubernetes control plane for high availability to match WEKA resiliency. High availability depends on etcd quorum.

  • Quorum rule: etcd requires an odd number of members (N) and tolerates failures up to (N-1)/2 failures.

  • Recommendation: Use five or nine etcd members for production storage backends.

Consider using an external etcd cluster or distributing control plane components across multiple failure domains. For more information, see the Kubernetes HA topology guidance.

Node hardware and software requirements

Verify that every node in the cluster meets these specifications:

  • Kubernetes version: 1.25 or later (OpenShift 4.17 or later).

  • Storage allocation: Reserve approximately 20 GiB per WEKA container plus 10 GiB per allocated CPU core in /opt/k8s-weka. Do not use NFS or network-attached storage.

  • Kernel headers: Ensure kernel headers exactly match the running kernel version to allow driver compilation.

Configure HugePages for Kubernetes worker nodes

WEKA processes require dedicated HugePages memory. Configure HugePages on every worker node before deploying the WekaCluster. Nodes without HugePages configured will fail to schedule WEKA pods.

Memory allocation requirements

Use the following formula to calculate the required number of 2 MiB HugePages for your server:

Variables:

Variable
Description

Server capacity

Total usable capacity of all drives assigned to WEKA on the server, measured in GiB.

Ratio

Controls the metadata memory component in the HugePages calculation. Server capacity is divided by this value, so a higher ratio allocates less memory to metadata, which reduces total HugePages consumption. The default is 1000. Set to 2000 to lower HugePages usage on servers where reduced metadata allocation is acceptable.

Cores for WEKA

Number of CPU cores allocated to the WEKA container on the server.

WEKA Container factor

Fixed HugePages allocation of 1.7 GiB for each WEKA container.

Headroom

Additional 10% buffer, expressed as 1.1, to account for memory fragmentation and operational variance. If you plan to run additional workloads that require HugePages, add their planned requirements on top of the calculated value.

Example calculation

Server specifications:

  • CPU cores: 64 total; 63 dedicated to WEKA.

  • Storage: 16 drives × 15.3 TiB = 244.8 TiB usable (250,675 GiB).

Step 1: Calculate total GiB:

Step 2: Convert to MiB:

Step 3: Calculate HugePages:

Apply HugePages settings

Before you begin:

  • Identify the number of drives and CPU cores allocated to WEKA on the server.

  • Ensure you have root or sudo permissions on the worker nodes.

Procedure:

  1. Check the current HugePages status on the server:

  2. Apply the calculated HugePages value. Replace <calculated-value> with the value computed for your server:

  3. Persist the setting to ensure it remains active after a reboot:

Kubernetes port requirements

The WEKA Operator automatically allocates ports to prevent collisions in multi-cluster environments. Manual configuration is typically unnecessary unless specific infrastructure or policy requirements apply.

Component
Default start port
Port range size

WEKA Operator (v1.10+) / WEKA (v5.1.0+)

35000

260 ports per cluster

WEKA Operator / WEKA (previous versions)

35000

500 ports per cluster

WEKA client connectivity

45000

Maximum: 65535

Reserve ports on each node

To prevent the Linux kernel from assigning WEKA ports to other processes, add the following to /etc/sysctl.d/99-weka.conf on every node. For example:

The range 35000–37600 covers 2,600 ports, which supports up to 10 WekaCluster instances at 260 ports each. If you plan to deploy more than 10 clusters, extend the upper bound by 260 ports per additional cluster.

For full kernel parameter configuration, see Set custom kernel parameters.

Configure Kubelet requirements

Enable the static CPU Manager policy on all worker nodes to give WEKA processes dedicated CPU cores. Without this, the Kubernetes scheduler can place other workloads on the same cores, causing contention and reducing I/O throughput.

On Kubernetes v1.32 and later, also enable strict-cpu-reservation to prevent Burstable and Best Effort pods from scheduling onto reserved cores.

For the full rationale, sibling-pair guidance, and version-specific reservation details, see WEKA Operator best practices.

Before you begin: identify HyperThreading sibling cores

On hyperthreaded systems, each physical core exposes two logical CPUs. Include both logical CPUs from the same physical core in reservedSystemCPUs to ensure full isolation. Reserving only one sibling of a physical core leaves that core shared.

Run the following commands to identify sibling pairs on the node:

Example output for a 12-logical-CPU, single-socket server with HyperThreading enabled:

In this example, there are 6 physical cores and 12 logical CPUs. CPUs that share the same CORE and SOCKET values are HyperThreading siblings:

Physical core
Logical CPU (thread 0)
Logical CPU (thread 1, HT sibling)

0

0

6

1

1

7

2

2

8

3

3

9

4

4

10

5

5

11

The thread_siblings_list confirms these pairs directly:

Do not treat CPUs on different sockets with the same core index as siblings. Always verify pairs using thread_siblings_list rather than relying on the CORE column alone.

Procedure

  1. Edit the Kubelet configuration file on each worker node and add the following settings. In this example, physical core 0 is reserved for the OS. reservedSystemCPUs includes both logical CPUs of that core (CPU 0 and its HT sibling, CPU 6):

Adjust reservedSystemCPUs to match the sibling pairs reported by thread_siblings_list on your node. Reserve at least one physical CPU (two sibling cores) for the Kubelet. Reserve additional physical cores, including both logical CPUs for each core, when OS or platform workloads require more capacity.

Kubelet configuration methods vary by Kubernetes distribution. Some environments manage KubeletConfiguration centrally, while others require per-node file or bootstrap changes. Treat this example as the target Kubelet state and apply the equivalent settings by using the method your platform supports on every worker node that hosts WEKA processes.

CPUManagerPolicyAlphaOptions and strict-cpu-reservation require Kubernetes v1.32 or later. Omit the featureGates and cpuManagerPolicyOptions blocks on earlier versions. Without strict reservation, Burstable and Best Effort pods can schedule onto reserved cores under load, reducing WEKA I/O throughput.

  1. Save the file and restart the Kubelet:

Related information

Control CPU Management Policies on the Node

Configure image pull secrets

Set up Kubernetes secrets to enable secure image pulling from the WEKA container registry. These secrets must exist in every namespace where WEKA resources are deployed.

Before you begin

Identify your QUAY_USERNAME, QUAY_PASSWORD, and QUAY_SECRET_KEY from step 1.

Procedure

  1. Define the target namespaces and ensure they do not overlap to prevent configuration conflicts.

  2. Create the secret in the weka-operator-system namespace. Repeat the same step in every namespace where you plan to create a WEKA CR. For example, if you deploy WEKA resources in the default namespace, create the secret there as well:

Configure failure domains

Group backend nodes into failure domains to ensure high availability and data protection. A failure domain represents a set of processes that share a common physical risk, such as a rack, power circuit, or network switch.

The system distributes data and parity blocks from the same stripe across different failure domains. If an entire failure domain fails, the cluster reconstructs the missing data from the remaining domains.

Select a failure domain mode

Mode
Function
Usage

Implicit (default)

Assigns every process as its own independent failure domain.

Deployments where infrastructure shared risks cannot be identified by Kubernetes node labels.

Explicit

Groups processes into named domains based on physical node labels.

Deployments where containers share a rack, switch, or power source.

Prefer explicit mode when Kubernetes node labels can represent shared infrastructure boundaries. Explicit mode provides better failure protection by separating processes across known physical domains such as racks, power feeds, or switches. To use it, ensure the required topology labels are present on the nodes.

Determine stripe width and domain count

Coordinate the number of failure domains with the stripe width and protection level during cluster formation. Stripe width and protection levels are permanent once set.

Constraint to prevent data loss: blocks lost during a failure domain failure = stripe width / number of failure domains. This value must not exceed the parity block count (P).

Minimum healthy server requirements:

Stripe configuration
Minimum healthy server

5+2

4

16+ 2

9

5+4

3

16+4

5

Map a single node label

  1. Label every backend node with a physical grouping value:

  2. Configure the failureDomain field in the WekaCluster CR:

    • label: The node label key identifying the failure domain.

    • skew: The permitted difference in container count between domains.

Use composite topology labels

Combine existing Kubernetes topology labels, such as zone and rack, into a compound failure domain identity.

Procedure

  1. Identify the existing labels on your nodes:

  2. Add the compositeLabels list to the WekaCluster CR:

    The operator combines these values. For example, a node in zone us-east-1a on rack-1 becomes failure domain us-east-1a/rack-1.

Verify the configuration

Confirm the distribution of containers across the defined domains.

Procedure

  1. Apply the CR changes:

  2. Check the container status:

  3. Verify that the FAILURE DOMAIN column displays your custom label values instead of AUTO.

3. Install the WEKA Operator

Manage the lifecycle of WEKA resources by installing the WEKA Operator. This process involves applying Custom Resource Definitions (CRDs) and deploying the operator controller with specific configurations for the Container Storage Interface (CSI) and drive types.

Before you begin

  • Ensure the QUAY_SECRET_KEY is created in the weka-operator-system namespace (completed in step 2).

  • Install Helm on a local server, unless using a higher-level deployment tool such as Argo CD:

  • Confirm kubectl is installed and configured against the target cluster.

  • Identify your deployment configuration before running the Helm command:

    Condition
    Required flag

    Operator v1.7.0 and later

    --set csi.installationEnabled=true

    Operator v1.10 and later with AlloyFlash

    --set driveSharing.driveTypesRatio='{tlc: 9, qlc: 1}'

    Operator v1.10 and later with single drive type

    --set driveSharing.driveTypesRatio='{qlc: 0}'

Procedure

  1. Download and apply the CRDs so the Kubernetes API can recognize WEKA resources. Replace <WEKA_OPERATOR_VERSION> with your version:

  1. Deploy the WEKA Operator using the Helm flags that match your configuration. The following examples show the two most common layouts:

Mixed flash configuration (AlloyFlashTM):

This setting allocates 9/10 capacity to TLC and 1/10 to QLC.

Single drive type:

This setting configures a single drive type and disables Hybrid Flash.

  1. Verify the installation. The weka-operator-controller-manager pod must show Running status:

Expected output:

If the pod does not reach Running state, see Troubleshoot WEKA Operator deployments.

4. Manage driver distribution

If outbound access to drivers.weka.io is available, use the pre-built driver service. Configure driver distribution only when you need a local build and distribution path for client and backend processes.

Choose a distribution method

Condition
Method

Standard Linux distribution with supported kernel, outbound access to drivers.weka.io

Pre-built drivers (recommended): No build infrastructure required. By default, the drivers are pulled from https://drivers.weka.io.

Air-gapped environment, custom or patched kernel, or no external network access

Local driver builder: Configure driver distribution policy.

For architectural details on how driver distribution works, see WEKA Operator driver management.

Before you begin

  • Ensure a WEKA-compatible image (weka-in-container) and a valid imagePullSecret are accessible.

  • Confirm that builder container versions match the target WEKA version.

  • For local distribution: ensure kernel headers matching the running kernel are installed on the build server. On Ubuntu, install linux-headers-$(uname -r). On Rocky Linux, install kernel-devel-$(uname -r) and kernel-headers-$(uname -r). Also confirm port 60002 is open for communication between the operator, Drivers-Builder, Drivers-Dist, and Drivers-Loader.

Local driver distribution components

When using a local builder, the operator deploys three components:

  • Drivers-Builder: Compiles the kernel module for specific WEKA and kernel version combinations.

  • Drivers-Dist: An internal HTTP server that stores and serves compiled driver packages.

  • Service: A Kubernetes Service that exposes Drivers-Dist at a stable internal endpoint.

When configuring driver distribution manually, the following elements must be preserved exactly as shown in the configuration examples: ports, network modes, core configurations, and spec.name.

Procedure

  1. Define node selection using a nodeSelector to identify target Kubernetes nodes that require the driver.

  2. Apply a WekaPolicy to deploy the driver distribution service. Use the example that matches your environment:

Example 1: Minimal policy (recommended for most deployments)
Example 2: Manual deployment of distribution and builder containers

Use this example only when direct resource control is required instead of a WekaPolicy:

On Rocky Linux, replace the preRunScript value with dnf install -y gcc.

Example 3: WekaPolicy with proactive driver pre-building

Use this example when you need to pre-build drivers for specific images beyond those detected from existing WekaCluster and WekaClient resources:

Ubuntu

Rocky Linux

  1. Install a compiler in the builder container.

    1. The driver builder compiles kernel modules in the builder container. Install a compiler that matches the node kernel requirements.

    2. Add builderPreRunScript to the WekaPolicy specification:

For RPM-based builder images (for example, Rocky Linux):

  • Ubuntu 22.04 with kernel 6.5 or later requires gcc-12.

  • Ubuntu 24.04 typically requires gcc-13.

  • Alternatively, install gcc and kernel headers with apt-get install -y gcc linux-headers-$(uname -r).

WekaPolicy additional attributes

Review the WekaPolicy API reference for all available resource options.

Attribute
Description

image

The WEKA container image used for the distributor and default builder.

interval

How often the operator reconciles the policy. Default: 1m.

builderPreRunScript

Optional script to run before the build, for example to install a compiler.

ensureNICsPayload

Defines the configuration for ensuring a specific number of data NICs on selected nodes.

signDrivesPayload

Configures parameters to scan and sign drives for WEKA backend containers.

  1. Apply the configuration:

5. Discover and sign drives

Identify and prepare physical storage devices before provisioning the WEKA cluster.

How drive discovery works

When a drive discovery operation runs, the operator performs three actions on each node:

  • Annotates the node with a list of known serial IDs for all accessible drives.

  • Creates the extended resource weka.io/drives on the node to indicate the count of ready drives.

  • Marks only healthy, unblocked drives as available. Drives with errors or manual blocks are excluded.

Choose a discovery method

Method
Use case

WekaManualOperation

One-time action for initial manual provisioning.

WekaPolicy

Automated periodic discovery. Initiates immediately when it detects node updates or hardware additions. Recommended for production.

Understand the shared field

The shared field in the signDrivesPayload controls whether SSD Proxy is enabled on the signed drives.

Whole drives are assigned directly to WEKA processes. This is the simpler configuration and suits deployments where clusters are large enough to use full drives.

Consider false when:

  • You intend to assign complete drives to one or more WekaCluster CRs.

  • Your clusters are consistently active and you want to avoid sharing drive workload across tenants.

Running multiple WekaCluster CRs on the same hardware does not require drive sharing. With 6 drives available, you can assign each drive to a separate WekaCluster without enabling shared.

Enables SSD Proxy, which introduces a layer between WEKA processes and the physical drives. This enables two capabilities:

  • Drive slicing: A single physical drive can be divided into logical slices, each used by a different WekaCluster. This is useful when clusters are smaller and do not need full drives.

  • Higher aggregate throughput: When clusters are not all fully loaded at the same time, drive sharing increases the number of drives used in parallel, which can improve overall performance. If clusters are consistently active simultaneously, drive workload is shared across tenants.

SSD Proxy enables allocating multiple CPU cores per physical drive.

For details on SSD Proxy operation and resource requirements,, see Drive sharing.

Procedure

Review the WekaPolicy API reference for all available resource options.

  1. Define drive sharing and signing: Apply a WekaPolicy to sign compatible drives.

Name
Description

all-not-root

Signs all detected block devices except the root device.

aws-all

Detects NVMe devices using AWS PCI identifiers.

device-paths

Targets specific device paths listed in the manifest.

6. Provision WEKA resources

Deploy the WekaCluster and WekaClient Custom Resources to provision the backend storage and connect your Kubernetes nodes.

Run cluster-level WEKA CLI commands from Compute or Drive pods only. Do not run WEKA CLI commands inside WekaClient pods or application client pods.

Perform these steps in sequence:

  1. Install the WekaCluster CR.

  2. Create the WEKA cluster client secret (only required if WekaCluster and WekaClient are not deployed on the same Kubernetes cluster)

  3. Install the WekaClient CR.

6.1. Install the WekaCluster CR

Provision the WEKA cluster backend using the WekaCluster CR. This resource defines the storage containers, drive configurations, and networking for the cluster.

Review the WekaCluster API reference for all available resource options.

Before you begin

  • Verify that drives are signed and discovered (step 5).

  • Verify the driver distribution service is accessible. WEKA recommends the external service at https://drivers.weka.io.

  • If you set shared: true when signing drives, select a sizing method for the dynamic template:

    • clusterCapacity: Sets the target usable capacity for the whole cluster. The operator derives the container and drive layout automatically.

    • containerCapacity: Sets the capacity per drive container. Required when shared: true is set and clusterCapacity is not set.

    • numDrives: Assigns whole drives per drive container. Applies when shared: false is set. Optional, defaults to 1.

Procedure

  1. Create weka-cluster.yaml:

Example: weka-cluster.yaml

  1. If your cluster requires settings that cannot be applied through standard configuration, for example overriding the default bucket count on a small or non-standard cluster, set spec.overrides.postFormClusterScript in the manifest before applying it. The operator runs this script once, after the cluster forms and before start-io. Use it only when no standard configuration option achieves the required result:

Example: postFormClusterScript override

To inspect the field definition, run:

postFormClusterScript runs privileged debug commands on a cluster that is not yet serving I/O. Validate the script on a non-production cluster before applying it to production.

  1. Apply the manifest:

Related information

WekaClusterSpec

6.2. Create the WEKA cluster client secret

Create a Kubernetes Secret that stores the credentials WekaClient uses to join the WEKA cluster. This is required only when WekaClient and WekaCluster are not deployed in the same Kubernetes cluster.

Before you begin

Obtain the org, join-secret, password, and username from your WEKA backend.

Procedure

  1. Encode each credential value to base64.

  1. Create secret.yaml:

Example: secret.yaml

  1. Apply the secret:

6.3. Install the WekaClient CR

If you need WEKA clients on Kubernetes, deploy the WekaClient CR on the designated Kubernetes nodes. WekaClient works like a DaemonSet and provisions one pod per selected node to provide a persistent WEKA data plane for your workloads.

Review the WekaClient API reference for all available resource options.

Before you begin

  • Label every worker node intended to host WEKA client pods:

Example:

Ensure the label matches the nodeSelector property in the WekaClient CR.

  • Verify that the Kubernetes Secret (for example, weka-cluster-dev) exists in the weka-operator-system namespace and contains base64-encoded cluster credentials (org, join-secret, password, and username).

  • Identify whether you are using the external driver distribution service (https://drivers.weka.io) or a local service endpoint.

Procedure

  1. Create weka-client.yaml using the connection type that matches your environment:

Example: Internal cluster connection (WekaCluster and WekaClient in the same Kubernetes cluster)
Example: External cluster connection (WEKA cluster running outside Kubernetes)

  1. Apply the manifest.

WekaClient parameters reference

For the full list of configurable fields, see WekaClient parameters.

Name
Description
Default

image

The WEKA container image version to deploy.

—

imagePullSecret

Secret name used to authenticate with the image registry.

—

port

Defines a range of 100 ports for the container.

Dynamic

agentPort

Specifies a single port used by the agent process.

Dynamic

portRange

Defines a basePort for automatic port allocation.

—

nodeSelector

Selects the nodes where WEKA containers are scheduled.

—

network

Network configuration map. Sub-keys: ethDevice (single device), ethDevices (multiple devices), and udpMode (true/false). Defaults to UDP mode when not set.

UDP

driversDistService

URL for the driver distribution service.

—

targetCluster

Name and namespace of the WekaCluster CR to connect to. Applies when the WekaCluster runs in the same Kubernetes cluster.

—

joinIpPorts

IP addresses used to join a cluster outside the local environment.

—

wekaSecretRef

Reference to the Kubernetes Secret containing cluster credentials.

—

coresNum

Number of physical CPU cores to allocate to each container.

1

cpuPolicy

Defines core allocation behavior: auto, manual, shared, dedicated or dedicated_ht

auto

upgradePolicy

Sets the upgrade strategy: rolling, manual, or all-at-once.

rolling

gracefulDestroyDuration

Pause duration for local data and drive allocations during pod deletion.

24h

7. Manage the WEKA cluster management proxy

Optionally - access WEKA management endpoints through an operator-managed Service, and optionally expose them outside the Kubernetes cluster using a Kubernetes Ingress.

Required infrastructure

WEKA does not install or configure the following components. These remain the responsibility of the platform administrator:

Component
Purpose

Ingress controller

Manages incoming traffic, for example NGINX or Traefik.

External connectivity

A load balancer or equivalent mechanism to route traffic from outside the cluster.

DNS resolution

Configured hostnames that resolve to the Ingress controller's external IP.

TLS termination

Optional platform-managed certificate management for secure HTTPS communication.

Ingress configuration

WEKA simplifies basic setups by managing Ingress configuration through a single ingressClass setting. For advanced or customized networking scenarios, wrap or modify the service using standard Kubernetes Ingress resources.

8. Assign network space proxy subnets for multiple WEKA clusters

Optionally, allocate a unique proxy subnet to each WEKA cluster when you deploy more than one WekaCluster on the same Kubernetes environment. Each WEKA cluster uses an internal proxy subnet for its network space. When two clusters share the same subnet, their address ranges overlap and cause routing conflicts.

Assign a non-overlapping subnet to every WEKA cluster so that each cluster keeps a dedicated address range and isolates its traffic from other tenants on the same Kubernetes nodes.

Before you begin

  • Deploy the WEKA Operator on the target Kubernetes environment.

  • Identify every WEKA cluster already deployed on the same Kubernetes environment.

Important: Assign a unique proxy subnet to each WEKA cluster on the same Kubernetes environment. This prevents overlapping address ranges and routing conflicts when you deploy additional clusters.

Procedure

  1. Record the proxy subnets already assigned to the existing WEKA clusters:

  2. For each new WEKA cluster, choose a subnet in CIDR notation that no other WEKA cluster on the same Kubernetes environment uses.

  3. Assign the subnet to the WEKA cluster:

  4. Confirm the assignment by listing the proxy subnets again and verifying that each WEKA cluster holds a distinct range:

9. Perform post-deployment storage configuration on WEKA client

If your deployment includes a WEKA client on Kubernetes and embedded CSI is enabled, configure the CSI plugin and storage classes based on your operator version to enable persistent volume provisioning.

Operator version
Behavior
Required action

v1.7.0 and later

Embedded CSI is supported. When embedded CSI is enabled during operator installation, the operator configures the CSI plugin and StorageClass automatically.

Proceed to create a Persistent Volume Claim (PVC). See Dynamic and static provisioning.

v1.6.2 and earlier

Embedded CSI is not available. CSI requires manual installation.

See WEKA CSI Plugin.

For v1.7.0 and later, when embedded CSI installation is enabled, the operator creates storage classes following the pattern weka-<groupName>-<fsName>. To disable automatic storage class creation, set csi.storageClassCreationDisabled: true in your Helm values.

PreviousQuick installationNextDeploy WEKA on cloud-managed Kubernetes services

Last updated