# Upgrade on GCP Upgrade Materialize on GCP using the new Terraform module. The following tutorial upgrades your Materialize deployment running on Google Kubernetes Engine (GKE). The tutorial assumes you have installed the example on [Install on GCP](/self-managed-deployments/installation/install-on-gcp/). ## Upgrade guidelines

When upgrading:

Always check the version specific upgrade notes.
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 - [Terraform](https://developer.hashicorp.com/terraform/install?product_intent=terraform) - [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) - [kubectl](https://kubernetes.io/docs/tasks/tools/) - [Helm 3.2.0+](https://helm.sh/docs/intro/install/) ## 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: Set up 1. Open a Terminal window. 1. Configure Google Cloud CLI with your GCP credentials. For details, see the [Google Cloud documentation](https://cloud.google.com/sdk/docs/initializing). 1. Go to the Terraform directory for your Materialize deployment. For example, if you deployed from the `gcp/examples/simple` directory: ```bash cd materialize-terraform-self-managed/gcp/examples/simple ``` 1. Configure `kubectl` to connect to your GKE cluster, replacing: - `` with your cluster name; i.e., the `gke_cluster_name` in the Terraform output. For the sample example, your cluster name has the form `-gke`; e.g., `simple-demo-gke` - `` with your cluster location; i.e., the `gke_cluster_location` in the Terraform output. Your region can also be found in your `terraform.tfvars` file. - `` with your GCP project ID. ```bash # gcloud container clusters get-credentials --region --project gcloud container clusters get-credentials $(terraform output -raw gke_cluster_name) \ --region $(terraform output -raw gke_cluster_location) \ --project ``` To verify that you have configured correctly, run the following command: ```bash kubectl get nodes ``` For help with `kubectl` commands, see [kubectl Quick reference](https://kubernetes.io/docs/reference/kubectl/quick-reference/). ### Step 2: Update the Helm Chart > **Important:** Always upgrade the Materialize Operator before > upgrading the Materialize instances.

To update your Materialize Helm Chart repository:

Update the Helm repo:
```
helm repo update materialize
```

View the available chart versions:

helm search repo materialize/materialize-operator --versions

### Step 3: Upgrade the Materialize Operator > **Important:** Always upgrade the Materialize Operator before > upgrading the Materialize instances.

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
```

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

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

Upgrade your Operator. For example, the following upgrades the Operator to v26.17.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.17.1
```
Verify that the Operator is running:
```
kubectl -n materialize get all
```
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 > **Important:** Always upgrade the Materialize Operator before > upgrading the 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.

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
```

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.17.1\"}}"

Rollout the Materialize instance version change.

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

Verify the upgrade by checking the environmentd events:

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

## 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/)