Upgrade on AWS

View as Markdown

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 for your target version:
Always upgrade the Materialize Operator before upgrading the Materialize instances.

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.

NOTE: Downgrading is not supported.

Prerequisites

Required Tools

Upgrade process

! Important: The following procedure performs a rolling upgrade, where both the old and new Materialize instances are running before the old instances are removed. When performing a rolling upgrade, ensure you have enough resources to support having both the old and new Materialize instances running.

Step 1: Update TF module source version

Update each module’s source to point to the desired release tag, substituting <RELEASE_TAG> in the code block below with your tag version:

! Important:

The following code block is not comprehensive. Only the core modules and their dependency chain are shown below.

If your configuration includes additional modules (networking, storage, database, node pools, etc.) provided by Materialize, update those to the same release tag as well.

module "eks" {
  source = "github.com/MaterializeInc/materialize-terraform-self-managed//aws/modules/eks?ref=<RELEASE_TAG>"
  # ... your existing configuration ...
}

module "cert_manager" {
  source = "github.com/MaterializeInc/materialize-terraform-self-managed//kubernetes/modules/cert-manager?ref=<RELEASE_TAG>"
  # ... your existing configuration ...

  # Your configuration may have additional dependencies here.
  depends_on = [module.eks]
}

module "operator" {
  source = "github.com/MaterializeInc/materialize-terraform-self-managed//aws/modules/operator?ref=<RELEASE_TAG>"
  # ... your existing configuration ...

  # Your configuration may have additional dependencies here.
  depends_on = [module.cert_manager]
}

module "materialize_instance" {
  source = "github.com/MaterializeInc/materialize-terraform-self-managed//kubernetes/modules/materialize-instance?ref=<RELEASE_TAG>"
  # ... your existing configuration ...

  # Your configuration may have additional dependencies here.
  depends_on = [module.operator]
}

# Update the source of any additional Materialize-provided modules to the same release tag

Step 2: Explicitly request rollout if using v1alpha1

v1alpha1 is the default CRD version for a Materialize instance. With v1alpha1, instance rollouts require manually rotating a UUID.

To check the CRD version of the Materialize manifest that was applied, run the following:

terraform state show 'module.materialize_instance.kubectl_manifest.materialize_instance' \
  | grep -iE 'api_?version|kind'

If you are using v1, skip to the Apply the updated TF step.
If you are using v1alpha1, you need to update your terraform.tfvars file to set the request_rollout variable to a new UUID value, substituting the example value in the code block below with a UUID you generate (for example, with uuidgen):
```
# ...
# ...
request_rollout = "DBB4FCEC-1837-44F6-9CF2-3894678DD8D5" # ONLY for v1alpha1
```

Step 3: Apply the updated TF

Initialize the Terraform directory to download the required providers and modules:
```
terraform init
```
Review the execution plan before applying. In particular, check for any resources Terraform plans to destroy and recreate (shown as -/+ in the plan), especially stateful resources such as your cluster, storage, and database:
```
terraform plan
```
After reviewing the plan, apply the Terraform configuration.
```
terraform apply
```

Step 4: Verify the upgrade

Configure kubectl to connect to your EKS cluster, replacing <your-region> with the region of your cluster (found in your terraform.tfvars; 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>

NOTE: terraform apply returns once the Materialize custom resource is updated. The Operator then rolls out the new generation asynchronously, so the new environmentd pods may take a few minutes to become ready.

Check the status of the materialize namespace:
```
kubectl -n materialize get all
```
Check the status of the materialize-environment namespace:
```
kubectl -n materialize-environment get all
```
Once a new environmentd is up (may take a few minutes), confirm the running environmentd version matches the version you upgraded to. Check the Image field in the pod description.
```
kubectl -n materialize-environment describe pod -l app=environmentd
```

If you run into an error during the upgrade, refer to the Troubleshooting.