docs: updates for license keys (#34181)

kay-kim · web-flow · commit 16f5efa272d9 · 2025-11-17T16:37:53.000-05:00
diff --git a/doc/user/content/installation/faq.md b/doc/user/content/installation/faq.md
@@ -16,7 +16,7 @@ keys will vary based on the terms of your contract.
 
 ## How do I get a license key?
 
-{{< include-md file="shared-content/license-key-required.md" >}}
+{{< yaml-table data="self_managed/license_key" >}}
 
 ## How do I add a license key to an existing installation?
 
diff --git a/doc/user/content/installation/install-on-aws/_index.md b/doc/user/content/installation/install-on-aws/_index.md
@@ -61,7 +61,9 @@ documentation](https://helm.sh/docs/intro/install/).
 
 ### License key
 
-{{< include-md file="shared-content/license-key-required.md" >}}
+Starting in v26.0, Self-Managed Materialize requires a license key.
+
+{{< yaml-table data="self_managed/license_key" >}}
 
 ## Set up AWS Kubernetes environment and install Materialize
 
@@ -269,7 +271,7 @@ components:
    `mz_instances.tfvars` file with the [Materialize instance
    configuration](https://github.com/MaterializeInc/terraform-aws-materialize?tab=readme-ov-file#input_materialize_instances).
 
-   For example, the following specifies the configuration for a `demo` instance.
+   For example, the following specifies the configuration for a `demo`:
 
    ```bash
    cat <<EOF > mz_instances.tfvars
@@ -282,12 +284,16 @@ components:
          cpu_request    = "1"
          memory_request = "2Gi"
          memory_limit   = "2Gi"
-         license_key    = ""
+         license_key    = "<ENTER YOUR LICENSE KEY HERE>"
        }
    ]
    EOF
    ```
 
+   - **Starting in v26.0**, Self-Managed Materialize requires a license key. To
+     get your license key:
+     {{% yaml-table data="self_managed/license_key" %}}
+
    - **Starting in v0.3.0**, the Materialize on AWS Terraform module also
    deploys, by default, Network Load Balancers (NLBs) for each Materialize
    instance (i.e., the
diff --git a/doc/user/content/installation/install-on-aws/upgrade-on-aws.md b/doc/user/content/installation/install-on-aws/upgrade-on-aws.md
@@ -79,7 +79,7 @@ documentation](https://helm.sh/docs/intro/install/).
 
 ### License key
 
-{{< include-md file="shared-content/license-key-required.md" >}}
+{{< include-md file="shared-content/self-managed/license-key-upgrades.md" >}}
 
 ## Procedure
 
diff --git a/doc/user/content/installation/install-on-azure/_index.md b/doc/user/content/installation/install-on-azure/_index.md
@@ -67,7 +67,9 @@ If you want to use `jq` and do not have `jq` installed, install.
 
 ### License key
 
-{{< include-md file="shared-content/license-key-required.md" >}}
+Starting in v26.0, Self-Managed Materialize requires a license key.
+
+{{< yaml-table data="self_managed/license_key" >}}
 
 ## A. Authenticate with Azure
 
@@ -335,12 +337,16 @@ deploys a sample infrastructure on Azure with the following components:
          cpu_request    = "1"
          memory_request = "2Gi"
          memory_limit   = "2Gi"
-         license_key    = ""
+         license_key    = "<ENTER YOUR LICENSE KEY HERE>"
        }
    ]
    EOF
    ```
 
+   - **Starting in v26.0**, Self-Managed Materialize requires a license key. To
+     get your license key:
+     {{% yaml-table data="self_managed/license_key" %}}
+
    - **Starting in v0.3.0**, the Materialize on Azure Terraform module also
      deploys, by default, a self-signed `ClusterIssuer`. The `ClusterIssuer` is
      deployed after the `cert-manager` is deployed and running.
diff --git a/doc/user/content/installation/install-on-azure/upgrade-on-azure.md b/doc/user/content/installation/install-on-azure/upgrade-on-azure.md
@@ -92,7 +92,7 @@ If you want to use `jq` and do not have `jq` installed, install.
 
 ### License key
 
-{{< include-md file="shared-content/license-key-required.md" >}}
+{{< include-md file="shared-content/self-managed/license-key-upgrades.md" >}}
 
 ## A. Authenticate with Azure
 
diff --git a/doc/user/content/installation/install-on-gcp/_index.md b/doc/user/content/installation/install-on-gcp/_index.md
@@ -93,7 +93,9 @@ If you want to use `jq` and do not have `jq` installed, install.
 
 ### License key
 
-{{< include-md file="shared-content/license-key-required.md" >}}
+Starting in v26.0, Self-Managed Materialize requires a license key.
+
+{{< yaml-table data="self_managed/license_key" >}}
 
 ## A. Configure GCP project and service account
 
@@ -404,12 +406,16 @@ components:
          cpu_request    = "1"
          memory_request = "2Gi"
          memory_limit   = "2Gi"
-         license_key    = ""
+         license_key    = "<ENTER YOUR LICENSE KEY HERE>"
        }
    ]
    EOF
    ```
 
+   - **Starting in v26.0**, Self-Managed Materialize requires a license key. To
+     get your license key:
+     {{% yaml-table data="self_managed/license_key" %}}
+
    - **Starting in v0.3.0**, the Materialize on GCP Terraform module also
      deploys, by default:
 
diff --git a/doc/user/content/installation/install-on-gcp/upgrade-on-gcp.md b/doc/user/content/installation/install-on-gcp/upgrade-on-gcp.md
@@ -109,7 +109,7 @@ If you want to use `jq` and do not have `jq` installed, install.
 
 ### License key
 
-{{< include-md file="shared-content/license-key-required.md" >}}
+{{< include-md file="shared-content/self-managed/license-key-upgrades.md" >}}
 
 ## Procedure
 
diff --git a/doc/user/content/installation/install-on-local-kind/_index.md b/doc/user/content/installation/install-on-local-kind/_index.md
@@ -12,13 +12,6 @@ menu:
 disable_list: true
 ---
 
-{{< annotation type="Disambiguation" >}}
-
-This page is for upgrading from v25.2.13 or later. For upgrading
-from v25.2.12 or earlier, see [Upgrade from v25.2.12 or earlier](/installation/install-on-local-kind/upgrade-to-swap/).
-
-{{< /annotation >}}
-
 {{% self-managed/materialize-components-sentence %}}
 
 The following tutorial uses a local [`kind`](https://kind.sigs.k8s.io/) cluster
@@ -69,7 +62,9 @@ reference](https://kubernetes.io/docs/reference/kubectl/quick-reference/).
 
 ### License key
 
-{{< include-md file="shared-content/license-key-required.md" >}}
+Starting in v26.0, Self-Managed Materialize requires a license key.
+
+{{< yaml-table data="self_managed/license_key" >}}
 
 ## Installation
 
@@ -116,7 +111,28 @@ reference](https://kubernetes.io/docs/reference/kubectl/quick-reference/).
 
    {{% self-managed/versions/curl-sample-files-local-install %}}
 
-1. Edit `sample-materialize.yaml` to add your license key to the `license_key` field in the backend secret.
+1. Add your license key:
+
+   a. To get your license key:
+
+      {{% yaml-table data="self_managed/license_key" %}}
+
+   b. Edit `sample-materialize.yaml` to add your license key to the
+   `license_key` field in the backend secret.
+
+   ```yaml {hl_lines="10"}
+   ---
+   apiVersion: v1
+   kind: Secret
+   metadata:
+   name: materialize-backend
+   namespace: materialize-environment
+   stringData:
+   metadata_backend_url: "postgres://materialize_user:materialize_pass@postgres.materialize.svc.cluster.local:5432/materialize_db?sslmode=disable"
+   persist_backend_url: "s3://minio:minio123@bucket/12345678-1234-1234-1234-123456789012?endpoint=http%3A%2F%2Fminio.materialize.svc.cluster.local%3A9000&region=minio"
+   license_key: "<enter your license key here>"
+   ---
+   ```
 
 1. Install the Materialize Helm chart.
 
diff --git a/doc/user/content/installation/install-on-local-kind/upgrade-on-local-kind.md b/doc/user/content/installation/install-on-local-kind/upgrade-on-local-kind.md
@@ -43,7 +43,7 @@ reference](https://kubernetes.io/docs/reference/kubectl/quick-reference/).
 
 ### License key
 
-{{< include-md file="shared-content/license-key-required.md" >}}
+{{< include-md file="shared-content/self-managed/license-key-upgrades.md" >}}
 
 ## Upgrade
 
diff --git a/doc/user/content/license.md b/doc/user/content/license.md
@@ -22,7 +22,7 @@ agreement.
 
 A license key is required to use Self-Managed Materialize.
 
-{{< include-md file="shared-content/license-key-required.md" >}}
+{{< yaml-table data="self_managed/license_key" >}}
 
 ### Self-Managed Community Edition Privacy Policy
 
diff --git a/doc/user/content/releases/_index.md b/doc/user/content/releases/_index.md
@@ -47,11 +47,14 @@ see [Authentication](/security/self-managed/authentication/).
 
 ### License Key
 
-{{< include-md file="shared-content/license-key-required.md" >}}
+Starting in v26.0.0, Self-Managed Materialize requires a license key.
 
-The license key should be configured in the Kubernetes Secret resource
-created during the installation process. To configure a license key in an
-existing installation, run:
+{{< yaml-table data="self_managed/license_key" >}}
+
+For new deployments, you configure your license key in the Kubernetes Secret
+resource during the installation process. For details, see the installation
+guides [/installation/]. For existing deployments, you can configure your
+license key via:
 
 ```bash
 kubectl -n materialize-environment patch secret materialize-backend -p '{"stringData":{"license_key":"<your license key goes here>"}}' --type=merge
diff --git a/doc/user/data/self_managed/license_key.yml b/doc/user/data/self_managed/license_key.yml
@@ -0,0 +1,19 @@
+columns:
+  - column: "Deployment"
+  - column: "Type"
+  - column: "Action"
+rows:
+  - Deployment: "New deployments"
+    Type: "Community"
+    Action: |
+      To get a license key:
+      - If you have a Cloud account, visit the [**License** page in the
+      Materialize Console](https://console.materialize.com/license/).
+      - If you do not have a Cloud account, visit
+      https://materialize.com/self-managed/community-license/.
+  - Deployment: "New deployments"
+    Type: "Enterprise"
+    Action: "Contact Materialize at https://materialize.com/self-managed/."
+  - Deployment: "Existing deployments"
+    Type: "Community or Enterprise"
+    Action: "Contact Materialize at https://materialize.com/self-managed/."
diff --git a/doc/user/layouts/shortcodes/self-managed/materialize-components-sentence.html b/doc/user/layouts/shortcodes/self-managed/materialize-components-sentence.html
@@ -1,4 +1,4 @@
 {{- $blobstorage := .Get "blobstorage" | default "blob storage" -}}
 
 Self-managed Materialize requires: a Kubernetes (v1.31+) cluster; PostgreSQL as
-a metadata database; and {{$blobstorage}}.
+a metadata database; {{$blobstorage}}; and a license key.
diff --git a/doc/user/layouts/shortcodes/self-managed/versions/upgrade/upgrade-steps-cloud.html b/doc/user/layouts/shortcodes/self-managed/versions/upgrade/upgrade-steps-cloud.html
@@ -82,14 +82,15 @@
    | `environmentd_version`  | New Materialize instance version. This should be the same as the operator version: `{{ $operator_version }}`.|
    | `request_rollout`  or `force_rollout` | A new UUID string.  Can be generated with `uuidgen`.<br> <ul><li>`request_rollout` triggers a rollout only if changes exist. </li><li>`force_rollout`  triggers a rollout even if no changes exist.</li></ul> |
    | `inPlaceRollout` | Set to `false` to perform a rolling upgrade. For rolling upgrades, ensure you have enough resources to support having both the old and new Materialize instances running during the upgrade. |
-   | `license_key` | Set to the value of your license key. |
+   | `license_key` | Required. Set to the value of your license key. If your existing deployment does not have a license key, contact Materialize at https://materialize.com/self-managed/. If you have a license key, substitute your license key for `<ENTER YOUR LICENSE KEY HERE>`. |
 
    For example, the following instance specifies:
 
    - a `create_database` of `false`,
    - an `inPlaceRollout` of `false`,
-   - an `environmentd_version` of `"{{ $environmentd_version }}"`, and
-   - a `request_rollout` of `"22222222-2222-2222-2222-222222222222"`.
+   - an `environmentd_version` of `"{{ $environmentd_version }}"`,
+   - a `request_rollout` of `"22222222-2222-2222-2222-222222222222"`, and
+   - a `license_key` (substituting your license key for `<ENTER YOUR LICENSE KEY HERE>`).
 
    ```sh
    materialize_instances = [
@@ -101,7 +102,7 @@
          memory_request = "2Gi"
          memory_limit   = "2Gi"
          create_database = false
-         license_key    = "[...]"
+         license_key    = "<ENTER YOUR LICENSE KEY HERE>"        # Required.
          environmentd_version = "{{ $environmentd_version }}"
          inPlaceRollout: false                                   # When false, performs a rolling upgrade rather than in-place
          requestRollout: 22222222-2222-2222-2222-222222222222    # Enter a new UUID
diff --git a/doc/user/layouts/shortcodes/self-managed/versions/upgrade/upgrade-steps-local-kind.html b/doc/user/layouts/shortcodes/self-managed/versions/upgrade/upgrade-steps-local-kind.html
@@ -50,12 +50,16 @@
    kubectl -n materialize describe pod -l app.kubernetes.io/name=materialize-operator
    ```
 
-1. As of Materialize version 26.0, a license key is required to run in
-   Kubernetes. To configure a license key in an existing installation, run:
+1. As of v26.0, Self-Managed Materialize requires a license key. If your
+deployment has not been configured with a license key:
 
-   ```bash
-   kubectl -n materialize-environment patch secret materialize-backend -p '{"stringData":{"license_key":"<your license key goes here>"}}' --type=merge
-   ```
+   a. Contact Materialize at https://materialize.com/self-managed/.
+
+   b. Once you have your license key, run the following command to add it to the `materialize-backend` secret:
+
+      ```bash
+      kubectl -n materialize-environment patch secret materialize-backend -p '{"stringData":{"license_key":"<your license key goes here>"}}' --type=merge
+      ```
 
 1. Create a new `upgrade-materialize.yaml` file with the following content:
 
diff --git a/doc/user/layouts/shortcodes/self-managed/versions/upgrade/upgrade-steps-local-minikube.html b/doc/user/layouts/shortcodes/self-managed/versions/upgrade/upgrade-steps-local-minikube.html
diff --git a/doc/user/shared-content/license-key-required.md b/doc/user/shared-content/license-key-required.md
diff --git a/doc/user/shared-content/self-managed/install-landing-page.md b/doc/user/shared-content/self-managed/install-landing-page.md
diff --git a/doc/user/shared-content/self-managed/license-key-upgrades.md b/doc/user/shared-content/self-managed/license-key-upgrades.md
