Install on AWS

Materialize provides a set of modular Terraform modules that can be used to deploy all services required for Materialize to run on AWS. These modules serve as composable building blocks that you can integrate into existing DevOps workflows, either as a full set or individually.

Self-managed Materialize requires: a Kubernetes (v1.31+) cluster; PostgreSQL as a metadata database; blob storage; and a license key. The example on this page deploys a complete Materialize environment on AWS using the modular Terraform setup from this repository.

What Gets Created

This example provisions the following infrastructure:

Networking

Compute

Database

Storage

Kubernetes Add-ons

Materialize

Prerequisites

AWS Account Requirements

An active AWS account with appropriate permissions to create:

• EKS clusters
• RDS instances
• S3 buckets
• VPCs and networking resources
• IAM roles and policies

Required Tools

• Terraform
• AWS CLI
• kubectl
• Helm 3.2.0+

License Key

Getting started: Simple example

Step 1: Set Up the Environment

1. Open a terminal window.

2. Clone the Materialize Terraform repository and go to the aws/examples/simple directory.

   git clone https://github.com/MaterializeInc/materialize-terraform-self-managed.git
   cd materialize-terraform-self-managed/aws/examples/simple
   

3. Ensure your AWS CLI is configured with the appropriate profile, substitute <your-aws-profile> with the profile to use:

   # Set your AWS profile for the session
   export AWS_PROFILE=<your-aws-profile>
   

Step 2: Configure Terraform Variables

1. Create a terraform.tfvars file with the following variables:

   • name_prefix: Prefix for all resource names (e.g., simple-demo)
   • aws_region: AWS region for deployment (e.g., us-east-1)
   • aws_profile: AWS CLI profile to use
   • license_key: Materialize license key
   • tags: Map of tags to apply to resources

   name_prefix = "simple-demo"
   aws_region  = "us-east-1"
   aws_profile = "your-aws-profile"
   license_key = "your-materialize-license-key"
   tags = {
     environment = "demo"
   }
   # internal_load_balancer = false   # default = true (internal load balancer). You can set to false = public load balancer.
   # ingress_cidr_blocks = ["x.x.x.x/n", ...]
   # k8s_apiserver_authorized_networks  = ["x.x.x.x/n", ...]
   

   Optional variables:

   • internal_load_balancer: Flag that determines whether the load balancer is internal (default) or public.
   • ingress_cidr_blocks: List of CIDR blocks allowed to reach the load balancer if the load balancer is public (internal_load_balancer: false). If unset, defaults to ["0.0.0.0/0"] (i.e., all IPv4 addresses on the internet). Only applied when the load balancer is public.
   • k8s_apiserver_authorized_networks: List of CIDR blocks allowed to access your cluster endpoint. If unset, defaults to ["0.0.0.0/0"] (all IPv4 addresses on the internet).
   NOTE: Refer to your organization’s security practices to set these values accordingly.

Step 3: Apply the Terraform

1. Initialize the Terraform directory to download the required providers and modules:

   terraform init
   

2. Apply the Terraform configuration to create the infrastructure.

   terraform apply
   

   If you are satisfied with the planned changes, type yes when prompted to proceed.

   💡 Tip:

   If you previously logged in to Amazon ECR Public, a cached auth token may cause 403 errors even when pulling public images. To remove the token, run:

   docker logout public.ecr.aws
   

   Then, re-apply the Terraform configuration.

3. From the output, you will need the following fields to connect using the Materialize Console and PostgreSQL-compatible clients/drivers:

   • nlb_dns_name
   • external_login_password_mz_system.

   terraform output -raw <field_name>
   

   💡 Tip: Your shell may show an ending marker (such as %) because the output did not end with a newline. Do not include the marker when using the value.

4. Configure kubectl to connect to your cluster, replacing:

   • <your-eks-cluster-name> with the your cluster name; i.e., the eks_cluster_name in the Terraform output. For the sample example, your cluster name has the form {prefix_name}-eks; e.g., simple-demo-eks.

   • <your-region> with the region of your cluster. Your region can be found in your terraform.tfvars file; e.g., us-east-1.

   # aws eks update-kubeconfig --name <your-eks-cluster-name> --region <your-region>
   aws eks update-kubeconfig --name $(terraform output -raw eks_cluster_name) --region <your-region>
   

Step 4. Optional. Verify the deployment.

1. Check the status of your deployment:

   To check the status of the Materialize operator, which runs in the materialize namespace:

   kubectl -n materialize get all
   

   To check the status of the Materialize instance, which runs in the materialize-environment namespace:

   kubectl -n materialize-environment get all
   

   If you run into an error during deployment, refer to the Troubleshooting.

Step 5: Connect to Materialize

Using the nlb_dns_name and external_login_password_mz_system from the Terraform output, you can connect to Materialize via the Materialize Console or PostgreSQL-compatible tools/drivers using the following ports:

Connect to the Materialize Console

1. To connect to the Materialize Console, open a browser to https://<nlb_dns_name>:8080, substituting your <nlb_dns_name>.

   From the terminal, you can type:

   open "https://$(terraform output -raw  nlb_dns_name):8080/materialize"
   

   💡 Tip: The example uses a self-signed ClusterIssuer. As such, you may encounter a warning with regards to the certificate. In production, run with certificates from an official Certificate Authority (CA) rather than self-signed certificates.

2. Log in as mz_system, using external_login_password_mz_system as the password.

3. Create new users and log out.

   In general, other than the initial login to create new users for new deployments, avoid using mz_system since mz_system also used by the Materialize Operator for upgrades and maintenance tasks.

   For more information on authentication and authorization for Self-Managed Materialize, see:

   • Authentication
   • Access Control

4. Login as one of the created user.

Connect using psql

1. To connect using psql, in the connection string, specify:

   • mz_system as the user
   • Your <nlb_dns_name> as the host
   • 6875 as the port:

   psql "postgres://mz_system@$(terraform output -raw  nlb_dns_name):6875/materialize"
   

   When prompted for the password, enter the external_login_password_mz_system value.

2. Create new users and log out.

   In general, other than the initial login to create new users for new deployments, avoid using mz_system since mz_system also used by the Materialize Operator for upgrades and maintenance tasks.

   For more information on authentication and authorization for Self-Managed Materialize, see:

   • Authentication
   • Access Control

3. Login as one of the created user.

Customizing Your Deployment

You can customize each Terraform module independently.

• For details on the Terraform modules, see both the top level and AWS specific READMEs.

• For details on recommended instance sizing and configuration, see the AWS deployment guide.

See also:

• Configuring System Parameters
• Materialize Operator Configuration
• Materialize CRD Field Descriptions

Cleanup

To delete the whole sample infrastructure and deployment (including the Materialize operator and Materialize instances and data), run from the Terraform directory:

terraform destroy

When prompted to proceed, type yes to confirm the deletion.

See Also

• Troubleshooting
• Security