Home  /  Self-Managed Deployments  /  Deployment guidelines

AWS deployment guidelines

View as Markdown

Self-managed Materialize requires: a Kubernetes (v1.31+) cluster; PostgreSQL as a metadata database; blob storage; and a license key.

As a general guideline, we recommend:

  • ARM-based CPU
  • A 1:8 ratio of vCPU to GiB memory.
  • At least a 2:1 ratio of GiB local instance storage to GiB memory when using swap.

When operating in AWS, we recommend the following instances:

EC2 Instances
r8g, r7g, and r6g families when running without local disk.
r7gd and r6gd families (and r8gd once available) when running with local disk. Recommended for production.

Starting in v0.3.1, the Materialize on AWS Terraform uses ["r7gd.2xlarge"] as the default node_group_instance_types.

Locally-attached NVMe storage

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 significantly degrade performance and is not supported.

Swap support

    New Terraform

    The new Materialize Terraform module supports configuring swap out of the box.

    Legacy Terraform

    The Legacy Terraform provider adds preliminary swap support in v0.6.1, via the swap_enabled variable. With this change, the Terraform:

    • Creates a node group for Materialize.
    • Configures NVMe instance store volumes as swap using a daemonset.
    • Enables swap at the Kubelet.

    See Upgrade Notes.

    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.

    TLS

    When running with TLS in production, run with certificates from an official Certificate Authority (CA) rather than self-signed certificates.

    Upgrading guideline

    Whe upgrading:

    • Always check the version-specific upgrade notes.

    • Always upgrade the operator first and ensure version compatibility between the operator and the Materialize instance you are upgrading to.

    • Always upgrade your Materialize instances after upgrading the operator to ensure compatibility.

    Karpenter node expiry

    We recommend setting expire_after to Never on the Materialize nodepool since node expiry is not a voluntary disruption. With any other value, Karpenter removes nodes that reach their configured lifetime even if they run pods annotated with karpenter.sh/do-not-disrupt. This can cause downtime unless you gracefully roll the nodes first. The Materialize Terraform modules default expire_after to Never.

    Karpenter termination grace period

    We recommend leaving termination_grace_period unset on nodepools that run Materialize workloads. When this value is set, Karpenter terminates nodes after the configured grace period following any change to the nodepool configuration, even if they run pods annotated with karpenter.sh/do-not-disrupt.

    Before v6.0.0, the modules set termination_grace_period to 300s. If you are using a version earlier than v6.0.0, upgrade to v6.0.0 using the v6.0.0 upgrade notes. Starting in v6.0.0, the Materialize Terraform modules leave termination_grace_period unset by default.

    Node pool resizing

    The VM type of a Kubernetes node pool is immutable on EKS, AKS, and GKE, so changing it triggers a destroy + create that fails while Materialize pods are still running on the pool. The supported pattern is to add a second pool with the new VM type, roll out the Materialize instance so new pods land on it, and then drop the old pool.

    For the full procedure, see Resize node pools.

    Back to top ↑