Upgrade on AWS

To upgrade your Materialize instances, upgrade the Materialize operator first and then the Materialize instances. The following tutorial upgrades your Materialize deployment running on AWS Elastic Kubernetes Service (EKS).

The tutorial assumes you have installed Materialize on AWS Elastic Kubernetes Service (EKS) using the instructions on Install on AWS (either from the examples/simple directory or the root).

Version compatibility

Prerequisites

Terraform

If you don’t have Terraform installed, install Terraform.

AWS CLI

If you do not have the AWS CLI installed, install. For details, see the AWS documentation.

kubectl

If you do not have kubectl, install. See the Amazon EKS: install kubectl documentation for details.

Helm 3.2.0+

If you do not have Helm 3.2.0+, install. For details, see the Helm documentation.

Procedure

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 examples/simple directory:

   cd terraform-aws-materialize/examples/simple
   

4. Optional. You may need to update your fork of the Terraform module to upgrade.

   💡 Tip:

   If upgrading from a deployment that was set up using an earlier version of the Terraform modules, additional considerations may apply when using an updated Terraform modules to your existing deployments.

   See Materialize on AWS releases for notable changes.

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

   • <your-eks-cluster-name> with the name of your EKS cluster. Your cluster name has the form {namespace}-{environment}-eks; e.g., my-demo-dev-eks.

   • <your-region> with the region of your EKS cluster. The simple example uses us-east-1.

   aws eks update-kubeconfig --name <your-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.

6. Back up your terraform.tfvars file.

   cp terraform.tfvars original_terraform.tfvars
   

7. Update the terraform.tfvars to set the Materialize Operator version:

   Variable	Description
   operator_version	New Materialize Operator version. If the variable does not exist, add the variable and set to the new version. If the variable exists, update the value to the new version.

   ##... Existing content not shown for brevity
   ##... Leave the existing variables unchanged
   operator_version="v25.2.13"  # Set to the desired operator version
   

8. Initialize the terraform directory.

   terraform init
   

9. Run terraform plan with both the terraform.tfvars and your mz_instances.tfvars files and review the changes to be made.

   terraform plan -var-file=terraform.tfvars -var-file=mz_instances.tfvars
   

   The plan should show the changes to be made for the materialize_operator.

10. If you are satisfied with the changes, apply.

    terraform apply -var-file=terraform.tfvars -var-file=mz_instances.tfvars
    

    To approve the changes and apply, enter yes.

    Upon successful completion, you should see output with a summary of changes.

11. Verify that the operator is running:

    kubectl -n materialize get all
    

    Verify the operator upgrade by checking its events:

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

    • The Containers section should show the --helm-chart-version argument set to the new version.

    • The Events section should list that the new version of the orchestratord have been pulled.

12. Back up your mz_instances.tfvars file.

    cp mz_instances.tfvars original_mz_instances.tfvars
    

13. Update the mz_instances.tfvars to specify the upgrade variables for each instance:

    Variable	Description
    create_database	Set to false.
    environmentd_version	New Materialize instance version.
    request_rollout or force_rollout	A new UUID string. Can be generated with uuidgen. request_rollout triggers a rollout only if changes exist. force_rollout triggers a rollout even if no changes exist.
    inPlaceRollout	Set to false to perform a rolling upgrade. For rolling upgrades, ensure you have enough resources to support having both the old and new Materialize instances running during the upgrade.

    For example, the following instance specifies:

    • a create_database of false,
    • an inPlaceRollout of false,
    • an environmentd_version of "v0.147.18", and
    • a request_rollout of "22222222-2222-2222-2222-222222222222".

    materialize_instances = [
        {
          name           = "demo"
          namespace      = "materialize-environment"
          database_name  = "demo_db"
          cpu_request    = "1"
          memory_request = "2Gi"
          memory_limit   = "2Gi"
          create_database = false
          environmentd_version = "v0.147.18"
          inPlaceRollout: false                                   # When false, performs a rolling upgrade rather than in-place
          requestRollout: 22222222-2222-2222-2222-222222222222    # Enter a new UUID
        }
    ]
    

    WARNING! Please consult the Materialize team before setting inPlaceRollout to true and performing an in-place rollout. In almost all cases a rolling upgrade is preferred.

14. Run terraform plan with both the terraform.tfvars and your mz_instances.tfvars files and review the changes to be made.

    terraform plan -var-file=terraform.tfvars -var-file=mz_instances.tfvars
    

    The plan should show the changes to be made for the Materialize instance.

15. If you are satisfied with the changes, apply.

    terraform apply -var-file=terraform.tfvars -var-file=mz_instances.tfvars
    

    To approve the changes and apply, enter yes.

    Upon successful completion, you should see output with a summary of changes.

16. Verify that the components are running after the upgrade:

    kubectl -n materialize-environment get all
    

    Verify upgrade by checking the balancerd events:

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

    The Events section should list that the new version of the balancerd have been pulled.

    Verify the upgrade by checking the environmentd events:

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

    The Events section should list that the new version of the environmentd have been pulled.

17. Open the Materialize Console. The Console should display the new version.