Upgrade on AWS

The following tutorial upgrades your Materialize deployment running on AWS Elastic Kubernetes Service (EKS). The tutorial assumes you have installed the example on Install on AWS.

Upgrade guidelines

When upgrading:

• Always check the version specific upgrade notes.

• Always upgrade the Materialize Operator before upgrading the Materialize instances.

Prerequisites

Required Tools

• Terraform
• AWS CLI
• kubectl
• Helm 3.2.0+

Upgrade process

Step 1: Set up

1. Open a Terminal window.

2. Configure AWS CLI with your AWS credentials. For details, see the AWS documentation.

3. Go to the Terraform directory for your Materialize deployment. For example, if you deployed from the aws/examples/simple directory:

   cd materialize-terraform-self-managed/aws/examples/simple
   

4. Ensure your AWS CLI is configured with the appropriate profile, substitute <your-aws-profile> with the profile to use:

   # Set your AWS profile for the session
   export AWS_PROFILE=<your-aws-profile>
   

5. Configure kubectl to connect to your EKS cluster, replacing:

   • <your-eks-cluster-name> with the your cluster name; i.e., the eks_cluster_name in the Terraform output. For the sample example, your cluster name has the form {prefix_name}-eks; e.g., simple-demo-eks.

   • <your-region> with the region of your cluster. Your region can be found in your terraform.tfvars file; e.g., us-east-1.

   # aws eks update-kubeconfig --name <your-eks-cluster-name> --region <your-region>
   aws eks update-kubeconfig --name $(terraform output -raw eks_cluster_name) --region <your-region>
   

   To verify that you have configured correctly, run the following command:

   kubectl get nodes
   

   For help with kubectl commands, see kubectl Quick reference.

Step 2: Update the Helm Chart

To update your Materialize Helm Chart repository:

1. Update the Helm repo:

   helm repo update materialize
   

2. View the available chart versions:

   helm search repo materialize/materialize-operator --versions
   

Step 3: Upgrade the Materialize Operator

1. Use helm list to find the release name. The sample example deployment using the unified Terraform module deploys the Operator in the materialize namespace.

   helm list -n materialize
   

   Retrieve the release name (corresponds to the name_prefix variable specified in your terraform.tfvars) associated with the materialize-operator CHART; for example, simple-demo in the following output:

   NAME    	    NAMESPACE    REVISION   UPDATED                               STATUS     CHART                         APP VERSION
   simple-demo  materialize  1         2025-12-08 11:39:50.185976 -0500 EST   deployed  materialize-operator-v26.1.0  v26.1.0
   

2. Export your current values to a file to preserve any custom settings:

   helm get values -n materialize simple-demo -o yaml > my-values.yaml
   

3. Upgrade your Operator. For example, the following upgrades the Operator to v26.1.1:

   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.

   helm upgrade -n materialize simple-demo materialize/materialize-operator  \
     -f my-values.yaml \
     --version v26.1.1
   

4. Verify that the Operator is running:

   kubectl -n materialize get all
   

5. Get the APP VERSION of the Operator.

   helm list -n materialize
   

   The APP VERSION will be the value that you will use for upgrading Materialize instances.

Step 4: Upgrading Materialize Instances

After you have upgraded your Materialize Operator, upgrade your Materialize instance(s) to the APP Version of the Operator. When upgrading Materialize Instances versions, changes are not automatically rolled out by the Operator in order to minimize unexpected downtime and avoid connection drops at critical periods. Instead, the upgrade process involves two steps:

• First, staging the version change to the Materialize custom resource.
• Second, rolling out the changes via a requestRollout flag.

1. Find the name of the Materialize instance to upgrade. The sample example deployment using the unified Terraform module deploys the Materialie instance in thematerialize-environment namespace.

   kubectl get materialize -n  materialize-environment
   

   In the example deployment, the name of the instance is main.

   NAME
   main
   

2. Stage, but not rollout, the Materialize instance version upgrade.

   kubectl patch materialize main\
     -n materialize-environment \
     --type='merge' \
     -p "{\"spec\": {\"environmentdImageRef\": \"docker.io/materialize/environmentd:v26.1.1\"}}"
   

3. Rollout the Materialize instance version change.

   kubectl patch materialize main \
     -n materialize-environment \
     --type='merge' \
     -p "{\"spec\": {\"requestRollout\": \"$(uuidgen)\"}}"
   

4. Verify the upgrade by checking the environmentd events:

   kubectl -n materialize-environment describe pod -l app=environmentd
   

See also

• Materialize Operator Configuration
• Materialize CRD Field Descriptions
• Troubleshooting