ContextQMD
Back to Materialize

GCP deployment guidelines

doc/user/content/self-managed-deployments/deployment-guidelines/gcp-deployment-guidelines.md

1234.5 KB
Original Source

As a general guideline, we recommend:

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

When operating on GCP in production, we recommend the following machine types that support local SSD attachment:

SeriesExamples
N2 high-memory seriesn2-highmem-16 or n2-highmem-32 with local NVMe SSDs
N2D high-memory seriesn2d-highmem-16 or n2d-highmem-32 with local NVMe SSDs

To maintain the recommended 8:1 disk-to-RAM ratio for your machine type, see Number of local SSDs to determine the number of local SSDs to use.

See also Locally attached NVMe storage.

Number of local SSDs

Each local NVMe SSD in GCP provides 375GB of storage. Use the appropriate number of local SSDs to ensure your total disk space is at least twice the amount of RAM in your machine type for optimal Materialize performance.

{{< note >}}

Your machine type may only supports predefined number of local SSDs. For instance, n2d-highmem-32 allows only the following number of local SSDs: 4,8,16, or 24. To determine the valid number of Local SSDs to attach for your machine type, see the GCP documentation.

{{</ note >}}

For example, the following table provides a minimum local SSD count to ensure the 2:1 disk-to-RAM ratio. Your actual count will depend on the your machine type.

Machine TypeRAMRequired DiskMinimum Local SSD CountTotal SSD Storage
n2-highmem-864GB128GB1375GB
n2-highmem-16128GB256GB1375GB
n2-highmem-32256GB512GB2750GB
n2-highmem-64512GB1024GB31125GB
n2-highmem-80640GB1280GB41500GB

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

{{< tabs >}} {{< tab "New Terraform" >}}

New Terraform

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

{{< /tab >}} {{< tab "Legacy Terraform" >}}

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. {{< /note >}} {{< /tab >}} {{< /tabs >}}

CPU affinity

It is strongly recommended to enable the Kubernetes static CPU management policy. This ensures that each worker thread of Materialize is given exclusively access to a vCPU. Our benchmarks have shown this to substantially improve the performance of compute-bound workloads.

TLS

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

Upgrading guideline

{{< include-md file="shared-content/self-managed/general-rules-for-upgrades.md"

}}