pr review changes

Author: jubrad

doc/user/content/installation/_index.md

@@ -16,175 +16,6 @@ aliases:
 
 {{< include-md file="shared-content/self-managed/general-rules-for-upgrades.md" >}}
 
-### Upgrade guides
-
-The following upgrade guides are available:
-
-|               | 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 |
-
-
-### General notes for upgrades
-
-The following provides some general notes for upgrades. For specific examples,
-see the [Upgrade guides](#upgrade-guides)
-
-
-#### Upgrading the Helm Chart and Kubernetes Operator
-
-{{< 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:v26.0.0
-```
-
-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:v26.0.0\"}}"
-```
-
-##### 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:v26.0.0\", \"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:v26.0.0 # 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
-
-#### Upgrading to `v26.0`
-
-{{< include-md file="shared-content/self-managed/upgrade-notes/v26.0.md" >}}
-
-#### Upgrading between minor versions less than `v26`
- - Prior to `v26`, you must upgrade at most one minor version at a time. For
-   example, upgrading from `v25.1.5` to `v25.2.15` is permitted.
-
 ## See also
 
 - [Materialize Operator Configuration](/installation/configuration/)

doc/user/content/installation/install-on-aws/appendix-deployment-guidelines.md

@@ -15,14 +15,14 @@ menu:
 As a general guideline, we recommend:
 
 - ARM-based CPU
-- A 1:8 ratio of vCPU to GiB memory is recommended.
-- When using swap, it is recommended to use a 8:1 ratio of GiB local instance storage to GiB Ram.
+- A 1:8 ratio of vCPU to GiB memory.
+- When using swap, use a 8:1 ratio of GiB local instance storage to GiB memory.
 
 {{% self-managed/aws-recommended-instances %}}
 
 ## Locally-attached NVMe storage
 
-Configuring swap on nodes to using locally-attached NVMe storage allows
+Configuring swap on nodes to use locally-attached NVMe storage allows
 Materialize to spill to disk when operating on datasets larger than main memory.
 This setup can provide significant cost savings and provides a more graceful
 degradation rather than OOMing. Network-attached storage (like EBS volumes) can
@@ -45,7 +45,7 @@ With this change, the Terraform:
 See [Upgrade Notes](https://github.com/MaterializeInc/terraform-aws-materialize?tab=readme-ov-file#v061).
 
 {{< note >}}
-If deploying `v25.2` Materialize clusters will not automatically use swap unless they are configured with a `memory_request` less than their `memory_limit`. In `v26` this will be handled automatically.
+If deploying `v25.2`, Materialize clusters will not automatically use swap unless they are configured with a `memory_request` less than their `memory_limit`. In `v26`, this will be handled automatically.
 {{< /note >}}
 
 ## TLS

doc/user/content/installation/install-on-aws/terraform-module/_index.md

@@ -9,17 +9,14 @@ menu:
 ---
 
 Materialize provides a set of modular Terraform modules that can be used to
-deploy all services required for a production ready Materialize database.
+deploy all services required for Materialize to run on AWS.
 The module is intended to provide a simple set of examples on how to deploy
-materialize. It can be used as is or modules can be taken from the example and
+Materialize. It can be used as is or modules can be taken from the example and
 integrated with existing DevOps tooling.
 
-The repository can be found at:
-
-***[Materialize Terraform Self-Managed AWS](https://github.com/MaterializeInc/materialize-terraform-self-managed/tree/main/aws)***
-
-Please see the [top level](https://github.com/MaterializeInc/materialize-terraform-self-managed/tree/main) and [cloud specific](https://github.com/MaterializeInc/materialize-terraform-self-managed/tree/main/aws) documentation for a full understanding
-of the module structure and customizations.
+For details on the module structure and customization, see:
+* [top level](https://github.com/MaterializeInc/materialize-terraform-self-managed/tree/main)
+* [cloud specific](https://github.com/MaterializeInc/materialize-terraform-self-managed/tree/main/aws)
 
 Also check out the [AWS deployment guide](/installation/install-on-aws/appendix-deployment-guidelines/) for details on recommended instance sizing and configuration.
 
@@ -43,7 +40,7 @@ Also check out the [AWS deployment guide](/installation/install-on-aws/appendix-
 
 #### License key
 
-{{< include-md file="shared-content/license-key-required.md" >}}
+{{< yaml-table data="self_managed/license_key" >}}
 
 ---
 
@@ -64,40 +61,56 @@ cd materialize-terraform-self-managed/aws/examples/simple
 This example provisions the following infrastructure:
 
 ### Networking
-- **VPC**: 10.0.0.0/16 with DNS hostnames and support enabled
-- **Subnets**: 3 private subnets (10.0.1.0/24, 10.0.2.0/24, 10.0.3.0/24) and 3 public subnets (10.0.101.0/24, 10.0.102.0/24, 10.0.103.0/24) across availability zones us-east-1a, us-east-1b, us-east-1c
-- **NAT Gateway**: Single NAT Gateway for all private subnets
-- **Internet Gateway**: For public subnet connectivity
+
+| Resource | Description |
+|----------|-------------|
+| VPC | 10.0.0.0/16 with DNS hostnames and support enabled |
+| Subnets | 3 private subnets (10.0.1.0/24, 10.0.2.0/24, 10.0.3.0/24) and 3 public subnets (10.0.101.0/24, 10.0.102.0/24, 10.0.103.0/24) across availability zones us-east-1a, us-east-1b, us-east-1c |
+| NAT Gateway | Single NAT Gateway for all private subnets |
+| Internet Gateway | For public subnet connectivity |
 
 ### Compute
-- **EKS Cluster**: Version 1.32 with CloudWatch logging (API, audit)
-- **Base Node Group**: 2 nodes (t4g.medium) for Karpenter and CoreDNS
-- **Karpenter**: Auto-scaling controller with two node classes:
-  - Generic nodepool: t4g.xlarge instances for general workloads
-  - Materialize nodepool: r7gd.2xlarge instances with swap enabled and dedicated taints to run materialize instance workloads.
+
+| Resource | Description |
+|----------|-------------|
+| EKS Cluster | Version 1.32 with CloudWatch logging (API, audit) |
+| Base Node Group | 2 nodes (t4g.medium) for Karpenter and CoreDNS |
+| Karpenter | Auto-scaling controller with two node classes: Generic nodepool (t4g.xlarge instances for general workloads) and Materialize nodepool (r7gd.2xlarge instances with swap enabled and dedicated taints to run materialize instance workloads) |
 
 ### Database
-- **RDS PostgreSQL**: Version 15, db.t3.large instance
-- **Storage**: 50GB allocated, autoscaling up to 100GB
-- **Deployment**: Single-AZ (non-production configuration)
-- **Backups**: 7-day retention
-- **Security**: Dedicated security group with access from EKS cluster and nodes
+
+| Resource | Description |
+|----------|-------------|
+| RDS PostgreSQL | Version 15, db.t3.large instance |
+| Storage | 50GB allocated, autoscaling up to 100GB |
+| Deployment | Single-AZ (non-production configuration) |
+| Backups | 7-day retention |
+| Security | Dedicated security group with access from EKS cluster and nodes |
 
 ### Storage
-- **S3 Bucket**: Dedicated bucket for Materialize persistence
-- **Encryption**: Disabled (for testing; enable in production)
-- **Versioning**: Disabled (for testing; enable in production)
-- **IAM Role**: IRSA role for Kubernetes service account access
+
+| Resource | Description |
+|----------|-------------|
+| S3 Bucket | Dedicated bucket for Materialize persistence |
+| Encryption | Disabled (for testing; enable in production) |
+| Versioning | Disabled (for testing; enable in production) |
+| IAM Role | IRSA role for Kubernetes service account access |
 
 ### Kubernetes Add-ons
-- **AWS Load Balancer Controller**: For managing Network Load Balancers
-- **cert-manager**: Certificate management controller for Kubernetes that automates TLS certificate provisioning and renewal
-- **Self-signed ClusterIssuer**: Provides self-signed TLS certificates for Materialize instance internal communication (balancerd, console). Used by the Materialize instance for secure inter-component communication.
+
+| Resource | Description |
+|----------|-------------|
+| AWS Load Balancer Controller | For managing Network Load Balancers |
+| cert-manager | Certificate management controller for Kubernetes that automates TLS certificate provisioning and renewal |
+| Self-signed ClusterIssuer | Provides self-signed TLS certificates for Materialize instance internal communication (balancerd, console). Used by the Materialize instance for secure inter-component communication. |
 
 ### Materialize
-- **Operator**: Materialize Kubernetes operator
-- **Instance**: Single Materialize instance in `materialize-environment` namespace
-- **Network Load Balancer**: Dedicated internal NLB for Materialize access (ports 6875, 6876, 8080)
+
+| Resource | Description |
+|----------|-------------|
+| Operator | Materialize Kubernetes operator |
+| Instance | Single Materialize instance in `materialize-environment` namespace |
+| Network Load Balancer | Dedicated internal NLB for Materialize access (ports 6875, 6876, 8080) |
 
 ---
 
@@ -111,7 +124,7 @@ Before running Terraform, create a `terraform.tfvars` file with the following va
 name_prefix = "simple-demo"
 aws_region  = "us-east-1"
 aws_profile = "your-aws-profile"
-license_key = "your-materialize-license-key"  # Get from https://materialize.com/self-managed/
+license_key = "your-materialize-license-key"
 tags = {
   environment = "demo"
 }

doc/user/content/installation/install-on-azure/appendix-deployment-guidelines.md

@@ -13,8 +13,8 @@ menu:
 As a general guideline, we recommend:
 
 - ARM-based CPU
-- A 1:8 ratio of vCPU to GiB memory is recommended.
-- When using swap, it is recommended to use a 8:1 ratio of GiB local instance storage to GiB Ram.
+- A 1:8 ratio of vCPU to GiB memory.
+- When using swap, use a 8:1 ratio of GiB local instance storage to GiB memory.
 
 ### Recommended Azure VM Types with Local NVMe Disks
 
@@ -39,7 +39,7 @@ when the VM is stopped or deleted.
 
 ## Locally-attached NVMe storage
 
-Configuring swap on nodes to using locally-attached NVMe storage allows
+Configuring swap on nodes to use locally-attached NVMe storage allows
 Materialize to spill to disk when operating on datasets larger than main memory.
 This setup can provide significant cost savings and provides a more graceful
 degradation rather than OOMing. Network-attached storage (like EBS volumes) can
@@ -62,7 +62,7 @@ With this change, the Terraform:
 See [Upgrade Notes](https://github.com/MaterializeInc/terraform-azurerm-materialize?tab=readme-ov-file#v061).
 
 {{< note >}}
-If deploying `v25.2` Materialize clusters will not automatically use swap unless they are configured with a `memory_request` less than their `memory_limit`. In `v26` this will be handled automatically.
+If deploying `v25.2`, Materialize clusters will not automatically use swap unless they are configured with a `memory_request` less than their `memory_limit`. In `v26`, this will be handled automatically.
 {{< /note >}}
 
 ## Recommended Azure Blob Storage