Upgrade on GCP

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.

Upgrade guidelines

When upgrading:

• Always check the version-specific upgrade notes for your target version:

  • Upgrading to v26.30 and later versions
  • Upgrading to v26.1 and later versions
  • Upgrading to v26.0
  • Upgrading between minor versions less than v26

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

Prerequisites

Required Tools

• Terraform
• Google Cloud CLI
• kubectl

Upgrade process

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:

module "gke" {
  source = "github.com/MaterializeInc/materialize-terraform-self-managed//gcp/modules/gke?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.gke]
}

module "operator" {
  source = "github.com/MaterializeInc/materialize-terraform-self-managed//gcp/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 the Materialize Helm chart. The Terraform modules default to v1 starting in v4.0.0. 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

1. Initialize the Terraform directory to download the required providers and modules:

   terraform init
   

2. 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
   

3. After reviewing the plan, apply the Terraform configuration.

   terraform apply
   

Step 4: Verify the upgrade

Configure kubectl to connect to your GKE cluster, replacing <your-project-id> with your GCP project ID:

# gcloud container clusters get-credentials <your-gke-cluster-name> --region <your-region> --project <your-project-id>
gcloud container clusters get-credentials $(terraform output -raw gke_cluster_name) \
 --region $(terraform output -raw gke_cluster_location) \
 --project <your-project-id>

1. Check the status of the materialize namespace:

   kubectl -n materialize get all
   

2. Check the status of the materialize-environment namespace:

   kubectl -n materialize-environment get all
   

3. 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.

Enable the monitoring stack

The Terraform modules can install a monitoring stack — Grafana, Thanos, Loki, Grafana Alloy, and Alertmanager — alongside your deployment, with the Materialize dashboards pre-installed. You can turn it on during an upgrade, in the same terraform apply as the version bump.

The stack below arrived in TF v10.0.0, replacing the earlier single Prometheus and Grafana. TF v10.1.0 then added durable state for Grafana and a load balancer to reach it on.

If you use the example configuration

Set the following in your terraform.tfvars:

enable_observability = true

If you instantiate the modules yourself

1. Add the monitoring module, using the same release tag as the rest of your modules:

   module "monitoring" {
     source = "github.com/MaterializeInc/materialize-terraform-self-managed//gcp/modules/monitoring?ref=<RELEASE_TAG>"
   
     prefix     = var.name_prefix
     project_id = var.project_id
     region     = var.region
   
     namespace = "monitoring"
     # The operator module already creates this namespace.
     create_namespace = false
   
     materialize_instance_namespace = "materialize-environment"
     materialize_operator_namespace = "materialize"
   
     # Grafana's own state. Omit to leave Grafana on SQLite.
     grafana_database = {
       network_id = module.networking.network_id
     }
   
     # Reach Grafana without port forwarding. Omit to keep it on ClusterIP.
     grafana_load_balancer = {
       ingress_cidr_blocks = var.ingress_cidr_blocks
     }
   
     depends_on = [module.operator]
   }
   

2. Turn on the operator’s scrape annotations so its pods are collected:

   module "operator" {
     # ...
     helm_values = {
       observability = {
         enabled = true
         prometheus = {
           scrapeAnnotations = {
             enabled = true
           }
         }
       }
     }
   }
   

What this creates

Applying the above adds Cloud Storage buckets for metrics and logs, and — from TF v10.1.0 — a db-f1-micro Cloud SQL instance for Grafana’s own state and an internal load balancer to reach Grafana on. The database and the load balancer are both billable.

For accessing Grafana, pointing the stack at a database you already run, sizing profiles, and retention, see Grafana.

See also

• Materialize Operator Configuration
• Materialize CRD Field Descriptions
• Troubleshooting