MaterializeInc · kay-kim · Nov 18, 2025 · Nov 4, 2025 · Nov 17, 2025 · Nov 18, 2025
@@ -34,7 +34,7 @@ $rem-scale: 0.585;
     --milli: #{rem(2)};
     --xx-small: #{rem(2.5)};
     --x-small: #{rem(3)};
-    --small: #{rem(4)};
+    --small: #{rem(4.5)};
     --medium: #{rem(5)};
     --large: #{rem(6)};
 

@@ -10,10 +10,10 @@
 .content-wrapper {
     display: flex;
     justify-content: center;
-    padding-top: var(--nav-height);
+    padding-top: calc(var(--nav-height) + var(--small));
 
     @media(max-width: 800px) {
-        padding-top: calc(var(--nav-height) + var(--xx-small));
+        padding-top: calc(var(--nav-height) + var(--small));
     }
 
     @media(max-width: 380px) {
@@ -139,7 +139,7 @@ table.inline-headings {
         z-index: 100;
         top: var(--nav-height);
         left: 0;
-        height: calc(100vh - var(--nav-height));
+        height: calc(120vh - var(--nav-height));
         border-right: 1px solid var(--divider-light);
         transform: translateX(-100%);
         transition: all .2s ease-out;
@@ -193,6 +193,7 @@ table.inline-headings {
     @media(max-width: 850px) {
         padding-bottom: var(--large);
         height: calc(100vh - var(--nav-height));
+        margin-top: 80px;
     }
 
     a {

@@ -149,7 +149,7 @@
 
 button.show-topics {
     display: none;
-    margin: 0 0 var(--small) !important;
+    margin: var(--small) 0 var(--small) !important;
     text-align: left;
     font-weight: 300;
     font-size: var(--base);
@@ -172,6 +172,7 @@ button.close-topics {
     justify-content: center;
     align-items: center;
     top: 0;
+    margin-top: 80px;
     right: 0;
     transform: translateX(50%) translateY(50%);
     background: var(--bg);

@@ -7,7 +7,7 @@ disableKinds = ['taxonomy']
 
 [params]
 repo = "//github.com/MaterializeInc/materialize"
-bannerMessage = ""
+bannerMessage = "❗This is the v25.2 Self-Managed Materialize documentation. For the latest docs, go to https://materialize.com/docs/.<br>👉 **Note**: Before upgrading from **v25.2** to **v26.0**, [upgrade first to version **25.2.15**](/release-notes/#v25215). Afterwards, you can [upgrade to v26.0](https://materialize.com/docs/installation/#upgrade)."
 bannerLink = ""
 
 [frontmatter]

@@ -1,6 +1,6 @@
 ---
 title: "Self-managed Materialize"
-description: ""
+description: "Documentation for Self-Managed Materialize v25.2"
 aliases:
   - /self-hosted/
   - /cloud_releases/

@@ -1,8 +1,7 @@
 ---
-title: "Installation"
-description: "Installation guides for self-managed Materialize."
+title: "Install/Upgrade (Self-Managed)"
+description: "Installation and upgrade guides for Self-Managed Materialize."
 disable_list: true
-
 menu:
   main:
     identifier: "installation"
@@ -15,54 +14,196 @@ or on a cloud provider. Self-managed Materialize requires:
 
 {{% self-managed/materialize-components-list %}}
 
-## Install locally
+## Install
 
-{{< multilinkbox >}}
-{{< linkbox title="Using Docker/kind" icon="materialize">}}
-[Install locally on kind](/installation/install-on-local-kind/)
-{{</ linkbox >}}
-{{< linkbox  title="Using Docker/minikube" icon="materialize">}}
-[Install locally on minikube](/installation/install-on-local-minikube/)
-{{</ linkbox >}}
-{{</ multilinkbox >}}
+### Installation guides
 
-## Install on cloud provider
+The following installation guides are available:
 
-{{< multilinkbox >}}
+|               | Notes  |
+| ------------- | -------|
+| [Install locally on kind](/installation/install-on-local-kind/) |
+| [Install locally on minikube](/installation/install-on-local-minikube/) |
+| [Deploy Materialize to AWS Elastic Kubernetes Service (EKS)](/installation/install-on-aws/) | Uses Materialize provided Terraform |
+| [Deploy Materialize to Azure Kubernetes Service (AKS)](/installation/install-on-azure/) | Uses Materialize provided Terraform |
+| [Deploy Materialize to Google Kubernetes Engine (GKE)](/installation/install-on-gcp/) | Uses Materialize provided Terraform |
 
-{{< linkbox title="[Install on AWS](/installation/install-on-aws/)" icon="materialize">}}
+See also:
+- [AWS Deployment
+  guidelines](/installation/install-on-aws/appendix-deployment-guidelines/#recommended-instance-types)
+- [GCP Deployment
+  guidelines](/installation/install-on-gcp/appendix-deployment-guidelines/#recommended-instance-types)
+- [Azure Deployment
+  guidelines](/installation/install-on-azure/appendix-deployment-guidelines/#recommended-instance-types)
 
-[Deploy Materialize to AWS Elastic Kubernetes Service (EKS)](/installation/install-on-aws/)
 
-{{</ linkbox >}}
+## Upgrade
 
-{{< linkbox title="[Install on Azure](/installation/install-on-azure/)" icon="materialize">}}
+{{< include-md file="shared-content/general-rules-for-upgrades.md" >}}
 
-[Deploy Materialize to Azure Kubernetes Service (AKS)](/installation/install-on-azure/)
+### Upgrade guides
 
-{{</ linkbox >}}
+The following upgrade guides are available:
 
-{{< linkbox icon="materialize" title="[Install on GCP](/installation/install-on-gcp/)" >}}
+|               | Notes  |
+| ------------- | -------|
+| [Upgrade on kind](/installation/install-on-local-kind/upgrade-on-local-kind/) |
+| [Upgrade on AWS](/installation/install-on-aws/upgrade-on-aws/) | Uses Materialize provided Terraform |
+| [Upgrade on Azure Kubernetes Service (AKS)](/installation/install-on-azure/upgrade-on-azure/) | Uses Materialize provided Terraform |
+| [Upgrade on Google Kubernetes Engine (GKE)](/installation/install-on-gcp/upgrade-on-gcp/) | Uses Materialize provided Terraform |
 
-[Deploy Materialize to Google Kubernetes Engine (GKE)](/installation/install-on-gcp/)
-{{</ linkbox >}}
 
-{{</ multilinkbox >}}
+### General notes for upgrades
 
-See also:
+The following provides some general notes for upgrades. For specific examples,
+see the [Upgrade guides](#upgrade-guides)
 
-- [AWS Deployment
-  guidelines](/installation/install-on-aws/appendix-deployment-guidelines/#recommended-instance-types)
 
-- [GCP Deployment
-  guidelines](/installation/install-on-gcp/appendix-deployment-guidelines/#recommended-instance-types)
+#### Upgrading the Helm Chart and Kubernetes Operator
 
-- [Azure Deployment
-  guidelines](/installation/install-on-azure/appendix-deployment-guidelines/#recommended-instance-types)
+{{< important >}}
+
+When upgrading Materialize, always upgrade the operator first.
+
+{{</ important >}}
+
+The Materialize Kubernetes operator is deployed via Helm and can be updated through standard Helm upgrade commands.
+
+```shell
+helm upgrade my-materialize-operator materialize/misc/helm-charts/operator
+```
+
+If you have custom values, make sure to include your values file:
+
+```shell
+helm upgrade my-materialize-operator materialize/misc/helm-charts/operator -f my-values.yaml
+```
+
+#### Upgrading Materialize Instances
+
+In order to minimize unexpected downtime and avoid connection drops at critical
+periods for your application, changes are not immediately and automatically
+rolled out by the Operator. Instead, the upgrade process involves two steps:
+- First, staging spec changes to the Materialize custom resource.
+- Second, applying the changes via a `requestRollout`.
+
+When upgrading your Materialize instances, you'll first want to update the `environmentdImageRef` field in the Materialize custom resource spec.
+
+##### Updating the `environmentdImageRef`
+To find a compatible version with your currently deployed Materialize operator, check the `appVersion` in the Helm repository.
+
+```shell
+helm list -n materialize
+```
+
+Using the returned version, we can construct an image ref.
+We always recommend using the official Materialize image repository
+`docker.io/materialize/environmentd`.
+
+```
+environmentdImageRef: docker.io/materialize/environmentd:v0.147.20
+```
+
+The following is an example of how to patch the version.
+```shell
+# For version updates, first update the image reference
+kubectl patch materialize <instance-name> \
+  -n <materialize-instance-namespace> \
+  --type='merge' \
+  -p "{\"spec\": {\"environmentdImageRef\": \"materialize/environmentd:v0.147.20\"}}"
+```
+
+##### Applying the changes via `requestRollout`
+
+To apply changes and kick off the Materialize instance upgrade, you must update the `requestRollout` field in the Materialize custom resource spec to a new UUID.
+Be sure to consult the [Rollout Configurations](#rollout-configuration) to ensure you've selected the correct rollout behavior.
+```shell
+# Then trigger the rollout with a new UUID
+kubectl patch materialize <instance-name> \
+  -n <materialize-instance-namespace> \
+  --type='merge' \
+  -p "{\"spec\": {\"requestRollout\": \"$(uuidgen)\"}}"
+```
+
+
+It is possible to combine both operations in a single command if preferred:
+
+```shell
+kubectl patch materialize <instance-name> \
+  -n materialize-environment \
+  --type='merge' \
+  -p "{\"spec\": {\"environmentdImageRef\": \"materialize/environmentd:v0.147.20\", \"requestRollout\": \"$(uuidgen)\"}}"
+```
+
+##### Using YAML Definition
+
+Alternatively, you can update your Materialize custom resource definition directly:
+
+```yaml
+apiVersion: materialize.cloud/v1alpha1
+kind: Materialize
+metadata:
+  name: 12345678-1234-1234-1234-123456789012
+  namespace: materialize-environment
+spec:
+  environmentdImageRef: materialize/environmentd:v0.147.20 # Update version as needed
+  requestRollout: 22222222-2222-2222-2222-222222222222    # Generate new UUID
+  forceRollout: 33333333-3333-3333-3333-333333333333      # Optional: for forced rollouts
+  inPlaceRollout: false                                   # In Place rollout is deprecated and ignored. Please use rolloutStrategy
+  rolloutStrategy: WaitUntilReady                         # The mechanism to use when rolling out the new version. Can be WaitUntilReady or ImmediatelyPromoteCausingDowntime
+  backendSecretName: materialize-backend
+```
+
+Apply the updated definition:
+
+```shell
+kubectl apply -f materialize.yaml
+```
+
+#### Rollout Configuration
+
+##### Forced Rollouts
+
+If you need to force a rollout even when there are no changes to the instance:
+
+```shell
+kubectl patch materialize <instance-name> \
+  -n materialize-environment \
+  --type='merge' \
+  -p "{\"spec\": {\"requestRollout\": \"$(uuidgen)\", \"forceRollout\": \"$(uuidgen)\"}}"
+```
+
+##### Rollout Strategies
+
+The behavior of the new version rollout follows your `rolloutStrategy` setting:
+
+`WaitUntilReady` (default):
+
+New instances are created and all dataflows are determined to be ready before cutover and terminating the old version, temporarily requiring twice the resources during the transition.
+
+`ImmediatelyPromoteCausingDowntime`:
+
+Tears down the prior version before creating and promoting the new version. This causes downtime equal to the duration it takes for dataflows to hydrate, but does not require additional resources.
+
+##### In Place Rollout
+
+The `inPlaceRollout` setting has been deprecated and will be ignored.
+
+### Verifying the Upgrade
+
+After initiating the rollout, you can monitor the status field of the Materialize custom resource to check on the upgrade.
+
+```shell
+# Watch the status of your Materialize environment
+kubectl get materialize -n materialize-environment -w
+
+# Check the logs of the operator
+kubectl logs -l app.kubernetes.io/name=materialize-operator -n materialize
+```
+### Version Specific Upgrade Notes
 
-{{< callout >}}
-{{< self-managed/also-available >}}
-{{</ callout >}}
+When upgrading v25 versions, you can upgrade at most one minor version at a
+time. For example, upgrading from `v25.1.5` to `v25.2.15` is permitted.
 
 ## See also
 

@@ -19,7 +19,7 @@ or the root).
 
 
 {{< note >}}
-**It is strongly recommended to upgrade at to least version 25.2.15 (environmentd 0.147.20) prior to upgrading to the next major version.**
+**Required. You must upgrade at to least version 25.2.15 (environmentd 0.147.20) prior to upgrading to the next major version.**
 {{</ note >}}
 
 

@@ -18,7 +18,7 @@ Azure](/installation/install-on-azure/) (either from the examples/simple
 directory or the root).
 
 {{< note >}}
-**It is strongly recommended to upgrade at to least version 25.2.15 (environmentd 0.147.20) prior to upgrading to the next major version.**
+**Required. You must upgrade at to least version 25.2.15 (environmentd 0.147.20) prior to upgrading to the next major version.**
 {{</ note >}}
 
 ## Version compatibility

@@ -18,7 +18,7 @@ GCP](/installation/install-on-gcp/) (either from the examples/simple directory
 or the root).
 
 {{< note >}}
-**It is strongly recommended to upgrade at to least version 25.2.15 (environmentd 0.147.20) prior to upgrading to the next major version.**
+**Required. You must upgrade at to least version 25.2.15 (environmentd 0.147.20) prior to upgrading to the next major version.**
 {{</ note >}}
 
 ## Version compatibility