# Self-Managed Deployments Learn about the key components and architecture of self-managed Materialize deployments. ## Overview Whereas Materialize Cloud gives you a fully managed service for Materialize, Self-Managed Materialize allows you to deploy Materialize in your own infrastructure. Self-Managed Materialize deployments on Kubernetes consist of several layers of components that work together to provide a fully functional database environment. Understanding these components and how they interact is essential for deploying, managing, and troubleshooting your Self-Managed Materialize. This page provides an overview of the core architectural components in a Self-Managed deployment, from the infrastructure level (Helm chart) down to the application level (clusters and replicas). ## Architecture layers A Self-Managed Materialize deployment is organized into the following layers: Layer | Component | Description ------|-----------|------------ **Infrastructure** | [Helm Chart](#helm-chart) | Package manager component that bootstraps the Kubernetes deployment **Orchestration** | [Materialize Operator](#materialize-operator) | Kubernetes operator that manages Materialize instances **Database** | [Materialize Instance](#materialize-instance) | The Materialize database instance itself **Compute** | [Clusters and Replicas](#clusters-and-replicas) | Isolated compute resources for workloads ## Helm chart The Helm chart is the entry point for deploying Materialize in a self-managed Kubernetes environment. It serves as a package manager component that defines and deploys the Materialize Operator. ### Working with the Helm chart You interact with the Helm chart through standard Helm commands. For example: - To add the Materialize Helm chart repository: ```bash helm repo add materialize https://materializeinc.github.io/materialize ``` - To update the repository index: ```bash helm repo update materialize ``` - To install the Materialize Helm chart and deploy the Materialize Operator and other resources: ```bash helm install materialize materialize/materialize-operator ``` - To upgrade the the Materialize Helm chart (and the Materialize Operator and other resources): ```bash helm upgrade materialize materialize/materialize-operator ``` - To uninstall the Helm chart (and the Materialize Operator and other resources): ```bash helm uninstall materialize ``` ### What gets installed ```bash helm install materialize materialize/materialize-operator ``` When you install the the Materialize Helm Chart, it: - Deploys the **Materialize Operator** as a Kubernetes deployment. - Creates necessary cluster-wide resources (CRDs, RBAC roles, service accounts). - Configures operator settings and permissions. Once installed, the **Materialize Operator** handles the deployment and management of Materialize instances. ## Materialize Operator The Materialize Operator (implemented as `orchestratord`) is a Kubernetes operator that automates the deployment and lifecycle management of Materialize instances. It implements the [Kubernetes operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) to extend Kubernetes with domain-specific knowledge about Materialize. ### Managed resources The operator watches for Materialize custom resources and creates/manages all the Kubernetes resources required to run a Materialize instance, including: - **Namespaces**: Isolated Kubernetes namespaces for each instance - **Services**: Network services for connecting to Materialize - **Network Policies**: Network isolation and security rules - **Certificates**: TLS certificates for secure connections - **ConfigMaps and Secrets**: Configuration and sensitive data - **Deployments**: These support the `balancerd` and `console` pod used as the ingress layer for Materialize. - **StatefulSets**: `environmentd` and `clusterd` which are the database control plane and compute resources respectively. ### Configuration For configuration options for the Materialize Operator, see the [Materialize Operator Configuration page](/self-managed-deployments/operator-configuration/). ## Materialize Instance A Materialize instance is the actual database that you connect to and interact with. Each instance is an isolated Materialize deployment (deployed via a Kubernetes Custom Resource) with its own data, configuration, and compute resources. ### Components When you create a Materialize instance, the operator deploys three core components as Kubernetes resources: - **balancerd**: A pgwire and HTTP proxy that routes all Materialize client connections to `environmentd` for handling. `balancerd` is deployed as a Kubernetes Deployment. - **environmentd**: The main database control plane, deployed as a StatefulSet. **`environmentd`** runs as a Kubernetes pod and is the primary component of a Materialize instance. It houses the control plane and contains: - **Adapter**: The SQL interface that handles client connections, query parsing, and planning. - **Storage Controller**: Maintains durable metadata for storage. - **Compute Controller**: Orchestrates compute resources and manages system state. On startup, `environmentd` will create several built-in clusters. - **console**: Web-based administration interface, deployed as a Deployment. ### Instance responsibilities A Materialize instance manages: - **SQL objects**: Sources, views, materialized views, indexes, sinks - **Schemas and databases**: Logical organization of objects - **User connections**: SQL client connections and authentication - **Catalog metadata**: System information about all objects and configuration - **Compute orchestration**: Coordination of work across clusters and replicas ### Deploying with the operator To deploy Materialize instances with the operator, create and apply Materialize custom resources definitions(CRDs). For a full list of fields available for the Materialize CR, see [Materialize CRD Field Descriptions](/self-managed-deployments/materialize-crd-field-descriptions/). ```yaml apiVersion: materialize.cloud/v1alpha1 kind: Materialize metadata: name: 12345678-1234-1234-1234-123456789012 namespace: materialize-environment spec: environmentdImageRef: materialize/environmentd:v26.17.1 # ... additional fields omitted for brevity ``` When you first apply the Materialize custom resource, the operator automatically creates all required Kubernetes resources. ### Modifying the custom resource To modify a custom resource, update the CRD with your changes, including the `requestRollout` field with a new UUID value. When you apply the CRD, the operator will roll out the changes. > **Note:** If you do not specify a new `requestRollout` UUID, the operator > watches for updates but does not roll out the changes. For a full list of fields available for the Materialize CR, see [Materialize CRD Field Descriptions](/self-managed-deployments/materialize-crd-field-descriptions/). See also: - [Upgrade Overview](/self-managed-deployments/upgrading/) ### Connecting to an instance Once deployed, you interact with a Materialize instance through the Materialize Console or standard PostgreSQL-compatible tools and drivers: ```bash # Connect with psql psql "postgres://materialize@:6875/materialize" ``` Once connected, you can issue SQL commands to create sources, define views, run queries, and manage the database: ```sql -- Create a source CREATE SOURCE my_source FROM KAFKA ...; -- Create a materialized view CREATE MATERIALIZED VIEW my_view AS SELECT ... FROM my_source ...; -- Query the view SELECT * FROM my_view; ``` ## Clusters and Replicas Clusters are isolated pools of compute resources that execute workloads in Materialize. They provide resource isolation and fault tolerance for your data processing pipelines. For a comprehensive overview of clusters in Materialize, see the [Clusters concept page](/concepts/clusters/). ### Cluster architecture - **Clusters**: Logical groupings of compute resources dedicated to specific workloads (sources, sinks, indexes, materialized views, queries) - **Replicas**: Physical instantiations of a cluster's compute resources, deployed as Kubernetes StatefulSets Each replica contains identical compute resources and processes the same data independently, providing fault tolerance and high availability. ### Kubernetes resources When you create a cluster with one or more replicas in Materialize, the instance coordinates with the operator to create: - One or more **StatefulSet** resources (one per replica) - **Pods** within each StatefulSet that execute the actual compute workload - **Persistent volumes** (if configured) for scratch disk space For example: ```sql -- Create a cluster with 2 replicas CREATE CLUSTER my_cluster SIZE = '100cc', REPLICATION FACTOR = 2; ``` This creates two separate StatefulSets in Kubernetes, each running compute processes. ### Managing clusters You interact with clusters primarily through SQL: ```sql -- Create a cluster CREATE CLUSTER ingest_cluster SIZE = '50cc', REPLICATION FACTOR = 1; -- Use the previous cluster for a source CREATE SOURCE my_source IN CLUSTER ingest_cluster FROM KAFKA ...; -- Create a cluster for materialized views CREATE CLUSTER compute_cluster SIZE = '100cc', REPLICATION FACTOR = 2; -- Use the previous cluster for a materialized view CREATE MATERIALIZED VIEW my_view IN CLUSTER compute_cluster AS SELECT ... FROM my_source ...; -- Resize a cluster ALTER CLUSTER compute_cluster SET (SIZE = '200cc'); ``` Materialize handles the underlying Kubernetes resource creation and management automatically. ## Workflow The following outlines the workflow process, summarizing how the various components work together: 1. **Install the Helm chart**: This deploys the Materialize Operator to your Kubernetes cluster. 1. **Create a Materialize instance**: Apply a Materialize custom resource. The operator detects this and creates all necessary Kubernetes resources, including the `environmentd`, `balancerd`, and `console` pods. 1. **Connect to the instance**: Use the Materialize Console on port 8080 to connecto to the `console` service endpoint or SQL client on port 6875 to connect to the `balancerd` service endpoint. If authentication is enabled, you must first connect to the Materialize Console and set up users. 1. **Create clusters**: Issue SQL commands to create clusters. Materialize coordinates with the operator to provision StatefulSets for replicas. 1. **Run your workloads**: Create sources, materialized views, indexes, and sinks on your clusters. ## Available Terraform Modules To help you get started, Materialize provides Terraform modules. > **Important:** These modules are intended for evaluation/demonstration purposes and for serving > as a template when building your own production deployment. The modules should > not be directly relied upon for production deployments: **future releases of the > modules will contain breaking changes.** Instead, to use as a starting point for > your own production deployment, either: > - Fork the repo and pin to a specific version; or > - Use the code as a reference when developing your own deployment. **Terraform Modules (New!):** ### Terraform Modules Materialize provides [**Terraform modules**](https://github.com/MaterializeInc/materialize-terraform-self-managed/tree/main?tab=readme-ov-file#materialize-self-managed-terraform-modules), which provides concrete examples and an opinionated model for deploying Materialize. | Module | Description | | --- | --- | | Amazon Web Services (AWS) | An example Terraform module for deploying Materialize on AWS. See Install on AWS for detailed instructions usage. | | Azure | An example Terraform module for deploying Materialize on Azure. See Install on Azure for detailed instructions usage. | | Google Cloud Platform (GCP) | An example Terraform module for deploying Materialize on GCP. See Install on GCP for detailed instructions usage. | **Legacy Terraform Modules:** ### Legacy Terraform Modules | Sample Module | Description | | --- | --- | | terraform-helm-materialize (Legacy) | A sample Terraform module for installing the Materialize Helm chart into a Kubernetes cluster. | | Materialize on AWS (Legacy) | A sample Terraform module for deploying Materialize on AWS Cloud Platform with all required infrastructure components. See Install on AWS (Legacy) for an example usage. | | Materialize on Azure (Legacy) | A sample Terraform module for deploying Materialize on Azure with all required infrastructure components. See Install on Azure for an example usage. | | Materialize on GCP (Legacy) | A sample Terraform module for deploying Materialize on Google Cloud Platform (GCP) with all required infrastructure components. See Install on GCP for an example usage. | ## Related pages - [Installation guides](/self-managed-deployments/installation/) - [Materialize Operator Configuration](/self-managed-deployments/operator-configuration/) - [Materialize CRD Field Descriptions](/self-managed-deployments/materialize-crd-field-descriptions/) - [Operational guidelines](/self-managed-deployments/deployment-guidelines/) - [Clusters concept page](/concepts/clusters/) - [Materialize architecture overview](/concepts/) --- ## Appendix ## Table of contents - [Appendix: Cluster sizes](./appendix-cluster-sizes/) - [Appendix: Prepare for swap and upgrade to v26.0](./upgrade-to-swap/) --- ## Configuring System Parameters This guide explains how to configure system parameters for your Materialize deployment using a Kubernetes ConfigMap. ## Overview System parameters allow you to customize the behavior of your Materialize instance at runtime. These parameters can control various aspects such as connection limits, cluster replica sizes, and other operational settings. There are two ways to configure system parameters: - **Using SQL**: Connect to your Materialize instance and use the [`ALTER SYSTEM SET`](/sql/alter-system-set/) command to modify parameters dynamically. This is useful for one-off changes or testing. - **Using a ConfigMap**: Create a Kubernetes ConfigMap containing the parameters in JSON format and reference it in your Materialize custom resource. This is the recommended approach for persistent configuration that survives restarts and upgrades. This guide focuses on the ConfigMap approach for self-managed deployments. > **Public Preview:** This feature is in public preview. ## Configure System Parameters via ConfigMap ### Step 1: Create a System Parameters ConfigMap In the same namespace as your Materialize environment, create a ConfigMap that includes a key named `system-params.json`. Set `system-params.json` to a valid JSON object containing your desired system parameters. ```yaml apiVersion: v1 kind: ConfigMap metadata: name: mz-system-params namespace: materialize-environment data: system-params.json: | { "max_connections": 1000, "allowed_cluster_replica_sizes": "'25cc', '50cc', '100cc'" } ``` Apply the ConfigMap to your cluster: ```shell kubectl apply -f system-params-configmap.yaml ``` ### Step 2: Configure the Materialize Custom Resource Reference the ConfigMap in your Materialize custom resource by setting the `systemParameterConfigmapName` field to the name of your ConfigMap: ```yaml {hl_lines="9"} apiVersion: materialize.cloud/v1alpha1 kind: Materialize metadata: name: 12345678-1234-1234-1234-123456789012 namespace: materialize-environment spec: environmentdImageRef: materialize/environmentd:v26.0.0 backendSecretName: materialize-backend systemParameterConfigmapName: mz-system-params ``` Apply the updated Materialize resource: ```shell kubectl apply -f materialize.yaml ``` ## Updating ConfigMap System Parameters To update system parameters defined in your ConfigMap, you can either: - Use `kubectl edit configmap` to edit the ConfigMap and apply the changes: ```shell kubectl edit configmap mz-system-params -n materialize-environment ``` - Or, edit the ConfigMap YAML file and reapply: ```shell kubectl apply -f system-params-configmap.yaml ``` ### ConfigMap sync behavior Kubernetes uses the kubelet to periodically sync ConfigMap updates to mounted volumes. By default, this sync occurs approximately every 60 seconds. This means changes to your ConfigMap may take up to a minute to be reflected in the running Materialize instance. Once the ConfigMap is synced to the volume, Materialize checks for configuration changes every second and applies them automatically. To force an immediate sync of the ConfigMap from Kubernetes, you can update an annotation on the Materialize resource, which triggers a pod re-reconciliation: ```shell kubectl annotate materialize \ -n materialize-environment \ configmap-reload-trigger="$(date +%s)" \ --overwrite ``` Alternatively, you can add the `configmap-reload-trigger` annotation to your Materialize custom resource YAML and update it whenever you need to force a ConfigMap reload: ```yaml apiVersion: materialize.cloud/v1alpha1 kind: Materialize metadata: name: 12345678-1234-1234-1234-123456789012 namespace: materialize-environment annotations: configmap-reload-trigger: "1234567890" # Update this value to force reload spec: # ... rest of spec ``` > **Note:** Even after the ConfigMap is synced, some parameters may require a restart to > take effect. ## Available System Parameters The system parameters that can be configured via the ConfigMap are the same parameters that can be modified using the [`ALTER SYSTEM SET`](/sql/alter-system-set/) SQL command. The following are some commonly configured system parameters: | Parameter | Description | |-----------|-------------| | `max_connections` | Maximum number of concurrent connections allowed | | `allowed_cluster_replica_sizes` | List of allowed cluster replica sizes | | `max_clusters` | Maximum number of clusters in the region | | `max_sources` | Maximum number of sources in the region | | `max_sinks` | Maximum number of sinks in the region | For a complete list of available system parameters and their descriptions, see the [configuration parameters](/sql/alter-system-set/#key-configuration-parameters) documentation, or run the following SQL command in your Materialize instance: ```sql SHOW ALL; ``` ### Sample ConfigMap: Setting Connection Limits The following sample ConfigMap YAML sets the `max_connections` parameter: ```yaml apiVersion: v1 kind: ConfigMap metadata: name: mz-system-params namespace: materialize-environment data: system-params.json: | { "max_connections": 500 } ``` ### Sample ConfigMap: Configuring Allowed Cluster Sizes The following sample ConfigMap YAML sets the `allowed_cluster_replica_sizes` parameter: ```yaml apiVersion: v1 kind: ConfigMap metadata: name: mz-system-params namespace: materialize-environment data: system-params.json: | { "allowed_cluster_replica_sizes": "'25cc', '50cc', '100cc', '200cc'" } ``` ### Sample ConfigMap: Configuring Connection Limits and Allowed Cluster Sizes The following sample ConfigMap YAML sets both the `max_connections` parameter and the `allowed_cluster_replica_sizes` parameter: ```yaml apiVersion: v1 kind: ConfigMap metadata: name: mz-system-params namespace: materialize-environment data: system-params.json: | { "max_connections": 500, "allowed_cluster_replica_sizes": "'25cc', '50cc', '100cc', '200cc'" } ``` ## Troubleshooting ### ConfigMap not being applied If your system parameters are not being applied, check the following: 1. **Verify the ConfigMap exists** in the correct namespace: ```shell kubectl get configmap mz-system-params -n materialize-environment ``` 2. **Check the ConfigMap content** is valid JSON: ```shell kubectl get configmap mz-system-params -n materialize-environment -o jsonpath='{.data.system-params\.json}' ``` 3. **Verify the Materialize resource** references the correct ConfigMap name: ```shell kubectl get materialize -n materialize-environment -o yaml | grep systemParameterConfigmapName ``` 4. **Check environmentd logs** for any errors related to configuration loading: ```shell kubectl logs -l app=environmentd -n materialize-environment ``` ### Invalid parameter values If a system parameter value is invalid, Materialize will log an error but continue running with the previous valid configuration. Check the environmentd logs for error messages: ```shell kubectl logs -l app=environmentd -n materialize-environment | grep -i "system.*param" ``` ## See also - [Materialize Operator Configuration](/installation/configuration/) - [Materialize CRD Field Descriptions](/installation/appendix-materialize-crd-field-descriptions/) - [Troubleshooting](/installation/troubleshooting/) --- ## Deployment guidelines Self-managed Materialize requires: a Kubernetes (v1.31+) cluster; PostgreSQL as a metadata database; blob storage; and a license key. ## Available deployment guidelines The following guides outline recommended configurations for deploying Materialize across different cloud environments. - [AWS Deployment Guidelines](/self-managed-deployments/deployment-guidelines/aws-deployment-guidelines/) - [Azure Deployment Guidelines](/self-managed-deployments/deployment-guidelines/azure-deployment-guidelines/) - [GCP Deployment Guidelines](/self-managed-deployments/deployment-guidelines/gcp-deployment-guidelines/) --- ## FAQ ## How long do license keys last? Community edition license keys are valid for one year. Enterprise license keys will vary based on the terms of your contract. ## How do I get a license key? | License key type | Deployment type | Action | | --- | --- | --- | | Community | New deployments |

To get a license key:

| | Community | Existing deployments | Contact Materialize support. | | Enterprise | New deployments | Visit https://materialize.com/self-managed/enterprise-license/ to purchase an Enterprise license. | | Enterprise | Existing deployments | Contact Materialize support. | ## How do I add a license key to an existing installation? The license key should be configured in the Kubernetes Secret resource created during the installation process. To configure a license key in an existing installation, run: ```bash kubectl -n materialize-environment patch secret materialize-backend -p '{"stringData":{"license_key":""}}' --type=merge ``` ## How can I downgrade Self-Managed Materialize? Downgrading is not supported. --- ## Installation

You can install Self-Managed Materialize on a Kubernetes cluster running locally or on a cloud provider. Self-Managed Materialize requires:

  • A Kubernetes (v1.31+) cluster.
  • PostgreSQL as a metadata database.
  • Blob storage.
  • A license key.

License key

Starting in v26.0, Materialize requires a license key.

| License key type | Deployment type | Action | | --- | --- | --- | | Community | New deployments |

To get a license key:

| | Community | Existing deployments | Contact Materialize support. | | Enterprise | New deployments | Visit https://materialize.com/self-managed/enterprise-license/ to purchase an Enterprise license. | | Enterprise | Existing deployments | Contact Materialize support. |

Installation guides

The following installation guides are available to help you get started:

Install using Helm Commands

Guide Description
Install locally on Kind Uses standard Helm commands to deploy Materialize to a Kind cluster in Docker.

Install using Terraform Modules

> **Tip:** The Terraform modules are provided as examples. They are not required for > installing Materialize.
Guide Description
Install on AWS Uses Terraform module to deploy Materialize to AWS Elastic Kubernetes Service (EKS).
Install on Azure Uses Terraform module to deploy Materialize to Azure Kubernetes Service (AKS).
Install on GCP Uses Terraform module to deploy Materialize to Google Kubernetes Engine (GKE).

Install using Legacy Terraform Modules

> **Tip:** The Terraform modules are provided as examples. They are not required for > installing Materialize.
Guide Description
Install on AWS (Legacy Terraform) Uses legacy Terraform module to deploy Materialize to AWS Elastic Kubernetes Service (EKS).
Install on Azure (Legacy Terraform) Uses legacy Terraform module to deploy Materialize to Azure Kubernetes Service (AKS).
Install on GCP (Legacy Terraform) Uses legacy Terraform module to deploy Materialize to Google Kubernetes Engine (GKE).
--- ## Materialize CRD Field Descriptions #### MaterializeSpec
Field Name Required Description
backendSecretName ✅ String

The name of a secret containing metadata_backend_url and persist_backend_url. It may also contain external_login_password_mz_system, which will be used as the password for the mz_system user if authenticatorKind is Password, Sasl, or Oidc.
environmentdImageRef ✅ String

The environmentd image to run.
authenticatorKind Enum

How to authenticate with Materialize.

Valid values:

  • Frontegg:
    Authenticate users using Frontegg.
  • Password:
    Authenticate users using internally stored password hashes. The backend secret must contain external_login_password_mz_system.
  • Sasl:
    Authenticate users using SASL.
  • Oidc:
    Authenticate users using OIDC (JWT tokens).
  • None (default):
    Do not authenticate users. Trust they are who they say they are without verification.

Default: None
balancerdExternalCertificateSpec MaterializeCertSpec

The configuration for generating an x509 certificate using cert-manager for balancerd to present to incoming connections. The dnsNames and issuerRef fields are required.
balancerdReplicas Integer

Number of balancerd pods to create.
balancerdResourceRequirements io.k8s.api.core.v1.ResourceRequirements

Resource requirements for the balancerd pod.
consoleExternalCertificateSpec MaterializeCertSpec

The configuration for generating an x509 certificate using cert-manager for the console to present to incoming connections. The dnsNames and issuerRef fields are required. Not yet implemented.
consoleReplicas Integer

Number of console pods to create.
consoleResourceRequirements io.k8s.api.core.v1.ResourceRequirements

Resource requirements for the console pod.
enableRbac Bool

Whether to enable role based access control. Defaults to false.
environmentId Uuid

The value used by environmentd (via the –environment-id flag) to uniquely identify this instance. Must be globally unique, and is required if a license key is not provided. NOTE: This value MUST NOT be changed in an existing instance, since it affects things like the way data is stored in the persist backend.

Default: 00000000-0000-0000-0000-000000000000
environmentdConnectionRoleArn String

If running in AWS, override the IAM role to use to support the CREATE CONNECTION feature.
environmentdExtraArgs Array<String>

Extra args to pass to the environmentd binary.
environmentdExtraEnv Array<io.k8s.api.core.v1.EnvVar>

Extra environment variables to pass to the environmentd binary.
environmentdResourceRequirements io.k8s.api.core.v1.ResourceRequirements

Resource requirements for the environmentd pod.
environmentdScratchVolumeStorageRequirement io.k8s.apimachinery.pkg.api.resource.Quantity

Amount of disk to allocate, if a storage class is provided.
forcePromote Uuid

If forcePromote is set to the same value as requestRollout, the current rollout will skip waiting for clusters in the new generation to rehydrate before promoting the new environmentd to leader.

Default: 00000000-0000-0000-0000-000000000000
forceRollout Uuid

This value will be written to an annotation in the generated environmentd statefulset, in order to force the controller to detect the generated resources as changed even if no other changes happened. This can be used to force a rollout to a new generation even without making any meaningful changes, by setting it to the same value as requestRollout.

Default: 00000000-0000-0000-0000-000000000000
internalCertificateSpec MaterializeCertSpec

The cert-manager Issuer or ClusterIssuer to use for database internal communication. The issuerRef field is required. This currently is only used for environmentd, but will eventually support clusterd. Not yet implemented.
podAnnotations Map<String, String>

Annotations to apply to the pods.
podLabels Map<String, String>

Labels to apply to the pods.
requestRollout Uuid

When changes are made to the environmentd resources (either via modifying fields in the spec here or by deploying a new orchestratord version which changes how resources are generated), existing environmentd processes won’t be automatically restarted. In order to trigger a restart, the request_rollout field should be set to a new (random) value. Once the rollout completes, the value of status.lastCompletedRolloutRequest will be set to this value to indicate completion.

Defaults to a random value in order to ensure that the first generation rollout is automatically triggered.

Default: 00000000-0000-0000-0000-000000000000
rolloutStrategy Enum

Rollout strategy to use when upgrading this Materialize instance.

Valid values:

  • WaitUntilReady (default):
    Create a new generation of pods, leaving the old generation around until the new ones are ready to take over. This minimizes downtime, and is what almost everyone should use.

  • ManuallyPromote:
    Create a new generation of pods, leaving the old generation as the serving generation until the user manually promotes the new generation.

    When using ManuallyPromote, the new generation can be promoted at any time, even if it has dataflows that are not fully caught up, by setting forcePromote to the same value as requestRollout in the Materialize spec.

    To minimize downtime, promotion should occur when the new generation has caught up to the prior generation. To determine if the new generation has caught up, consult the UpToDate condition in the status of the Materialize Resource. If the condition’s reason is ReadyToPromote the new generation is ready to promote.

    > **Warning:** Do not leave new generations unpromoted indefinitely. > The new generation keeps open read holds which prevent compaction. Once promoted or > cancelled, those read holds are released. If left unpromoted for an extended time, this > data can build up, and can cause extreme deletion load on the metadata backend database > when finally promoted or cancelled.

  • ImmediatelyPromoteCausingDowntime:
    > **Warning:** THIS WILL CAUSE YOUR MATERIALIZE INSTANCE TO BE UNAVAILABLE FOR SOME TIME!!! > This strategy should ONLY be used by customers with physical hardware who do not have > enough hardware for the `WaitUntilReady` strategy. If you think you want this, please > consult with Materialize engineering to discuss your situation.

    Tear down the old generation of pods and promote the new generation of pods immediately, without waiting for the new generation of pods to be ready.

Default: WaitUntilReady
serviceAccountAnnotations Map<String, String>

Annotations to apply to the service account.

Annotations on service accounts are commonly used by cloud providers for IAM. AWS uses “eks.amazonaws.com/role-arn”. Azure uses “azure.workload.identity/client-id”, but additionally requires “azure.workload.identity/use”: “true” on the pods.
serviceAccountLabels Map<String, String>

Labels to apply to the service account.
serviceAccountName String

Name of the kubernetes service account to use. If not set, we will create one with the same name as this Materialize object.
systemParameterConfigmapName String

The name of a ConfigMap containing system parameters in JSON format. The ConfigMap must contain a system-params.json key whose value is a valid JSON object containing valid system parameters.

Run SHOW ALL in SQL to see a subset of configurable system parameters.

Example ConfigMap:

data:
  system-params.json: |
    {
      "max_connections": 1000
    }

#### MaterializeCertSpec
Field Name Required Description
dnsNames Array<String>

Additional DNS names the certificate will be valid for.
duration String

Duration the certificate will be requested for. Value must be in units accepted by Go time.ParseDuration.
issuerRef CertificateIssuerRef

Reference to an Issuer or ClusterIssuer that will generate the certificate.
privateKeyAlgorithm CertificatePrivateKeyAlgorithm

Optional algorithm to use for the private key. If not specified, a recommended default will be chosen.
privateKeySize Integer

Optional size for the private key.
renewBefore String

Duration before expiration the certificate will be renewed. Value must be in units accepted by Go time.ParseDuration.
secretTemplate CertificateSecretTemplate

Additional annotations and labels to include in the Certificate object.
#### CertificateSecretTemplate
Field Name Required Description
annotations Map<String, String>

Annotations is a key value map to be copied to the target Kubernetes Secret.
labels Map<String, String>

Labels is a key value map to be copied to the target Kubernetes Secret.
#### CertificateIssuerRef
Field Name Required Description
name ✅ String

Name of the resource being referred to.
group String

Group of the resource being referred to.
kind String

Kind of the resource being referred to.
#### io.k8s.api.core.v1.ResourceRequirements
Field Name Required Description
claims Array<io.k8s.api.core.v1.ResourceClaim>

Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container.

This is an alpha field and requires enabling the DynamicResourceAllocation feature gate.

This field is immutable. It can only be set for containers.
limits Map<String, io.k8s.apimachinery.pkg.api.resource.Quantity>

Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
requests Map<String, io.k8s.apimachinery.pkg.api.resource.Quantity>

Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
#### io.k8s.api.core.v1.ResourceClaim
Field Name Required Description
name ✅ String

Name must match the name of one entry in pod.spec.resourceClaims of the Pod where this field is used. It makes that resource available inside a container.
request String

Request is the name chosen for a request in the referenced claim. If empty, everything from the claim is made available, otherwise only the result of this request.
#### io.k8s.api.core.v1.EnvVar
Field Name Required Description
name ✅ String

Name of the environment variable. Must be a C_IDENTIFIER.
value String

Variable references $(VAR_NAME) are expanded using the previously defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to “”.
valueFrom io.k8s.api.core.v1.EnvVarSource

Source for the environment variable’s value. Cannot be used if value is not empty.
#### io.k8s.api.core.v1.EnvVarSource
Field Name Required Description
configMapKeyRef io.k8s.api.core.v1.ConfigMapKeySelector

Selects a key of a ConfigMap.
fieldRef io.k8s.api.core.v1.ObjectFieldSelector

Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels['<KEY>'], metadata.annotations['<KEY>'], spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs.
resourceFieldRef io.k8s.api.core.v1.ResourceFieldSelector

Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported.
secretKeyRef io.k8s.api.core.v1.SecretKeySelector

Selects a key of a secret in the pod’s namespace
#### io.k8s.api.core.v1.SecretKeySelector
Field Name Required Description
key ✅ String

The key of the secret to select from. Must be a valid secret key.
name ✅ String

Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
optional Bool

Specify whether the Secret or its key must be defined
#### io.k8s.api.core.v1.ResourceFieldSelector
Field Name Required Description
resource ✅ String

Required: resource to select
containerName String

Container name: required for volumes, optional for env vars
divisor io.k8s.apimachinery.pkg.api.resource.Quantity

Specifies the output format of the exposed resources, defaults to “1”
#### io.k8s.api.core.v1.ObjectFieldSelector
Field Name Required Description
fieldPath ✅ String

Path of the field to select in the specified API version.
apiVersion String

Version of the schema the FieldPath is written in terms of, defaults to “v1”.
#### io.k8s.api.core.v1.ConfigMapKeySelector
Field Name Required Description
key ✅ String

The key to select.
name ✅ String

Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
optional Bool

Specify whether the ConfigMap or its key must be defined
--- ## Materialize Operator Configuration ## Configure the Materialize operator To configure the Materialize operator, you can: - Use a configuration YAML file (e.g., `values.yaml`) that specifies the configuration values and then install the chart with the `-f` flag: ```shell # Assumes you have added the Materialize operator Helm chart repository helm install my-materialize-operator materialize/materialize-operator \ -f /path/to/your/config/values.yaml ``` - Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`. For example: ```shell # Assumes you have added the Materialize operator Helm chart repository helm install my-materialize-operator materialize/materialize-operator \ --set observability.podMetrics.enabled=true ```
Parameter Default
balancerd.affinity
balancerd.defaultResources.limits {"memory":"256Mi"}
balancerd.defaultResources.requests {"cpu":"500m","memory":"256Mi"}
balancerd.enabled true
balancerd.nodeSelector
balancerd.tolerations
clusterd.affinity
clusterd.nodeSelector
clusterd.scratchfsNodeSelector
clusterd.swapNodeSelector
clusterd.tolerations
console.affinity
console.defaultResources.limits {"memory":"256Mi"}
console.defaultResources.requests {"cpu":"500m","memory":"256Mi"}
console.enabled true
console.imageTagMapOverride {}
console.nodeSelector
console.tolerations
environmentd.affinity
environmentd.defaultResources.limits {"memory":"4Gi"}
environmentd.defaultResources.requests {"cpu":"1","memory":"4095Mi"}
environmentd.nodeSelector
environmentd.tolerations
networkPolicies.egress.cidrs ["0.0.0.0/0"]
networkPolicies.egress.enabled false
networkPolicies.enabled false
networkPolicies.ingress.cidrs ["0.0.0.0/0"]
networkPolicies.ingress.enabled false
networkPolicies.internal.enabled false
observability.enabled true
observability.podMetrics.enabled false
observability.prometheus.scrapeAnnotations.enabled true
operator.additionalMaterializeCRDColumns {}
operator.affinity
operator.args.enableInternalStatementLogging true
operator.args.enableLicenseKeyChecks false
operator.args.startupLogFilter "INFO,mz_orchestratord=TRACE"
operator.cloudProvider.providers.aws.accountID ""
operator.cloudProvider.providers.aws.enabled false
operator.cloudProvider.providers.aws.iam.roles.connection ""
operator.cloudProvider.providers.aws.iam.roles.environment ""
operator.cloudProvider.providers.gcp {"enabled":false}
operator.cloudProvider.region "kind"
operator.cloudProvider.type "local"
operator.clusters.defaultReplicationFactor.analytics 0
operator.clusters.defaultReplicationFactor.probe 0
operator.clusters.defaultReplicationFactor.support 0
operator.clusters.defaultReplicationFactor.system 0
operator.clusters.defaultSizes.analytics "25cc"
operator.clusters.defaultSizes.catalogServer "25cc"
operator.clusters.defaultSizes.default "25cc"
operator.clusters.defaultSizes.probe "mz_probe"
operator.clusters.defaultSizes.support "25cc"
operator.clusters.defaultSizes.system "25cc"
operator.clusters.swap_enabled true
operator.image.pullPolicy "IfNotPresent"
operator.image.repository "materialize/orchestratord"
operator.image.tag "v26.17.0"
operator.nodeSelector
operator.resources.limits {"memory":"512Mi"}
operator.resources.requests {"cpu":"100m","memory":"512Mi"}
operator.secretsController "kubernetes"
operator.tolerations
rbac.create true
schedulerName nil
serviceAccount.create true
serviceAccount.name "orchestratord"
storage.storageClass.allowVolumeExpansion false
storage.storageClass.create false
storage.storageClass.name ""
storage.storageClass.parameters {"fsType":"ext4","storage":"lvm","volgroup":"instance-store-vg"}
storage.storageClass.provisioner ""
storage.storageClass.reclaimPolicy "Delete"
storage.storageClass.volumeBindingMode "WaitForFirstConsumer"
telemetry.enabled true
telemetry.segmentApiKey "hMWi3sZ17KFMjn2sPWo9UJGpOQqiba4A"
telemetry.segmentClientSide true
tls.defaultCertificateSpecs {}
## Parameters ### `balancerd` parameters #### balancerd.affinity **Default**: Affinity to use for balancerd pods spawned by the operator #### balancerd.defaultResources.limits **Default**: {"memory":"256Mi"} Default resource limits for balancerd’s CPU and memory if not set in the Materialize CR #### balancerd.defaultResources.requests **Default**: {"cpu":"500m","memory":"256Mi"} Default resources requested for balancerd’s CPU and memory if not set in the Materialize CR #### balancerd.enabled **Default**: true Flag to indicate whether to create balancerd pods for the environments #### balancerd.nodeSelector **Default**: Node selector to use for balancerd pods spawned by the operator #### balancerd.tolerations **Default**: Tolerations to use for balancerd pods spawned by the operator ### `clusterd` parameters #### clusterd.affinity **Default**: Affinity to use for clusterd pods spawned by the operator #### clusterd.nodeSelector **Default**: Node selector to use for all clusterd pods spawned by the operator #### clusterd.scratchfsNodeSelector **Default**: Additional node selector to use for clusterd pods when using an LVM scratch disk. This will be merged with the values in nodeSelector. #### clusterd.swapNodeSelector **Default**: Additional node selector to use for clusterd pods when using swap. This will be merged with the values in nodeSelector. #### clusterd.tolerations **Default**: Tolerations to use for clusterd pods spawned by the operator ### `console` parameters #### console.affinity **Default**: Affinity to use for console pods spawned by the operator #### console.defaultResources.limits **Default**: {"memory":"256Mi"} Default resource limits for the console’s CPU and memory if not set in the Materialize CR #### console.defaultResources.requests **Default**: {"cpu":"500m","memory":"256Mi"} Default resources requested for the console’s CPU and memory if not set in the Materialize CR #### console.enabled **Default**: true Flag to indicate whether to create console pods for the environments #### console.imageTagMapOverride **Default**: {} Override the mapping of environmentd versions to console versions #### console.nodeSelector **Default**: Node selector to use for console pods spawned by the operator #### console.tolerations **Default**: Tolerations to use for console pods spawned by the operator ### `environmentd` parameters #### environmentd.affinity **Default**: Affinity to use for environmentd pods spawned by the operator #### environmentd.defaultResources.limits **Default**: {"memory":"4Gi"} Default resource limits for environmentd’s CPU and memory if not set in the Materialize CR #### environmentd.defaultResources.requests **Default**: {"cpu":"1","memory":"4095Mi"} Default resources requested for environmentd’s CPU and memory if not set in the Materialize CR #### environmentd.nodeSelector **Default**: Node selector to use for environmentd pods spawned by the operator #### environmentd.tolerations **Default**: Tolerations to use for environmentd pods spawned by the operator ### `networkPolicies` parameters #### networkPolicies.egress.cidrs **Default**: ["0.0.0.0/0"] CIDR blocks to allow egress to #### networkPolicies.egress.enabled **Default**: false Whether to enable egress network policies to sources and sinks #### networkPolicies.enabled **Default**: false Whether to enable network policies for securing communication between pods #### networkPolicies.ingress.cidrs **Default**: ["0.0.0.0/0"] CIDR blocks to allow ingress from #### networkPolicies.ingress.enabled **Default**: false Whether to enable ingress network policies to the SQL and HTTP interfaces on environmentd and balancerd #### networkPolicies.internal.enabled **Default**: false Whether to enable network policies for internal communication between Materialize pods ### `observability` parameters #### observability.enabled **Default**: true Whether to enable observability features #### observability.podMetrics.enabled **Default**: false Whether to enable the pod metrics scraper which populates the Environment Overview Monitoring tab in the web console (requires metrics-server to be installed) #### observability.prometheus.scrapeAnnotations.enabled **Default**: true Whether to annotate pods with common keys used for prometheus scraping. ### `operator` parameters #### operator.additionalMaterializeCRDColumns **Default**: {} Additional columns to display when printing the Materialize CRD in table format. #### operator.affinity **Default**: Affinity to use for the operator pod #### operator.args.enableInternalStatementLogging **Default**: true #### operator.args.enableLicenseKeyChecks **Default**: false #### operator.args.startupLogFilter **Default**: "INFO,mz_orchestratord=TRACE" Log filtering settings for startup logs #### operator.cloudProvider.providers.aws.accountID **Default**: "" When using AWS, accountID is required #### operator.cloudProvider.providers.aws.enabled **Default**: false #### operator.cloudProvider.providers.aws.iam.roles.connection **Default**: "" ARN for CREATE CONNECTION feature #### operator.cloudProvider.providers.aws.iam.roles.environment **Default**: "" ARN of the IAM role for environmentd #### operator.cloudProvider.providers.gcp **Default**: {"enabled":false} GCP Configuration (placeholder for future use) #### operator.cloudProvider.region **Default**: "kind" Common cloud provider settings #### operator.cloudProvider.type **Default**: "local" Specifies cloud provider. Valid values are ‘aws’, ‘gcp’, ‘azure’ , ‘generic’, or ’local’ #### operator.clusters.defaultReplicationFactor.analytics **Default**: 0 #### operator.clusters.defaultReplicationFactor.probe **Default**: 0 #### operator.clusters.defaultReplicationFactor.support **Default**: 0 #### operator.clusters.defaultReplicationFactor.system **Default**: 0 #### operator.clusters.defaultSizes.analytics **Default**: "25cc" #### operator.clusters.defaultSizes.catalogServer **Default**: "25cc" #### operator.clusters.defaultSizes.default **Default**: "25cc" #### operator.clusters.defaultSizes.probe **Default**: "mz_probe" #### operator.clusters.defaultSizes.support **Default**: "25cc" #### operator.clusters.defaultSizes.system **Default**: "25cc" #### operator.clusters.swap_enabled **Default**: true Configure sizes such that the pod QoS class is not Guaranteed, as is required for swap to be enabled. Disk doesn’t make much sense with swap, as swap performs better than lgalloc, so it also gets disabled. #### operator.image.pullPolicy **Default**: "IfNotPresent" Policy for pulling the image: “IfNotPresent” avoids unnecessary re-pulling of images #### operator.image.repository **Default**: "materialize/orchestratord" The Docker repository for the operator image #### operator.image.tag **Default**: "v26.17.0" The tag/version of the operator image to be used #### operator.nodeSelector **Default**: Node selector to use for the operator pod #### operator.resources.limits **Default**: {"memory":"512Mi"} Resource limits for the operator’s CPU and memory #### operator.resources.requests **Default**: {"cpu":"100m","memory":"512Mi"} Resources requested by the operator for CPU and memory #### operator.secretsController **Default**: "kubernetes" Which secrets controller to use for storing secrets. Valid values are ‘kubernetes’ and ‘aws-secrets-manager’. Setting ‘aws-secrets-manager’ requires a configured AWS cloud provider and IAM role for the environment with Secrets Manager permissions. #### operator.tolerations **Default**: Tolerations to use for the operator pod ### `rbac` parameters #### rbac.create **Default**: true Whether to create necessary RBAC roles and bindings ### `schedulerName` parameters #### schedulerName **Default**: nil Optionally use a non-default kubernetes scheduler. ### `serviceAccount` parameters #### serviceAccount.create **Default**: true Whether to create a new service account for the operator #### serviceAccount.name **Default**: "orchestratord" The name of the service account to be created ### `storage` parameters #### storage.storageClass.allowVolumeExpansion **Default**: false #### storage.storageClass.create **Default**: false Set to false to use an existing StorageClass instead. Refer to the Kubernetes StorageClass documentation #### storage.storageClass.name **Default**: "" Name of the StorageClass to create/use: eg “openebs-lvm-instance-store-ext4” #### storage.storageClass.parameters **Default**: {"fsType":"ext4","storage":"lvm","volgroup":"instance-store-vg"} Parameters for the CSI driver #### storage.storageClass.provisioner **Default**: "" CSI driver to use, eg “local.csi.openebs.io” #### storage.storageClass.reclaimPolicy **Default**: "Delete" #### storage.storageClass.volumeBindingMode **Default**: "WaitForFirstConsumer" ### `telemetry` parameters #### telemetry.enabled **Default**: true #### telemetry.segmentApiKey **Default**: "hMWi3sZ17KFMjn2sPWo9UJGpOQqiba4A" #### telemetry.segmentClientSide **Default**: true ### `tls` parameters #### tls.defaultCertificateSpecs **Default**: {} ## See also - [Installation](/installation/) - [Troubleshooting](/installation/troubleshooting/) --- ## Self-managed release versions ## V26 releases | Materialize Operator | orchestratord version | environmentd version | Release date | Notes | | --- | --- | --- | --- | --- | | v26.17.1 | v26.17.1 | v26.17.1 | 2026-03-27 | | | v26.17.0 | v26.17.0 | v26.17.0 | 2026-03-27 | See v26.17.0 release notes | | v26.16.0 | v26.16.0 | v26.16.0 | 2026-03-20 | See v26.16.0 release notes | | v26.15.0 | v26.15.0 | v26.15.0 | 2026-03-13 | | | v26.15.0 | v26.15.0 | v26.15.0 | 2026-03-13 | See v26.15.0 release notes | | v26.14.1 | v26.14.1 | v26.14.1 | 2026-03-06 | See v26.14 release notes | | v26.14.0 | v26.14.0 | v26.14.0 | 2026-03-06 | | | v26.13.0 | v26.13.0 | v26.13.0 | 2026-02-27 | See v26.13.0 release notes | | v26.12.1 | v26.12.1 | v26.12.1 | 2026-02-20 | | | v26.12.0 | v26.12.0 | v26.12.0 | 2026-02-20 | See v26.12.0 release notes | | v26.11.0 | v26.11.0 | v26.11.0 | 2026-02-13 | See v26.11.0 release notes | | v26.10.2 | v26.10.2 | v26.10.2 | 2026-02-09 | | | v26.10.1 | v26.10.1 | v26.10.1 | 2026-02-06 | See v26.10.1 release notes | | v26.9.0 | v26.9.0 | v26.9.0 | 2026-01-30 | See v26.9.0 release notes | | v26.8.0 | v26.8.0 | v26.8.0 | 2026-01-23 | See v26.8.0 release notes | | v26.7.0 | v26.7.0 | v26.7.0 | 2026-01-16 | See v26.7.0 release notes | | v26.6.0 | v26.6.0 | v26.6.0 | 2026-01-12 | See v26.6.0 release notes | | v26.5.1 | v26.5.1 | v26.5.1 | 2025-12-23 | See v26.5.1 release notes | | v26.5.0 | v26.5.0 | v26.5.0 | 2025-12-23 | Do not use. | | v26.4.0 | v26.4.0 | v26.4.0 | 2025-12-17 | See v26.4.0 release notes. | | v26.3.0 | v26.3.0 | v26.3.0 | 2025-12-12 | See v26.3.0 release notes. | | v26.2.0 | v26.2.0 | v26.2.0 | 2025-12-09 | See v26.2.0 release notes. | | v26.1.0 | v26.1.0 | v26.1.0 | 2025-11-26 | See v26.1.0 release notes. | | v26.0.0 | v26.0.0 | v26.0.0 | 2025-11-18 | See v26.0.0 release notes | --- ## Troubleshooting ## Troubleshooting Kubernetes To check the status of the Materialize operator: ```shell kubectl -n materialize get all ``` If you encounter issues with the Materialize operator, - Check the operator logs, using the label selector: ```shell kubectl -n materialize logs -l app.kubernetes.io/name=materialize-operator ``` - Check the log of a specific object (pod/deployment/etc) running in your namespace: ```shell kubectl -n materialize logs / ``` In case of a container restart, to get the logs for previous instance, include the `--previous` flag. - Check the events for the operator pod: - You can use `kubectl describe`, substituting your pod name for ``: ```shell kubectl -n materialize describe pod/ ``` - You can use `kubectl get events`, substituting your pod name for ``: ```shell kubectl -n materialize get events --sort-by=.metadata.creationTimestamp --field-selector involvedObject.name= ``` ### Materialize deployment - To check the status of your Materialize deployment, run: ```shell kubectl -n materialize-environment get all ``` - To check the log of a specific object (pod/deployment/etc) running in your namespace: ```shell kubectl -n materialize-environment logs / ``` In case of a container restart, to get the logs for previous instance, include the `--previous` flag. - To describe an object, you can use `kubectl describe`: ```shell kubectl -n materialize-environment describe / ``` For additional `kubectl` commands, see [kubectl Quick reference](https://kubernetes.io/docs/reference/kubectl/quick-reference/). ## Troubleshooting Console unresponsiveness If you experience long loading screens or unresponsiveness in the Materialize Console, it may be that the size of the `mz_catalog_server` cluster (where the majority of the Console's queries are run) is insufficient (default size is `25cc`). To increase the cluster's size, you can follow the following steps: 1. Login as the `mz_system` user in order to update `mz_catalog_server`. 1. To login as `mz_system` you'll need the internal-sql port found in the `environmentd` pod (`6877` by default). You can port forward via `kubectl port-forward svc/mzXXXXXXXXXX 6877:6877 -n materialize-environment`. 1. Connect using a pgwire compatible client (e.g., `psql`) and connect using the port and user `mz_system`. For example: ``` psql -h localhost -p 6877 --user mz_system ``` 3. Run the following [ALTER CLUSTER](/sql/alter-cluster/#resizing) statement to change the cluster size to `50cc`: ```mzsql ALTER CLUSTER mz_catalog_server SET (SIZE = '50cc'); ``` 4. Verify your changes via `SHOW CLUSTERS;` ```mzsql show clusters; ``` The output should include the `mz_catalog_server` cluster with a size of `50cc`: ```none name | replicas | comment -------------------+-----------+--------- mz_analytics | | mz_catalog_server | r1 (50cc) | mz_probe | | mz_support | | mz_system | | quickstart | r1 (25cc) | (6 rows) ``` --- ## Upgrading Materialize releases new Self-Managed versions per the schedule outlined in [Release schedule](/releases/schedule/#self-managed-release-schedule). ## General rules for upgrading

When upgrading:

> **Note:** For major version upgrades, you can only upgrade one major version > at a time. For example, upgrades from v26.1.0 to v27.3.0 is > permitted but v26.1.0 to v28.0.0 is not. ## Upgrade guides The following upgrade guides are available as examples:

Upgrade using Helm Commands

Guide Description
Upgrade on Kind Uses standard Helm commands to upgrade Materialize on a Kind cluster in Docker.

Upgrade using the new Terraform Modules

> **Tip:** The Terraform modules are provided as examples. They are not required for > upgrading Materialize.
Guide Description
Upgrade on AWS (Terraform) Uses the new Terraform module to deploy Materialize to AWS Elastic Kubernetes Service (EKS).
Upgrade on Azure (Terraform) Uses the new Terraform module to deploy Materialize to Azure Kubernetes Service (AKS).
Upgrade on GCP (Terraform) Uses the new Terraform module to deploy Materialize to Google Kubernetes Engine (GKE).

Upgrade using Legacy Terraform Modules

> **Tip:** The Terraform modules are provided as examples. They are not required for > upgrading Materialize.
Guide Description
Upgrade on AWS (Legacy Terraform) Uses legacy Terraform module to deploy Materialize to AWS Elastic Kubernetes Service (EKS).
Upgrade on Azure (Legacy Terraform) Uses legacy Terraform module to deploy Materialize to Azure Kubernetes Service (AKS).
Upgrade on GCP (Legacy Terraform) Uses legacy Terraform module to deploy Materialize to Google Kubernetes Engine (GKE).
## Upgrading the Helm Chart and Materialize Operator > **Important:** When upgrading Materialize, always upgrade the Helm Chart and Materialize > Operator first. ### Update the Helm Chart repository To update your Materialize Helm Chart repository: ```shell helm repo update materialize ``` View the available chart versions: ```shell helm search repo materialize/materialize-operator --versions ``` ### Upgrade your Materialize Operator The Materialize Kubernetes Operator is deployed via Helm and can be updated through standard `helm upgrade` command: ```mzsql helm upgrade -n materialize/materialize-operator \ --version \ -f ``` | Syntax element | Description | | --- | --- | | `` | The namespace where the Operator is running. (e.g., `materialize`) | | `` | The release name. You can use `helm list -n ` to find your release name. | | `` | The upgrade version. | | `` | The name of your customization file, if using. If you are configuring using `\-\-set key=value` options, include them as well. | You can use `helm list` to find your release name. For example, if your Operator is running in the namespace `materialize`, run `helm list`: ```shell helm list -n materialize ``` Retrieve the name associated with the `materialize-operator` **CHART**; for example, `my-demo` in the following helm list: ```none NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION my-demo materialize 1 2025-12-08 11:39:50.185976 -0500 EST deployed materialize-operator-v26.1.0 v26.1.0 ``` Then, to upgrade: ```shell helm upgrade -n materialize my-demo materialize/operator \ -f my-values.yaml \ --version v26.17.1 ``` ## Upgrading Materialize Instances **After** you have upgraded your Materialize Operator, upgrade your Materialize instance(s) to the **APP Version** of the Operator. To find the version of your currently deployed Materialize Operator: ```shell helm list -n materialize ``` You will use the returned **App Version** for the updated `environmentdImageRef` value. Specifically, for your Materialize instance(s), set `environmentdImageRef` value to use the new version: ``` spec: environmentdImageRef: docker.io/materialize/environmentd: ``` To minimize unexpected downtime and avoid connection drops at critical periods for your application, the upgrade process involves two steps: - First, stage the changes (update the `environmentdImageRef` with the new version) to the Materialize custom resource. The Operator watches for changes but does not automatically roll out the changes. - Second, roll out the changes by specifying a new UUID for `requestRollout`. ### Stage the Materialize instance version change To stage the Materialize instances version upgrade, update the `environmentdImageRef` field in the Materialize custom resource spec to the compatible version of your currently deployed Materialize Operator. To stage, but **not** rollout, the Materialize instance version upgrade, you can use the `kubectl patch` command; for example, if the **App Version** is v26.17.1: ```shell kubectl patch materialize \ -n \ --type='merge' \ -p "{\"spec\": {\"environmentdImageRef\": \"docker.io/materialize/environmentd:v26.17.1\"}}" ``` > **Note:** Until you specify a new `requestRollout`, the Operator watches for updates but > does not roll out the changes. ### Applying the changes via `requestRollout` To apply chang Materialize instance upgrade, you must update the `requestRollout` field in the Materialize custom resource spec to a new UUID. Be sure to consult the [Rollout Configurations](#rollout-configuration) to ensure you've selected the correct rollout behavior. ```shell # Then trigger the rollout with a new UUID kubectl patch materialize \ -n \ --type='merge' \ -p "{\"spec\": {\"requestRollout\": \"$(uuidgen)\"}}" ``` ### Staging and applying in a single command Although separating the staging and rollout of the changes into two steps can minimize unexpected downtime and avoid connection drops at critical periods, you can, if preferred, combine both operations in a single command ```shell kubectl patch materialize \ -n materialize-environment \ --type='merge' \ -p "{\"spec\": {\"environmentdImageRef\": \"docker.io/materialize/environmentd:v26.17.1\", \"requestRollout\": \"$(uuidgen)\"}}" ``` #### Using YAML Definition Alternatively, you can update your Materialize custom resource definition directly: ```yaml apiVersion: materialize.cloud/v1alpha1 kind: Materialize metadata: name: 12345678-1234-1234-1234-123456789012 namespace: materialize-environment spec: environmentdImageRef: materialize/environmentd:v26.17.1 # Update version as needed requestRollout: 22222222-2222-2222-2222-222222222222 # Use a new UUID forceRollout: 33333333-3333-3333-3333-333333333333 # Optional: for forced rollouts inPlaceRollout: false # In Place rollout is deprecated and ignored. Please use rolloutStrategy rolloutStrategy: WaitUntilReady # The mechanism to use when rolling out the new version. Can be WaitUntilReady or ImmediatelyPromoteCausingDowntime backendSecretName: materialize-backend ``` Apply the updated definition: ```shell kubectl apply -f materialize.yaml ``` ## Rollout Configuration ### `requestRollout` Specify a new `UUID` value for the `requestRollout` to roll out the changes to the Materialize instance. > **Note:** `requestRollout` without the `forcedRollout` field only rolls out if changes > exist to the Materialize instance. To roll out even if there are no changes to > the instance, use with `forcedRollouts`. ```shell # Only rolls out if there are changes kubectl patch materialize \ -n \ --type='merge' \ -p "{\"spec\": {\"requestRollout\": \"$(uuidgen)\"}}" ``` #### `requestRollout` with `forcedRollouts` Specify a new `UUID` value for `forcedRollout` to roll out even when there are no changes to the instance. Use `forcedRollout` with `requestRollout`. ```shell kubectl patch materialize \ -n materialize-environment \ --type='merge' \ -p "{\"spec\": {\"requestRollout\": \"$(uuidgen)\", \"forceRollout\": \"$(uuidgen)\"}}" ``` ### Rollout strategies Rollout strategies control how Materialize transitions from the current generation to a new generation during an upgrade. The behavior of the new version rollout follows your `rolloutStrategy` setting. #### *WaitUntilReady* - ***Default*** `WaitUntilReady` creates a new generation of pods and automatically cuts over to them as soon as they catch up to the old generation and become `ReadyToPromote`. This strategy temporarily doubles the required resources to run Materialize. > **Warning:** `WaitUntilReady` waits up to 72 hours (configurable by the `with_0dt_deployment_max_wait` flag) for the new pods to become ready. If the promotion has not occurred by then, the new pods are automatically promoted. #### *ImmediatelyPromoteCausingDowntime* > **Warning:** Using the `ImmediatelyPromoteCausingDowntime` rollout flag will cause downtime. `ImmediatelyPromoteCausingDowntime` tears down the prior generation, and immediately promotes the new generation without waiting for it to hydrate. This causes downtime until the new generation has hydrated. However, it does not require additional resources. #### *ManuallyPromote* `ManuallyPromote` allows you to choose when to promote the new generation. This means you can time the promotion for periods when load is low, minimizing the impact of potential downtime for any clients connected to Materialize. This strategy temporarily doubles the required resources to run Materialize. To minimize downtime, wait until the new generation has fully hydrated and caught up to the prior generation before promoting. To check hydration status, inspect the `UpToDate` condition in the Materialize resource status. When hydration completes, the condition will be `ReadyToPromote`. To promote, update the `forcePromote` field to match the `requestRollout` field in the Materialize spec. If you need to promote before hydration completes, you can set `forcePromote` immediately, but clients may experience downtime. > **Warning:** Leaving a new generation unpromoted for over 6 hours may cause downtime. **Do not leave new generations unpromoted indefinitely**. They should either be promoted or canceled. New generations open a read hold on the metadata database that prevents compaction. This hold is only released when the generation is promoted or canceled. If left open too long, promoting or canceling can trigger a spike in deletion load on the metadata database, potentially causing downtime. It is not recommended to leave generations unpromoted for over 6 hours. #### *inPlaceRollout* - ***Deprecated*** The setting is ignored. ## Verifying the Upgrade After initiating the rollout, you can monitor the status field of the Materialize custom resource to check on the upgrade. ```shell # 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 ``` ## Cancelling the Upgrade You may want to cancel an in-progress rollout if the upgrade has failed. This may be indicated by new pods not being healthy. Before cancelling, verify that the upgrade has not already completed by checking that the deploy generation (found via `status.activeGeneration`) is still the one from before the upgrade. Once an upgrade has already happened, you cannot revert using this method. To cancel an in-progress rollout and revert to the last completed rollout state, first retrieve the last rollout request ID from your Materialize CR: ```shell kubectl get materialize -n materialize-environment -o jsonpath='{.status.lastCompletedRolloutRequest}' ``` Then, set the `requestRollout` back to this value: ```shell kubectl patch materialize \ -n materialize-environment \ --type='merge' \ -p "{\"spec\": {\"requestRollout\": \"\"}}" ``` ## Version Specific Upgrade Notes ### Upgrading to `v26.1` and later versions
  • To upgrade to v26.1 or future versions, you must first upgrade to v26.0
### Upgrading to `v26.0`

  • Upgrading to v26.0.0 is a major version upgrade. To upgrade to v26.0 from v25.2.X or v25.1, you must first upgrade to v25.2.16 and then upgrade to v26.0.0.

  • For upgrades, the inPlaceRollout setting has been deprecated and will be ignored. Instead, use the new setting rolloutStrategy to specify either:

    • WaitUntilReady (Default)
    • ImmediatelyPromoteCausingDowntime

    For more information, see rolloutStrategy.

  • New requirements were introduced for license keys. To upgrade, you will first need to add a license key to the backendSecret used in the spec for your Materialize resource.

    See License key for details on getting your license key.

  • Swap is now enabled by default. Swap reduces the memory required to operate Materialize and improves cost efficiency. Upgrading to v26.0 requires some preparation to ensure Kubernetes nodes are labeled and configured correctly. As such:

    • If you are using the Materialize-provided Terraforms, upgrade to version v0.6.1 of the Terraform.

    • If you are not using a Materialize-provided Terraform, refer to Prepare for swap and upgrade to v26.0.

### Upgrading between minor versions less than `v26` - Prior to `v26`, you must upgrade at most one minor version at a time. For example, upgrading from `v25.1.5` to `v25.2.16` is permitted. ## See also - [Materialize Operator Configuration](/self-managed-deployments/operator-configuration/) - [Materialize CRD Field Descriptions](/self-managed-deployments/materialize-crd-field-descriptions/) - [Troubleshooting](/self-managed-deployments/troubleshooting/)