Environment:MaterializeInc Materialize Kubernetes Helm Runtime
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Kubernetes |
| Last Updated | 2026-02-08 21:00 GMT |
Overview
Kubernetes cluster with Helm 3.x for deploying the Materialize Operator, managing Materialize instances, and running the operator Helm chart tests.
Description
This environment provides the Kubernetes runtime for deploying and managing Materialize via the Materialize Kubernetes Operator. The operator is packaged as a Helm chart (`misc/helm-charts/operator/`) and manages custom resources (`Materialize`, `Balancer`). The chart deploys the operator Deployment, ClusterRole, ClusterRoleBinding, ServiceAccount, and optionally a StorageClass. Testing uses KinD (Kubernetes in Docker) for local cluster simulation, and Helm unittest for chart validation.
Usage
Use this environment for deploying Materialize in Kubernetes, running Helm chart tests, and performing operator version upgrades. It is the mandatory prerequisite for Helm_Chart_Version_Bump and the release deployment workflow.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux or macOS | For local development with KinD |
| Kubernetes | Kubernetes 1.25+ | KinD for local, EKS/GKE/AKS for production |
| Helm | Helm 3.x | Chart uses Helm 3 API version v2 |
| Disk | 50+ GB | KinD nodes and container images |
Dependencies
System Packages
- `kubectl` (Kubernetes CLI)
- `helm` >= 3.0 (Helm chart manager)
- `kind` (Kubernetes in Docker, for local testing)
- `docker` (required by KinD)
- `helm-unittest` plugin (for Helm chart unit tests)
Helm Chart Dependencies
- No external Helm chart dependencies (self-contained)
Credentials
- `kubectl` context configured for target Kubernetes cluster
- Container registry credentials for pulling Materialize operator images
- For local testing with KinD, no external credentials required
Quick Install
# Install the operator Helm chart:
helm install materialize-operator misc/helm-charts/operator/
# Run Helm chart tests:
helm unittest misc/helm-charts/operator/
# Local KinD cluster setup:
kind create cluster --config misc/kind/cluster.yaml
Code Evidence
Helm chart version bump from `helm_chart_version_bump.py:20-108`:
# Reads Chart.yaml and values.yaml, bumps version numbers
# for the operator Helm chart during release process
KinD cluster configuration from `misc/kind/cluster.yaml`:
# Defines multi-node KinD cluster with port mappings,
# storage provisioning, and CoreDNS overrides
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `helm unittest` not found | Helm unittest plugin not installed | `helm plugin install https://github.com/helm-unittest/helm-unittest` |
| StorageClass not found | StorageClass not enabled in values | Set `storage.storageClass.create: true` in values.yaml |
| NetworkPolicy denied | NetworkPolicy restricting operator traffic | Review `networkPolicies` section in values.yaml |
Compatibility Notes
- KinD testing: Local testing uses a custom KinD configuration with CoreDNS overrides and storage provisioning.
- Chart API version: The chart uses `apiVersion: v2` (Helm 3 only).
- Storage classes: The chart can optionally create a `StorageClass` for persistent volume provisioning.