Configuring System Parameters

This guide explains how to configure system parameters for your Materialize deployment using a Kubernetes ConfigMap.

Overview

System parameters allow you to customize the behavior of your Materialize instance at runtime. These parameters can control various aspects such as connection limits, cluster replica sizes, and other operational settings.

There are two ways to configure system parameters:

• Using SQL: Connect to your Materialize instance and use the ALTER SYSTEM SET command to modify parameters dynamically. This is useful for one-off changes or testing.

• Using a ConfigMap: Create a Kubernetes ConfigMap containing the parameters in JSON format and reference it in your Materialize custom resource. This is the recommended approach for persistent configuration that survives restarts and upgrades.

This guide focuses on the ConfigMap approach for self-managed deployments.

{{< public-preview />}}

Configure System Parameters via ConfigMap

Step 1: Create a System Parameters ConfigMap

In the same namespace as your Materialize environment, create a ConfigMap that includes a key named system-params.json. Set system-params.json to a valid JSON object containing your desired system parameters.

apiVersion: v1
kind: ConfigMap
metadata:
  name: mz-system-params
  namespace: materialize-environment
data:
  system-params.json: |
    {
      "max_connections": 1000,
      "allowed_cluster_replica_sizes": "'25cc', '50cc', '100cc'"
    }

Apply the ConfigMap to your cluster:

kubectl apply -f system-params-configmap.yaml

Step 2: Configure the Materialize Custom Resource

Reference the ConfigMap in your Materialize custom resource by setting the systemParameterConfigmapName field to the name of your ConfigMap:

apiVersion: materialize.cloud/v1alpha1
kind: Materialize
metadata:
  name: 12345678-1234-1234-1234-123456789012
  namespace: materialize-environment
spec:
  environmentdImageRef: materialize/environmentd:v26.0.0
  backendSecretName: materialize-backend
  systemParameterConfigmapName: mz-system-params

Apply the updated Materialize resource:

kubectl apply -f materialize.yaml

Updating ConfigMap System Parameters

To update system parameters defined in your ConfigMap, you can either:

• Use kubectl edit configmap to edit the ConfigMap and apply the changes:

  shellCopy

  kubectl edit configmap mz-system-params -n materialize-environment
  

• Or, edit the ConfigMap YAML file and reapply:

  shellCopy

  kubectl apply -f system-params-configmap.yaml
  

ConfigMap sync behavior

Kubernetes uses the kubelet to periodically sync ConfigMap updates to mounted volumes. By default, this sync occurs approximately every 60 seconds. This means changes to your ConfigMap may take up to a minute to be reflected in the running Materialize instance.

Once the ConfigMap is synced to the volume, Materialize checks for configuration changes every second and applies them automatically.

To force an immediate sync of the ConfigMap from Kubernetes, you can update an annotation on the Materialize resource, which triggers a pod re-reconciliation:

kubectl annotate materialize <instance-name> \
  -n materialize-environment \
  configmap-reload-trigger="$(date +%s)" \
  --overwrite

Alternatively, you can add the configmap-reload-trigger annotation to your Materialize custom resource YAML and update it whenever you need to force a ConfigMap reload:

apiVersion: materialize.cloud/v1alpha1
kind: Materialize
metadata:
  name: 12345678-1234-1234-1234-123456789012
  namespace: materialize-environment
  annotations:
    configmap-reload-trigger: "1234567890"  # Update this value to force reload
spec:
  # ... rest of spec

{{< note >}} Even after the ConfigMap is synced, some parameters may require a restart to take effect. {{< /note >}}

Available System Parameters

The system parameters that can be configured via the ConfigMap are the same parameters that can be modified using the ALTER SYSTEM SET SQL command.

The following are some commonly configured system parameters:

For a complete list of available system parameters and their descriptions, see the configuration parameters documentation, or run the following SQL command in your Materialize instance:

SHOW ALL;

Sample ConfigMap: Setting Connection Limits

The following sample ConfigMap YAML sets the max_connections parameter:

apiVersion: v1
kind: ConfigMap
metadata:
  name: mz-system-params
  namespace: materialize-environment
data:
  system-params.json: |
    {
      "max_connections": 500
    }

Sample ConfigMap: Configuring Allowed Cluster Sizes

The following sample ConfigMap YAML sets the allowed_cluster_replica_sizes parameter:

apiVersion: v1
kind: ConfigMap
metadata:
  name: mz-system-params
  namespace: materialize-environment
data:
  system-params.json: |
    {
      "allowed_cluster_replica_sizes": "'25cc', '50cc', '100cc', '200cc'"
    }

Sample ConfigMap: Configuring Connection Limits and Allowed Cluster Sizes

The following sample ConfigMap YAML sets both the max_connections parameter and the allowed_cluster_replica_sizes parameter:

apiVersion: v1
kind: ConfigMap
metadata:
  name: mz-system-params
  namespace: materialize-environment
data:
  system-params.json: |
    {
      "max_connections": 500,
      "allowed_cluster_replica_sizes": "'25cc', '50cc', '100cc', '200cc'"
    }

Troubleshooting

ConfigMap not being applied

If your system parameters are not being applied, check the following:

1. Verify the ConfigMap exists in the correct namespace:

   shellCopy

   kubectl get configmap mz-system-params -n materialize-environment
   

2. Check the ConfigMap content is valid JSON:

   shellCopy

   kubectl get configmap mz-system-params -n materialize-environment -o jsonpath='{.data.system-params\.json}'
   

3. Verify the Materialize resource references the correct ConfigMap name:

   shellCopy

   kubectl get materialize -n materialize-environment -o yaml | grep systemParameterConfigmapName
   

4. Check environmentd logs for any errors related to configuration loading:

   shellCopy

   kubectl logs -l app=environmentd -n materialize-environment
   

Invalid parameter values

If a system parameter value is invalid, Materialize will log an error but continue running with the previous valid configuration. Check the environmentd logs for error messages:

kubectl logs -l app=environmentd -n materialize-environment | grep -i "system.*param"

See also

• Materialize Operator Configuration
• Materialize CRD Field Descriptions
• Troubleshooting