Materialize Kubernetes Operator Helm Chart

Materialize Kubernetes Operator Helm Chart

This Helm chart deploys the Materialize operator on a Kubernetes cluster. The operator manages Materialize environments within your Kubernetes infrastructure.

Prerequisites

• Kubernetes 1.29+
• Helm 3.2.0+

Kubernetes Storage Configuration

Materialize requires fast, locally-attached NVMe storage for optimal performance. Network-attached storage (like EBS volumes) is not supported.

We recommend using OpenEBS with LVM Local PV for managing local volumes. While other storage solutions may work, we have tested and recommend OpenEBS for optimal performance.

Installing OpenEBS

# Install OpenEBS operator
helm repo add openebs https://openebs.github.io/openebs
helm repo update

# Install only the Local PV Storage Engines
helm install openebs --namespace openebs openebs/openebs \
  --set engines.replicated.mayastor.enabled=false \
  --create-namespace

Verify the installation:

kubectl get pods -n openebs -l role=openebs-lvm

LVM Configuration

LVM setup varies by environment. Below is our tested and recommended configuration:

AWS EC2 with Bottlerocket AMI

Tested configurations:

• Instance types: r6g, r7g families
• AMI: AWS Bottlerocket
• Instance store volumes required

Setup process:

1. Use Bottlerocket bootstrap container for LVM configuration
2. Configure volume group name as instance-store-vg

Note: While LVM setup may work on other instance types with local storage (like i3.xlarge, i4i.xlarge, r5d.xlarge), we have not extensively tested these configurations.

Storage Configuration

Once LVM is configured, set up the storage class (for example in misc/helm-charts/operator/values.yaml):

storage:
  storageClass:
    create: true
    name: "openebs-lvm-instance-store-ext4"
    provisioner: "local.csi.openebs.io"
    parameters:
      storage: "lvm"
      fsType: "ext4"
      volgroup: "instance-store-vg"

While OpenEBS is our recommended solution, you can use any storage provisioner that meets your performance requirements by overriding the provisioner and parameters values.

For example, to use a different storage provider:

storage:
  storageClass:
    create: true
    name: "your-storage-class"
    provisioner: "your.storage.provisioner"
    parameters:
      # Parameters specific to your chosen storage provisioner

Installing the Chart

To install the chart with the release name my-materialize-operator:

helm install my-materialize-operator misc/helm-charts/operator --namespace materialize --create-namespace

This command deploys the Materialize operator on the Kubernetes cluster with default configuration. The Parameters section lists the parameters that can be configured during installation.

Uninstalling the Chart

To uninstall/delete the my-materialize-operator deployment:

helm delete my-materialize-operator

This command removes all the Kubernetes components associated with the chart and deletes the release.

Parameters

The following table lists the configurable parameters of the Materialize operator chart and their default values.

Specify each parameter using the --set key=value[,key=value] argument to helm install. For example:

helm install my-materialize-operator \
  --set operator.image.tag=v26.18.0-dev.0 \
  materialize/materialize-operator

Alternatively, a YAML file that specifies the values for the parameters can be provided while installing the chart. For example:

helm install my-materialize-operator -f values.yaml materialize/materialize-operator

Deploying Materialize Environments

To deploy a Materialize environment, create a Materialize custom resource definition with the desired configuration.

apiVersion: v1
kind: Namespace
metadata:
  name: materialize-environment
---
apiVersion: v1
kind: Secret
metadata:
  name: materialize-backend
  namespace: materialize-environment
stringData:
  metadata_backend_url: "postgres://materialize_user:[email protected]:5432/materialize_db?sslmode=disable"
  persist_backend_url: "s3://minio:minio123@bucket/12345678-1234-1234-1234-123456789012?endpoint=http%3A%2F%2Fminio.materialize.svc.cluster.local%3A9000&region=minio"
---
apiVersion: materialize.cloud/v1alpha1
kind: Materialize
metadata:
  name: 12345678-1234-1234-1234-123456789012
  namespace: materialize-environment
spec:
  environmentdImageRef: materialize/environmentd:v26.18.0-dev.0
  backendSecretName: materialize-backend
  environmentdResourceRequirements:
    limits:
      memory: 16Gi
    requests:
      cpu: "2"
      memory: 16Gi
  balancerdResourceRequirements:
    limits:
      memory: 256Mi
    requests:
      cpu: 100m
      memory: 256Mi

Configuration and Installation Details

RBAC Configuration

The chart creates a ClusterRole and ClusterRoleBinding by default. To use an existing ClusterRole, set rbac.create=false and specify the name of the existing ClusterRole using the rbac.clusterRole parameter.

Observability

To enable observability features, set observability.enabled=true. This will create the necessary resources for monitoring the operator. If you want to use Prometheus, also set observability.prometheus.enabled=true.

Network Policies

Network policies can be enabled by setting networkPolicies.enabled=true. By default, the chart uses native Kubernetes network policies. To use Cilium network policies instead, set networkPolicies.useNativeKubernetesPolicy=false.

Troubleshooting

If you encounter issues with the Materialize operator, check the operator logs:

kubectl logs -l app.kubernetes.io/name=materialize-operator -n materialize

For more detailed information on using and troubleshooting the Materialize operator, refer to the Materialize documentation.

Upgrading

Once you have the Materialize operator installed and managing your Materialize instances, you can upgrade both components. While the operator and instances can be upgraded independently, you should ensure version compatibility between them. The operator can typically manage instances within a certain version range - upgrading the operator too far ahead of your instances may cause compatibility issues.

We recommend:

• Upgrade the operator first
• Always upgrade your Materialize instances after upgrading the operator to ensure compatibility

Upgrading the Helm Chart

To upgrade the Materialize operator to a new version:

helm upgrade my-materialize-operator materialize/misc/helm-charts/operator

If you have custom values, make sure to include your values file:

helm upgrade my-materialize-operator materialize/misc/helm-charts/operator -f my-values.yaml

Upgrading Materialize Instances

To upgrade your Materialize instances, you'll need to update the Materialize custom resource and trigger a rollout.

By default, the operator performs rolling upgrades (rolloutStrategy: WaitUntilReady) which minimizes downtime but require additional Kubernetes cluster resources during the transition.

For environments without enough capacity to perform the WaitUntilReady strategy, and where downtime is acceptable, there is the ImmediatelyPromoteCausingDowntime strategy. This strategy will cause downtime and is not recommended. If you think you need this, please reach out to Materialize engineering to discuss your situation.

Determining the Version

The compatible version for your Materialize instances is specified in the Helm chart's appVersion. For the installed chart version, you can run:

helm list -n materialize

Or check the Chart.yaml file in the misc/helm-charts/operator directory:

apiVersion: v2
name: materialize-operator
# ...
version: v26.0.0-dev.0
appVersion: v0.147.0  # Use this version for your Materialize instances

Use the appVersion (v0.147.0 in this case) when updating your Materialize instances to ensure compatibility.

Using kubectl patch

For standard upgrades such as image updates:

# For version updates, first update the image reference
kubectl patch materialize <instance-name> \
  -n <materialize-instance-namespace> \
  --type='merge' \
  -p "{\"spec\": {\"environmentdImageRef\": \"materialize/environmentd:v0.147.0\"}}"

# Then trigger the rollout with a new UUID
kubectl patch materialize <instance-name> \
  -n <materialize-instance-namespace> \
  --type='merge' \
  -p "{\"spec\": {\"requestRollout\": \"$(uuidgen)\"}}"

You can combine both operations in a single command if preferred:

kubectl patch materialize 12345678-1234-1234-1234-123456789012 \
  -n materialize-environment \
  --type='merge' \
  -p "{\"spec\": {\"environmentdImageRef\": \"materialize/environmentd:v0.147.0\", \"requestRollout\": \"$(uuidgen)\"}}"

Using YAML Definition

Alternatively, you can update your Materialize custom resource definition directly:

apiVersion: materialize.cloud/v1alpha1
kind: Materialize
metadata:
  name: 12345678-1234-1234-1234-123456789012
  namespace: materialize-environment
spec:
  environmentdImageRef: materialize/environmentd:v0.147.0 # Update version as needed
  requestRollout: 22222222-2222-2222-2222-222222222222    # Generate new UUID
  forceRollout: 33333333-3333-3333-3333-333333333333      # Optional: for forced rollouts
  backendSecretName: materialize-backend

Apply the updated definition:

kubectl apply -f materialize.yaml

Forced Rollouts

If you need to force a rollout even when there are no changes to the instance:

kubectl patch materialize <instance-name> \
  -n materialize-environment \
  --type='merge' \
  -p "{\"spec\": {\"requestRollout\": \"$(uuidgen)\", \"forceRollout\": \"$(uuidgen)\"}}"

Verifying the Upgrade

After initiating the rollout, you can monitor the status:

# Watch the status of your Materialize environment
kubectl get materialize -n materialize-environment -w

# Check the logs of the operator
kubectl logs -l app.kubernetes.io/name=materialize-operator -n materialize

Notes on Rollouts

• requestRollout triggers a rollout only if there are actual changes to the instance (like image updates)
• forceRollout triggers a rollout regardless of whether there are changes, which can be useful for debugging or when you need to force a rollout for other reasons
• Both fields expect UUID values and each rollout requires a new, unique UUID value

Operational Guidelines

Beyond the Helm configuration, there are other important knobs to tune to get the best out of Materialize within a Kubernetes environment.

Instance Types

Materialize has been vetted to work on instances with the following properties:

• ARM-based CPU
• 1:8 ratio of vCPU to GiB memory
• 1:16 ratio of vCPU to GiB local instance storage (if enabling spill-to-disk)

When operating in AWS, we recommend using the r7gd and r6gd families of instances (and r8gd once available) when running with local disk, and the r8g, r7g, and r6g families when running without local disk.

Learn More

• Materialize Documentation
• Materialize GitHub Repository

Autogenerated from chart metadata using helm-docs v1.14.2