Adopting the v1 CRD

If you are using the supported Terraform modules, the required infrastructure changes (cert-manager and network ingress) and enabling of v1 CRD will be handled for you automatically starting in TF modules (v3.1.1 or greater).

• If you have already upgraded your TF modules to v3.1.1 or greater, the prerequisites are handled automatically.

• If you are on earlier TF modules, use the same procedure to perform version upgrades to upgrade to v3.1.1 or greater; i.e., update each module’s source to point to the new release tag (v3.1.1 or greater), then run terraform init && terraform plan && terraform apply.

  This will also upgrade your Materialize version to that associated with that TF release tag.

  • Upgrade on AWS
  • Upgrade on Azure
  • Upgrade on GCP

If you are using the legacy Terraform modules (AWS, GCP, or Azure), we recommend migrating to the new supported Terraform modules before opting in to the v1 CRD.

The new modules include built-in support for the conversion webhooks used by the v1 CRD, including cert-manager installation and network policy configuration. The legacy modules do not include these changes, so you would need to apply them manually (see the Manual tab).

For migration guidance, see the documentation for your cloud provider:

• AWS migration guide
• GCP migration guide
• Azure migration guide

If you are not using our Terraform modules, you must complete the following steps before enabling the v1 CRD:

1. Install cert-manager

The conversion webhook requires a TLS certificate. The Helm chart defaults to using cert-manager to automatically create and manage this certificate. cert-manager must be installed before enabling the v1 CRD.

If you prefer to provide your own certificate instead of using cert-manager, set the following Helm values:

• operator.certificate.source: secret
• operator.certificate.secretName: the name of the Kubernetes Secret containing ca.crt, tls.crt, and tls.key entries.

2. Allow network access to the webhook port

The conversion webhooks require the Kubernetes API server to reach the orchestratord pod on port 8001. If your cluster enforces network policies or cloud-level firewall rules, you must allow ingress traffic on TCP port 8001 from the API server to pods with the label app.kubernetes.io/name: materialize-operator.

Kubernetes NetworkPolicy: Add a policy that allows ingress from the Kubernetes API server on port 8001 to the materialize-operator pods in the namespace where the operator is deployed:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-api-server-ingress-to-conversion-webhook
  namespace: materialize  # the namespace where the operator runs
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: materialize-operator
  policyTypes:
    - Ingress
  ingress:
    - ports:
        - protocol: TCP
          port: 8001

Cloud firewall rules (e.g., AWS security groups, GCP firewall rules): Ensure the node security group or firewall allows inbound TCP traffic on port 8001 from the Kubernetes control plane. For example, on AWS, add an ingress rule to the EKS node security group allowing port 8001 from the cluster security group. On GCP with private clusters, add a firewall rule allowing port 8001 from the GKE control plane CIDR.

For a complete example of the required changes across AWS, Azure, and GCP, see this pull request.

3. Enable the v1 CRD

Once the prerequisites above are in place, set the following Helm value when installing or upgrading the operator:

operator:
  args:
    installV1CRD: true

This installs the v1 version of the Materialize CRD and the conversion webhook that converts between v1 and v1alpha1.

If you are managing your Materialize instance with the Materialize Terraform modules, set:

crd_version     = "v1"
request_rollout = null

Once on v1, an unchanged spec will not trigger a rollout. Reapplying the same spec produces the same hash and the same derived requestRollout. Changing a hashed spec field produces a new value and triggers a rollout automatically.

To adopt v1 for an existing instance, apply your CR with apiVersion: materialize.cloud/v1 and remove the requestRollout field:

kubectl apply -f - <<EOF
apiVersion: materialize.cloud/v1
kind: Materialize
metadata:
  name: <instance-name>
  namespace: <materialize-instance-namespace>
spec:
  environmentdImageRef: <current-image-ref>
  backendSecretName: <backend-secret-name>
  # ... other spec fields (copy from your existing CR, removing requestRollout)
EOF

Once on v1, an unchanged spec will not trigger a rollout. Reapplying the same spec produces the same hash and the same derived requestRollout. Changing a hashed spec field produces a new value and triggers a rollout automatically.