Install on Azure

Materialize provides a set of modular Terraform modules that can be used to deploy all services required for Materialize to run on Azure. The module is intended to provide a simple set of examples on how to deploy Materialize. It can be used as is or modules can be taken from the example and integrated with existing DevOps tooling.

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 Azure using the modular Terraform setup from this repository.

What Gets Created

This example provisions the following infrastructure:

Resource Group

Networking

Compute

Database

Storage

Kubernetes Add-ons

Materialize

Prerequisites

Azure Account Requirements

An active Azure subscription with appropriate permissions to create:

• AKS clusters
• Azure PostgreSQL Flexible Server instances
• Storage accounts
• Virtual networks and networking resources
• Managed identities and role assignments

Required Tools

• Terraform
• Azure 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 azure/examples/simple directory.

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

3. Authenticate with Azure.

   az login
   

   The command opens a browser window to sign in to Azure. Sign in.

4. Select the subscription and tenant to use. After you have signed in, back in the terminal, your tenant and subscription information is displayed.

   Retrieving tenants and subscriptions for the selection...
   
   [Tenant and subscription selection]
   
   No     Subscription name    Subscription ID                       Tenant
   -----  -------------------  ------------------------------------  ----------------
   [1]*   ...                  ...                                   ...
   
   The default is marked with an *; the default tenant is '<Tenant>' and
   subscription is '<Subscription Name>' (<Subscription ID>).
   

   Select the subscription and tenant.

Step 2: Configure Terraform Variables

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

   • subscription_id: Azure subscription ID
   • resource_group_name: Name for the resource group to create (e.g. mz-demo-rg)
   • name_prefix: Prefix for all resource names (e.g., simple-demo)
   • location: Azure region for deployment (e.g., westus2)
   • license_key: Materialize license key
   • tags: Map of tags to apply to resources

   subscription_id     = "your-subscription-id"
   resource_group_name = "mz-demo-rg"
   name_prefix         = "simple-demo"
   location            = "westus2"
   license_key         = "your-materialize-license-key"
   tags = {
     environment = "demo"
   }
   

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.

   • To deploy with the default internal NLB for Materialize access:

   terraform apply
   

   • To deploy with public NLB for Materialize access:

   terraform apply -var="internal=false"
   

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

3. From the output, you will need the following field(s) to connect:

   • console_load_balancer_ip for the Materialize Console
   • balancerd_load_balancer_ip to connect PostgreSQL-compatible clients/drivers.

   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-resource-group-name> with your resource group name; i.e., the resource_group_name in the Terraform output or in the terraform.tfvars file.

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

   # az aks get-credentials --resource-group <your-resource-group-name> --name <your-aks-cluster-name>
   az aks get-credentials --resource-group $(terraform output -raw resource_group_name) --name $(terraform output -raw aks_cluster_name)
   

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

Connect using the Materialize Console

Using the console_load_balancer_ip from the Terraform output, you can connect to Materialize via the Materialize Console.

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

From the terminal, you can type:

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

Connect using the psql

Using the balancerd_load_balancer_ip value from the Terraform output, you can connect to Materialize via PostgreSQL-compatible clients/drivers, such as psql:

psql "postgres://$(terraform output -raw balancerd_load_balancer_ip):6875/materialize"

Customizing Your Deployment

You can customize each Terraform module independently.

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

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

See also:

• 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

• Materialize Operator Configuration
• Troubleshooting