diff --git a/doc/user/data/self_managed/materialize_crd_descriptions.json b/doc/user/data/self_managed/materialize_crd_descriptions.json
index 6537c3ffe6414..f1355144aeb01 100644
--- a/doc/user/data/self_managed/materialize_crd_descriptions.json
+++ b/doc/user/data/self_managed/materialize_crd_descriptions.json
@@ -3,200 +3,228 @@
     "MaterializeSpec",
     [
       {
-        "name": "environmentdImageRef",
+        "name": "backendSecretName",
         "type": "String",
-        "description": "The environmentd image to run.",
+        "description": "The name of a secret containing `metadata_backend_url` and `persist_backend_url`.\nIt may also contain `external_login_password_mz_system`, which will be used as\nthe password for the `mz_system` user if `authenticatorKind` is `Password`.",
         "default": null,
-        "required": true
+        "required": true,
+        "deprecated": false
       },
       {
-        "name": "environmentdExtraArgs",
-        "type": "Array<String>",
-        "description": "Extra args to pass to the environmentd binary.",
+        "name": "environmentdImageRef",
+        "type": "String",
+        "description": "The environmentd image to run.",
         "default": null,
-        "required": false
+        "required": true,
+        "deprecated": false
       },
       {
-        "name": "environmentdExtraEnv",
-        "type": "Array<io.k8s.api.core.v1.EnvVar>",
-        "description": "Extra environment variables to pass to the environmentd binary.",
-        "default": null,
-        "required": false
+        "name": "authenticatorKind",
+        "type": "Enum",
+        "description": "How to authenticate with Materialize.\n\nValid values:\n- `Frontegg`:<br>  Authenticate users using Frontegg.\n- `Password`:<br>  Authenticate users using internally stored password hashes.\n  The backend secret must contain external_login_password_mz_system.\n- `Sasl`:<br>  Authenticate users using SASL.\n- `None` (default):<br>  Do not authenticate users. Trust they are who they say they are without verification.",
+        "default": "None",
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "environmentdIamRoleArn",
-        "type": "String",
-        "description": "DEPRECATED\nIf running in AWS, override the IAM role to use to give\nenvironmentd access to the persist S3 bucket.\nDEPRECATED\nUse `service_account_annotations` to set \"eks.amazonaws.com/role-arn\" instead.",
+        "name": "balancerdExternalCertificateSpec",
+        "type": "MaterializeCertSpec",
+        "description": "The configuration for generating an x509 certificate using cert-manager for balancerd\nto present to incoming connections.\nThe `dnsNames` and `issuerRef` fields are required.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "environmentdConnectionRoleArn",
-        "type": "String",
-        "description": "If running in AWS, override the IAM role to use to support\nthe CREATE CONNECTION feature.",
+        "name": "balancerdReplicas",
+        "type": "Integer",
+        "description": "Number of balancerd pods to create.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "environmentdResourceRequirements",
+        "name": "balancerdResourceRequirements",
         "type": "io.k8s.api.core.v1.ResourceRequirements",
-        "description": "Resource requirements for the environmentd pod.",
+        "description": "Resource requirements for the balancerd pod.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "environmentdScratchVolumeStorageRequirement",
-        "type": "io.k8s.apimachinery.pkg.api.resource.Quantity",
-        "description": "Amount of disk to allocate, if a storage class is provided.",
+        "name": "consoleExternalCertificateSpec",
+        "type": "MaterializeCertSpec",
+        "description": "The configuration for generating an x509 certificate using cert-manager for the console\nto present to incoming connections.\nThe `dnsNames` and `issuerRef` fields are required.\nNot yet implemented.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "balancerdResourceRequirements",
-        "type": "io.k8s.api.core.v1.ResourceRequirements",
-        "description": "Resource requirements for the balancerd pod.",
+        "name": "consoleReplicas",
+        "type": "Integer",
+        "description": "Number of console pods to create.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
         "name": "consoleResourceRequirements",
         "type": "io.k8s.api.core.v1.ResourceRequirements",
         "description": "Resource requirements for the console pod.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "balancerdReplicas",
-        "type": "Integer",
-        "description": "Number of balancerd pods to create.",
-        "default": null,
-        "required": false
+        "name": "enableRbac",
+        "type": "Bool",
+        "description": "Whether to enable role based access control. Defaults to false.",
+        "default": false,
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "consoleReplicas",
-        "type": "Integer",
-        "description": "Number of console pods to create.",
-        "default": null,
-        "required": false
+        "name": "environmentId",
+        "type": "Uuid",
+        "description": "The value used by environmentd (via the --environment-id flag) to\nuniquely identify this instance. Must be globally unique, and\nis required if a license key is not provided.\nNOTE: This value MUST NOT be changed in an existing instance,\nsince it affects things like the way data is stored in the persist\nbackend.",
+        "default": "00000000-0000-0000-0000-000000000000",
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "serviceAccountName",
+        "name": "environmentdConnectionRoleArn",
         "type": "String",
-        "description": "Name of the kubernetes service account to use.\nIf not set, we will create one with the same name as this Materialize object.",
+        "description": "If running in AWS, override the IAM role to use to support\nthe CREATE CONNECTION feature.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "serviceAccountAnnotations",
-        "type": "Map<String, String>",
-        "description": "Annotations to apply to the service account.\n\nAnnotations on service accounts are commonly used by cloud providers for IAM.\nAWS uses \"eks.amazonaws.com/role-arn\".\nAzure uses \"azure.workload.identity/client-id\", but\nadditionally requires \"azure.workload.identity/use\": \"true\" on the pods.",
+        "name": "environmentdExtraArgs",
+        "type": "Array<String>",
+        "description": "Extra args to pass to the environmentd binary.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "serviceAccountLabels",
-        "type": "Map<String, String>",
-        "description": "Labels to apply to the service account.",
+        "name": "environmentdExtraEnv",
+        "type": "Array<io.k8s.api.core.v1.EnvVar>",
+        "description": "Extra environment variables to pass to the environmentd binary.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "podAnnotations",
-        "type": "Map<String, String>",
-        "description": "Annotations to apply to the pods.",
+        "name": "environmentdResourceRequirements",
+        "type": "io.k8s.api.core.v1.ResourceRequirements",
+        "description": "Resource requirements for the environmentd pod.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "podLabels",
-        "type": "Map<String, String>",
-        "description": "Labels to apply to the pods.",
+        "name": "environmentdScratchVolumeStorageRequirement",
+        "type": "io.k8s.apimachinery.pkg.api.resource.Quantity",
+        "description": "Amount of disk to allocate, if a storage class is provided.",
         "default": null,
-        "required": false
-      },
-      {
-        "name": "requestRollout",
-        "type": "Uuid",
-        "description": "When changes are made to the environmentd resources (either via\nmodifying fields in the spec here or by deploying a new\norchestratord version which changes how resources are generated),\nexisting environmentd processes won't be automatically restarted.\nIn order to trigger a restart, the request_rollout field should be\nset to a new (random) value. Once the rollout completes, the value\nof `status.lastCompletedRolloutRequest` will be set to this value\nto indicate completion.\n\nDefaults to a random value in order to ensure that the first\ngeneration rollout is automatically triggered.",
-        "default": "00000000-0000-0000-0000-000000000000",
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
         "name": "forcePromote",
         "type": "Uuid",
         "description": "If `forcePromote` is set to the same value as `requestRollout`, the\ncurrent rollout will skip waiting for clusters in the new\ngeneration to rehydrate before promoting the new environmentd to\nleader.",
         "default": "00000000-0000-0000-0000-000000000000",
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
         "name": "forceRollout",
         "type": "Uuid",
         "description": "This value will be written to an annotation in the generated\nenvironmentd statefulset, in order to force the controller to\ndetect the generated resources as changed even if no other changes\nhappened. This can be used to force a rollout to a new generation\neven without making any meaningful changes, by setting it to the\nsame value as `requestRollout`.",
         "default": "00000000-0000-0000-0000-000000000000",
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "inPlaceRollout",
-        "type": "Bool",
-        "description": "Deprecated and ignored. Use `rolloutStrategy` instead.",
-        "default": false,
-        "required": false
+        "name": "internalCertificateSpec",
+        "type": "MaterializeCertSpec",
+        "description": "The cert-manager Issuer or ClusterIssuer to use for database internal communication.\nThe `issuerRef` field is required.\nThis currently is only used for environmentd, but will eventually support clusterd.",
+        "default": null,
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "rolloutStrategy",
-        "type": "Enum",
-        "description": "Rollout strategy to use when upgrading this Materialize instance.\n\nValid values:\n- `WaitUntilReady` (default):<br>  Create a new generation of pods, leaving the old generation around until the\n  new ones are ready to take over.\n  This minimizes downtime, and is what almost everyone should use.\n- `ImmediatelyPromoteCausingDowntime`:<br>  {{<warning>}}\n  THIS WILL CAUSE YOUR MATERIALIZE INSTANCE TO BE UNAVAILABLE FOR SOME TIME!!!\n  \n  This strategy should ONLY be used by customers with physical hardware who do not have\n  enough hardware for the `WaitUntilReady` strategy. If you think you want this, please\n  consult with Materialize engineering to discuss your situation.\n  {{</warning>}}\n  \n  Tear down the old generation of pods and promote the new generation of pods immediately,\n  without waiting for the new generation of pods to be ready.",
-        "default": "WaitUntilReady",
-        "required": false
+        "name": "podAnnotations",
+        "type": "Map<String, String>",
+        "description": "Annotations to apply to the pods.",
+        "default": null,
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "backendSecretName",
-        "type": "String",
-        "description": "The name of a secret containing `metadata_backend_url` and `persist_backend_url`.\nIt may also contain `external_login_password_mz_system`, which will be used as\nthe password for the `mz_system` user if `authenticatorKind` is `Password`.",
+        "name": "podLabels",
+        "type": "Map<String, String>",
+        "description": "Labels to apply to the pods.",
         "default": null,
-        "required": true
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "authenticatorKind",
-        "type": "Enum",
-        "description": "How to authenticate with Materialize.\n\nValid values:\n- `Frontegg`:<br>  Authenticate users using Frontegg.\n- `Password`:<br>  Authenticate users using internally stored password hashes.\n  The backend secret must contain external_login_password_mz_system.\n- `Sasl`:<br>  Authenticate users using SASL.\n- `None` (default):<br>  Do not authenticate users. Trust they are who they say they are without verification.",
-        "default": "None",
-        "required": false
+        "name": "requestRollout",
+        "type": "Uuid",
+        "description": "When changes are made to the environmentd resources (either via\nmodifying fields in the spec here or by deploying a new\norchestratord version which changes how resources are generated),\nexisting environmentd processes won't be automatically restarted.\nIn order to trigger a restart, the request_rollout field should be\nset to a new (random) value. Once the rollout completes, the value\nof `status.lastCompletedRolloutRequest` will be set to this value\nto indicate completion.\n\nDefaults to a random value in order to ensure that the first\ngeneration rollout is automatically triggered.",
+        "default": "00000000-0000-0000-0000-000000000000",
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "enableRbac",
-        "type": "Bool",
-        "description": "Whether to enable role based access control. Defaults to false.",
-        "default": false,
-        "required": false
+        "name": "rolloutStrategy",
+        "type": "Enum",
+        "description": "Rollout strategy to use when upgrading this Materialize instance.\n\nValid values:\n- `WaitUntilReady` (default):<br>  Create a new generation of pods, leaving the old generation around until the\n  new ones are ready to take over.\n  This minimizes downtime, and is what almost everyone should use.\n- `ImmediatelyPromoteCausingDowntime`:<br>  {{<warning>}}\n  THIS WILL CAUSE YOUR MATERIALIZE INSTANCE TO BE UNAVAILABLE FOR SOME TIME!!!\n  \n  This strategy should ONLY be used by customers with physical hardware who do not have\n  enough hardware for the `WaitUntilReady` strategy. If you think you want this, please\n  consult with Materialize engineering to discuss your situation.\n  {{</warning>}}\n  \n  Tear down the old generation of pods and promote the new generation of pods immediately,\n  without waiting for the new generation of pods to be ready.",
+        "default": "WaitUntilReady",
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "environmentId",
-        "type": "Uuid",
-        "description": "The value used by environmentd (via the --environment-id flag) to\nuniquely identify this instance. Must be globally unique, and\nis required if a license key is not provided.\nNOTE: This value MUST NOT be changed in an existing instance,\nsince it affects things like the way data is stored in the persist\nbackend.",
-        "default": "00000000-0000-0000-0000-000000000000",
-        "required": false
+        "name": "serviceAccountAnnotations",
+        "type": "Map<String, String>",
+        "description": "Annotations to apply to the service account.\n\nAnnotations on service accounts are commonly used by cloud providers for IAM.\nAWS uses \"eks.amazonaws.com/role-arn\".\nAzure uses \"azure.workload.identity/client-id\", but\nadditionally requires \"azure.workload.identity/use\": \"true\" on the pods.",
+        "default": null,
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "balancerdExternalCertificateSpec",
-        "type": "MaterializeCertSpec",
-        "description": "The configuration for generating an x509 certificate using cert-manager for balancerd\nto present to incoming connections.\nThe `dnsNames` and `issuerRef` fields are required.",
+        "name": "serviceAccountLabels",
+        "type": "Map<String, String>",
+        "description": "Labels to apply to the service account.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "consoleExternalCertificateSpec",
-        "type": "MaterializeCertSpec",
-        "description": "The configuration for generating an x509 certificate using cert-manager for the console\nto present to incoming connections.\nThe `dnsNames` and `issuerRef` fields are required.\nNot yet implemented.",
+        "name": "serviceAccountName",
+        "type": "String",
+        "description": "Name of the kubernetes service account to use.\nIf not set, we will create one with the same name as this Materialize object.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "internalCertificateSpec",
-        "type": "MaterializeCertSpec",
-        "description": "The cert-manager Issuer or ClusterIssuer to use for database internal communication.\nThe `issuerRef` field is required.\nThis currently is only used for environmentd, but will eventually support clusterd.",
+        "name": "environmentdIamRoleArn",
+        "type": "String",
+        "description": "{{<warning>}}\nDeprecated.\n\nUse `service_account_annotations` to set \"eks.amazonaws.com/role-arn\" instead.\n{{</warning>}}\n\nIf running in AWS, override the IAM role to use to give\nenvironmentd access to the persist S3 bucket.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": true
+      },
+      {
+        "name": "inPlaceRollout",
+        "type": "Bool",
+        "description": "{{<warning>}}\nDeprecated and ignored. Use `rolloutStrategy` instead.\n{{</warning>}}",
+        "default": false,
+        "required": false,
+        "deprecated": true
       }
     ]
   ],
@@ -208,35 +236,40 @@
         "type": "Array<String>",
         "description": "Additional DNS names the certificate will be valid for.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
         "name": "duration",
         "type": "String",
         "description": "Duration the certificate will be requested for.\nValue must be in units accepted by Go\n[`time.ParseDuration`](https://golang.org/pkg/time/#ParseDuration).",
         "default": null,
-        "required": false
-      },
-      {
-        "name": "renewBefore",
-        "type": "String",
-        "description": "Duration before expiration the certificate will be renewed.\nValue must be in units accepted by Go\n[`time.ParseDuration`](https://golang.org/pkg/time/#ParseDuration).",
-        "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
         "name": "issuerRef",
         "type": "CertificateIssuerRef",
         "description": "Reference to an `Issuer` or `ClusterIssuer` that will generate the certificate.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
+      },
+      {
+        "name": "renewBefore",
+        "type": "String",
+        "description": "Duration before expiration the certificate will be renewed.\nValue must be in units accepted by Go\n[`time.ParseDuration`](https://golang.org/pkg/time/#ParseDuration).",
+        "default": null,
+        "required": false,
+        "deprecated": false
       },
       {
         "name": "secretTemplate",
         "type": "CertificateSecretTemplate",
         "description": "Additional annotations and labels to include in the Certificate object.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       }
     ]
   ],
@@ -248,14 +281,16 @@
         "type": "Map<String, String>",
         "description": "Annotations is a key value map to be copied to the target Kubernetes Secret.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
         "name": "labels",
         "type": "Map<String, String>",
         "description": "Labels is a key value map to be copied to the target Kubernetes Secret.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       }
     ]
   ],
@@ -263,25 +298,28 @@
     "CertificateIssuerRef",
     [
       {
-        "name": "group",
+        "name": "name",
         "type": "String",
-        "description": "Group of the resource being referred to.",
+        "description": "Name of the resource being referred to.",
         "default": null,
-        "required": false
+        "required": true,
+        "deprecated": false
       },
       {
-        "name": "kind",
+        "name": "group",
         "type": "String",
-        "description": "Kind of the resource being referred to.",
+        "description": "Group of the resource being referred to.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
-        "name": "name",
+        "name": "kind",
         "type": "String",
-        "description": "Name of the resource being referred to.",
+        "description": "Kind of the resource being referred to.",
         "default": null,
-        "required": true
+        "required": false,
+        "deprecated": false
       }
     ]
   ],
@@ -293,21 +331,24 @@
         "type": "Array<io.k8s.api.core.v1.ResourceClaim>",
         "description": "Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container.\n\nThis is an alpha field and requires enabling the DynamicResourceAllocation feature gate.\n\nThis field is immutable. It can only be set for containers.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
         "name": "limits",
         "type": "Map<String, io.k8s.apimachinery.pkg.api.resource.Quantity>",
         "description": "Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
         "name": "requests",
         "type": "Map<String, io.k8s.apimachinery.pkg.api.resource.Quantity>",
         "description": "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/",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       }
     ]
   ],
@@ -319,14 +360,16 @@
         "type": "String",
         "description": "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.",
         "default": null,
-        "required": true
+        "required": true,
+        "deprecated": false
       },
       {
         "name": "request",
         "type": "String",
         "description": "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.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       }
     ]
   ],
@@ -338,21 +381,24 @@
         "type": "String",
         "description": "Name of the environment variable. Must be a C_IDENTIFIER.",
         "default": null,
-        "required": true
+        "required": true,
+        "deprecated": false
       },
       {
         "name": "value",
         "type": "String",
         "description": "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 \"\".",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
         "name": "valueFrom",
         "type": "io.k8s.api.core.v1.EnvVarSource",
         "description": "Source for the environment variable's value. Cannot be used if value is not empty.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       }
     ]
   ],
@@ -364,28 +410,32 @@
         "type": "io.k8s.api.core.v1.ConfigMapKeySelector",
         "description": "Selects a key of a ConfigMap.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
         "name": "fieldRef",
         "type": "io.k8s.api.core.v1.ObjectFieldSelector",
         "description": "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.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
         "name": "resourceFieldRef",
         "type": "io.k8s.api.core.v1.ResourceFieldSelector",
         "description": "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.",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
         "name": "secretKeyRef",
         "type": "io.k8s.api.core.v1.SecretKeySelector",
         "description": "Selects a key of a secret in the pod's namespace",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       }
     ]
   ],
@@ -397,47 +447,53 @@
         "type": "String",
         "description": "The key of the secret to select from.  Must be a valid secret key.",
         "default": null,
-        "required": true
+        "required": true,
+        "deprecated": false
       },
       {
         "name": "name",
         "type": "String",
         "description": "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",
         "default": null,
-        "required": true
+        "required": true,
+        "deprecated": false
       },
       {
         "name": "optional",
         "type": "Bool",
         "description": "Specify whether the Secret or its key must be defined",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       }
     ]
   ],
   [
     "io.k8s.api.core.v1.ResourceFieldSelector",
     [
+      {
+        "name": "resource",
+        "type": "String",
+        "description": "Required: resource to select",
+        "default": null,
+        "required": true,
+        "deprecated": false
+      },
       {
         "name": "containerName",
         "type": "String",
         "description": "Container name: required for volumes, optional for env vars",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       },
       {
         "name": "divisor",
         "type": "io.k8s.apimachinery.pkg.api.resource.Quantity",
         "description": "Specifies the output format of the exposed resources, defaults to \"1\"",
         "default": null,
-        "required": false
-      },
-      {
-        "name": "resource",
-        "type": "String",
-        "description": "Required: resource to select",
-        "default": null,
-        "required": true
+        "required": false,
+        "deprecated": false
       }
     ]
   ],
@@ -445,18 +501,20 @@
     "io.k8s.api.core.v1.ObjectFieldSelector",
     [
       {
-        "name": "apiVersion",
+        "name": "fieldPath",
         "type": "String",
-        "description": "Version of the schema the FieldPath is written in terms of, defaults to \"v1\".",
+        "description": "Path of the field to select in the specified API version.",
         "default": null,
-        "required": false
+        "required": true,
+        "deprecated": false
       },
       {
-        "name": "fieldPath",
+        "name": "apiVersion",
         "type": "String",
-        "description": "Path of the field to select in the specified API version.",
+        "description": "Version of the schema the FieldPath is written in terms of, defaults to \"v1\".",
         "default": null,
-        "required": true
+        "required": false,
+        "deprecated": false
       }
     ]
   ],
@@ -468,21 +526,24 @@
         "type": "String",
         "description": "The key to select.",
         "default": null,
-        "required": true
+        "required": true,
+        "deprecated": false
       },
       {
         "name": "name",
         "type": "String",
         "description": "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",
         "default": null,
-        "required": true
+        "required": true,
+        "deprecated": false
       },
       {
         "name": "optional",
         "type": "Bool",
         "description": "Specify whether the ConfigMap or its key must be defined",
         "default": null,
-        "required": false
+        "required": false,
+        "deprecated": false
       }
     ]
   ]
diff --git a/doc/user/layouts/shortcodes/self-managed/materialize-crd-descriptions.html b/doc/user/layouts/shortcodes/self-managed/materialize-crd-descriptions.html
index 0ff0c880037a6..5c09e0cb47f88 100644
--- a/doc/user/layouts/shortcodes/self-managed/materialize-crd-descriptions.html
+++ b/doc/user/layouts/shortcodes/self-managed/materialize-crd-descriptions.html
@@ -1,3 +1,9 @@
+<!-- build a dict of type names -->
+{{ $types := dict }}
+{{ range $.Site.Data.self_managed.materialize_crd_descriptions }}
+{{ $types = merge $types (dict (index . 0) true) }}
+{{ end }}
+
 {{ range $.Site.Data.self_managed.materialize_crd_descriptions }}
 #### {{ index . 0 }}
 <table>
@@ -9,13 +15,43 @@
 </tr>
 </thead>
 <tbody>
-{{ range (index . 1) }}
+{{- range (index . 1) }}
+  {{- if not .deprecated }}
 <tr>
 <td><code>{{ .name }}</code></td>
 <td>{{ if .required }}✅{{ end }}</td>
-<td><em><strong>{{ .type }}</strong></em><br>{{ .description | markdownify }} {{ if .default }}<br><br><strong>Default:</strong> <code>{{ .default }}</code>{{ end }}</td>
+<td>
+<!-- Type -->
+  {{- $matches := findRESubmatch `(Array<|Map<String, )*([^>]+)(>*)` .type 1 -}}
+  {{- $captures := index $matches 0 -}}
+
+  {{- $typePrefix := index $captures 1 -}}
+  {{- $baseType := index $captures 2 -}}
+  {{- $typeSuffix := index $captures 3 -}}
+<em><strong>
+  {{- $typePrefix -}}
+  {{- if (index $types $baseType) -}}
+    <a href='#{{ replace $baseType "." "" | urlize}}'>
+  {{- end -}}
+  {{ $baseType }}
+  {{- if (index $types $baseType) -}}
+    </a>
+  {{- end -}}
+  {{- $typeSuffix -}}
+</strong></em>
+
+<!-- Description -->
+<p>{{- .description | markdownify -}}</p>
+
+<!-- Default value -->
+  {{- if .default -}}
+<p><strong>Default:</strong> <code>{{ .default }}</code></p>
+  {{- end -}}
+
+</td>
 </tr>
-{{ end }}
+  {{- end }}
+{{- end }}
 </tbody>
 </table>
 {{ end }}
diff --git a/src/cloud-resources/src/bin/crd_writer.rs b/src/cloud-resources/src/bin/crd_writer.rs
index 62926a11244d8..7a51c8386ba4e 100644
--- a/src/cloud-resources/src/bin/crd_writer.rs
+++ b/src/cloud-resources/src/bin/crd_writer.rs
@@ -7,18 +7,46 @@
 // the Business Source License, use of this software will be governed
 // by the Apache License, Version 2.0.
 
+use std::cmp::Ordering;
+
 use indexmap::{IndexMap, IndexSet};
 use mz_cloud_resources::crd::materialize::v1alpha1::MaterializeSpec;
 use schemars::schema_for;
 use serde::Serialize;
 
-#[derive(Serialize)]
+#[derive(Serialize, PartialEq, Eq)]
 struct DocsField {
     name: String,
     r#type: String,
     description: String,
     default: Option<serde_json::Value>,
     required: bool,
+    deprecated: bool,
+}
+impl PartialOrd for DocsField {
+    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+impl Ord for DocsField {
+    fn cmp(&self, other: &Self) -> Ordering {
+        match (
+            self.required,
+            other.required,
+            self.deprecated,
+            other.deprecated,
+        ) {
+            // required before other stuff
+            (true, false, _, _) => Ordering::Less,
+            (false, true, _, _) => Ordering::Greater,
+            // deprecated after other stuff
+            (_, _, true, false) => Ordering::Greater,
+            (_, _, false, true) => Ordering::Less,
+            // alphabetical otherwise
+            (_, _, _, _) => self.name.cmp(&other.name),
+        }
+    }
 }
 
 impl DocsField {
@@ -48,6 +76,7 @@ impl DocsField {
                     .to_owned();
                 let default = field_props.get("default").cloned();
                 let required = required_fields.contains(name);
+                let deprecated = description.to_lowercase().contains("deprecated");
 
                 // Get the field type (without nested fields)
                 let r#type = DocsField::extract_field_type(
@@ -68,6 +97,7 @@ impl DocsField {
                     description,
                     default,
                     required,
+                    deprecated,
                 });
             }
             types_map.insert(type_name.to_owned(), fields);
@@ -317,6 +347,13 @@ fn main() {
         &mut processed_types,
     );
 
-    let types_vec: Vec<(String, Vec<DocsField>)> = types_map.into_iter().rev().collect();
+    let types_vec: Vec<(String, Vec<DocsField>)> = types_map
+        .into_iter()
+        .rev()
+        .map(|(name, mut fields)| {
+            fields.sort();
+            (name, fields)
+        })
+        .collect();
     println!("{}", serde_json::to_string_pretty(&types_vec).unwrap());
 }
diff --git a/src/cloud-resources/src/crd/materialize.rs b/src/cloud-resources/src/crd/materialize.rs
index 6fff53c5c9ff1..8f617a5736553 100644
--- a/src/cloud-resources/src/crd/materialize.rs
+++ b/src/cloud-resources/src/crd/materialize.rs
@@ -102,11 +102,15 @@ pub mod v1alpha1 {
         pub environmentd_extra_args: Option<Vec<String>>,
         /// Extra environment variables to pass to the environmentd binary.
         pub environmentd_extra_env: Option<Vec<EnvVar>>,
-        /// DEPRECATED
+        /// {{<warning>}}
+        /// Deprecated.
+        ///
+        /// Use `service_account_annotations` to set "eks.amazonaws.com/role-arn" instead.
+        /// {{</warning>}}
+        ///
         /// 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.
+        #[kube(deprecated)]
         pub environmentd_iam_role_arn: Option<String>,
         /// If running in AWS, override the IAM role to use to support
         /// the CREATE CONNECTION feature.
@@ -168,7 +172,10 @@ pub mod v1alpha1 {
         /// same value as `requestRollout`.
         #[serde(default)]
         pub force_rollout: Uuid,
+        /// {{<warning>}}
         /// Deprecated and ignored. Use `rolloutStrategy` instead.
+        /// {{</warning>}}
+        #[kube(deprecated)]
         #[serde(default)]
         pub in_place_rollout: bool,
         /// Rollout strategy to use when upgrading this Materialize instance.