Home  /  Install/Upgrade (Self-Managed)

Appendix: Materialize CRD Field Descriptions

MaterializeSpec

Field Name Required Description
environmentdImageRef ✅ String
The environmentd image to run.
environmentdExtraArgs Array<String>
Extra args to pass to the environmentd binary.
environmentdExtraEnv Array<io.k8s.api.core.v1.EnvVar>
Extra environment variables to pass to the environmentd binary.
environmentdIamRoleArn String
DEPRECATED If running in AWS, override the IAM role to use to give environmentd access to the persist S3 bucket. DEPRECATED Use service_account_annotations to set “eks.amazonaws.com/role-arn” instead.
environmentdConnectionRoleArn String
If running in AWS, override the IAM role to use to support the CREATE CONNECTION feature.
environmentdResourceRequirements io.k8s.api.core.v1.ResourceRequirements
Resource requirements for the environmentd pod.
environmentdScratchVolumeStorageRequirement io.k8s.apimachinery.pkg.api.resource.Quantity
Amount of disk to allocate, if a storage class is provided.
balancerdResourceRequirements io.k8s.api.core.v1.ResourceRequirements
Resource requirements for the balancerd pod.
consoleResourceRequirements io.k8s.api.core.v1.ResourceRequirements
Resource requirements for the console pod.
balancerdReplicas Integer
Number of balancerd pods to create.
consoleReplicas Integer
Number of console pods to create.
serviceAccountName String
Name of the kubernetes service account to use. If not set, we will create one with the same name as this Materialize object.
serviceAccountAnnotations Map<String, String>

Annotations to apply to the service account.

Annotations on service accounts are commonly used by cloud providers for IAM. AWS uses “eks.amazonaws.com/role-arn”. Azure uses “azure.workload.identity/client-id”, but additionally requires “azure.workload.identity/use”: “true” on the pods.
serviceAccountLabels Map<String, String>
Labels to apply to the service account.
podAnnotations Map<String, String>
Annotations to apply to the pods.
podLabels Map<String, String>
Labels to apply to the pods.
requestRollout Uuid

When changes are made to the environmentd resources (either via modifying fields in the spec here or by deploying a new orchestratord version which changes how resources are generated), existing environmentd processes won’t be automatically restarted. In order to trigger a restart, the request_rollout field should be set to a new (random) value. Once the rollout completes, the value of status.lastCompletedRolloutRequest will be set to this value to indicate completion.

Defaults to a random value in order to ensure that the first generation rollout is automatically triggered.



Default: 00000000-0000-0000-0000-000000000000
forcePromote Uuid
If forcePromote is set to the same value as requestRollout, the current rollout will skip waiting for clusters in the new generation to rehydrate before promoting the new environmentd to leader.

Default: 00000000-0000-0000-0000-000000000000
forceRollout Uuid
This value will be written to an annotation in the generated environmentd statefulset, in order to force the controller to detect the generated resources as changed even if no other changes happened. This can be used to force a rollout to a new generation even without making any meaningful changes, by setting it to the same value as requestRollout.

Default: 00000000-0000-0000-0000-000000000000
inPlaceRollout Bool
Deprecated and ignored. Use rolloutStrategy instead.
rolloutStrategy Enum

Rollout strategy to use when upgrading this Materialize instance.

Valid values:

  • WaitUntilReady (default):
    Create a new generation of pods, leaving the old generation around until the new ones are ready to take over. This minimizes downtime, and is what almost everyone should use.

  • ImmediatelyPromoteCausingDowntime:

    WARNING!

    THIS WILL CAUSE YOUR MATERIALIZE INSTANCE TO BE UNAVAILABLE FOR SOME TIME!!!

    This strategy should ONLY be used by customers with physical hardware who do not have enough hardware for the WaitUntilReady strategy. If you think you want this, please consult with Materialize engineering to discuss your situation.

    Tear down the old generation of pods and promote the new generation of pods immediately, without waiting for the new generation of pods to be ready.



Default: WaitUntilReady
backendSecretName ✅ String
The name of a secret containing metadata_backend_url and persist_backend_url. It may also contain external_login_password_mz_system, which will be used as the password for the mz_system user if authenticatorKind is Password.
authenticatorKind Enum

How to authenticate with Materialize.

Valid values:

  • Frontegg:
    Authenticate users using Frontegg.
  • Password:
    Authenticate users using internally stored password hashes. The backend secret must contain external_login_password_mz_system.
  • Sasl:
    Authenticate users using SASL.
  • None (default):
    Do not authenticate users. Trust they are who they say they are without verification.


Default: None
enableRbac Bool
Whether to enable role based access control. Defaults to false.
environmentId Uuid
The value used by environmentd (via the –environment-id flag) to uniquely identify this instance. Must be globally unique, and is required if a license key is not provided. NOTE: This value MUST NOT be changed in an existing instance, since it affects things like the way data is stored in the persist backend.

Default: 00000000-0000-0000-0000-000000000000
balancerdExternalCertificateSpec MaterializeCertSpec
The configuration for generating an x509 certificate using cert-manager for balancerd to present to incoming connections. The dnsNames and issuerRef fields are required.
consoleExternalCertificateSpec MaterializeCertSpec
The configuration for generating an x509 certificate using cert-manager for the console to present to incoming connections. The dnsNames and issuerRef fields are required. Not yet implemented.
internalCertificateSpec MaterializeCertSpec
The cert-manager Issuer or ClusterIssuer to use for database internal communication. The issuerRef field is required. This currently is only used for environmentd, but will eventually support clusterd.

MaterializeCertSpec

Field Name Required Description
dnsNames Array<String>
Additional DNS names the certificate will be valid for.
duration String
Duration the certificate will be requested for. Value must be in units accepted by Go time.ParseDuration.
renewBefore String
Duration before expiration the certificate will be renewed. Value must be in units accepted by Go time.ParseDuration.
issuerRef CertificateIssuerRef
Reference to an Issuer or ClusterIssuer that will generate the certificate.
secretTemplate CertificateSecretTemplate
Additional annotations and labels to include in the Certificate object.

CertificateSecretTemplate

Field Name Required Description
annotations Map<String, String>
Annotations is a key value map to be copied to the target Kubernetes Secret.
labels Map<String, String>
Labels is a key value map to be copied to the target Kubernetes Secret.

CertificateIssuerRef

Field Name Required Description
group String
Group of the resource being referred to.
kind String
Kind of the resource being referred to.
name ✅ String
Name of the resource being referred to.

io.k8s.api.core.v1.ResourceRequirements

Field Name Required Description
claims Array<io.k8s.api.core.v1.ResourceClaim>

Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container.

This is an alpha field and requires enabling the DynamicResourceAllocation feature gate.

This field is immutable. It can only be set for containers.
limits Map<String, io.k8s.apimachinery.pkg.api.resource.Quantity>
Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
requests Map<String, io.k8s.apimachinery.pkg.api.resource.Quantity>
Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

io.k8s.api.core.v1.ResourceClaim

Field Name Required Description
name ✅ String
Name must match the name of one entry in pod.spec.resourceClaims of the Pod where this field is used. It makes that resource available inside a container.
request String
Request is the name chosen for a request in the referenced claim. If empty, everything from the claim is made available, otherwise only the result of this request.

io.k8s.api.core.v1.EnvVar

Field Name Required Description
name ✅ String
Name of the environment variable. Must be a C_IDENTIFIER.
value String
Variable references $(VAR_NAME) are expanded using the previously defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to “”.
valueFrom io.k8s.api.core.v1.EnvVarSource
Source for the environment variable’s value. Cannot be used if value is not empty.

io.k8s.api.core.v1.EnvVarSource

Field Name Required Description
configMapKeyRef io.k8s.api.core.v1.ConfigMapKeySelector
Selects a key of a ConfigMap.
fieldRef io.k8s.api.core.v1.ObjectFieldSelector
Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels['<KEY>'], metadata.annotations['<KEY>'], spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs.
resourceFieldRef io.k8s.api.core.v1.ResourceFieldSelector
Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported.
secretKeyRef io.k8s.api.core.v1.SecretKeySelector
Selects a key of a secret in the pod’s namespace

io.k8s.api.core.v1.SecretKeySelector

Field Name Required Description
key ✅ String
The key of the secret to select from. Must be a valid secret key.
name ✅ String
Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
optional Bool
Specify whether the Secret or its key must be defined

io.k8s.api.core.v1.ResourceFieldSelector

Field Name Required Description
containerName String
Container name: required for volumes, optional for env vars
divisor io.k8s.apimachinery.pkg.api.resource.Quantity
Specifies the output format of the exposed resources, defaults to “1”
resource ✅ String
Required: resource to select

io.k8s.api.core.v1.ObjectFieldSelector

Field Name Required Description
apiVersion String
Version of the schema the FieldPath is written in terms of, defaults to “v1”.
fieldPath ✅ String
Path of the field to select in the specified API version.

io.k8s.api.core.v1.ConfigMapKeySelector

Field Name Required Description
key ✅ String
The key to select.
name ✅ String
Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
optional Bool
Specify whether the ConfigMap or its key must be defined
Back to top ↑