Make v1 CRD and conversion webhook optional

Author: alex-hunt-materialize

doc/user/content/self-managed-deployments/installation/install-on-local-kind.md

@@ -107,10 +107,13 @@ Starting in v26.0, Self-Managed Materialize requires a license key.
    kubectl get nodes --show-labels
    ```
 
-1. Install cert-manager
+1. Recommended: Install cert-manager
 
    Cert-manager is used for generating TLS certificates needed by the materialize operator
-   for CRD conversion webhooks.
+   for CRD conversion webhooks. It is currently only required if you enable the v1
+   version of the Materialize CRD by setting `operator.args.installV1CRD=true`
+   when installing the operator, but certificates will become required in a
+   future version of Materialize.
 
    ```shell
    helm install cert-manager oci://quay.io/jetstack/charts/cert-manager \

misc/helm-charts/operator/README.md

@@ -143,12 +143,13 @@ The following table lists the configurable parameters of the Materialize operato
 | `operator.affinity` | Affinity to use for the operator pod | ``{}`` |
 | `operator.args.enableInternalStatementLogging` |  | ``true`` |
 | `operator.args.enableLicenseKeyChecks` |  | ``false`` |
+| `operator.args.installV1CRD` | Whether to install the v1 version of the Materialize CRD and the conversion webhook that converts between v1 and v1alpha1. When false, only the v1alpha1 CRD version is installed and no webhook serving certificate or service is created. | ``false`` |
 | `operator.args.startupLogFilter` | Log filtering settings for startup logs | ``"INFO,mz_orchestratord=TRACE"`` |
-| `operator.args.webhookCertReloadInterval` | How often orchestratord reloads its webhook TLS certificate from disk and, when the CA changes, refreshes the conversion webhook's CA bundle. Must be shorter than the certificate's lifetime. Accepts a humantime duration (e.g. "1h", "30m"). Leave null to use the binary default. | ``nil`` |
+| `operator.args.webhookCertReloadInterval` | How often orchestratord reloads its webhook TLS certificate from disk and, when the CA changes, refreshes the conversion webhook's CA bundle. Must be shorter than the certificate's lifetime. Accepts a humantime duration (e.g. "1h", "30m"). Leave null to use the binary default. Only used if `installV1CRD` is true. | ``nil`` |
 | `operator.certificate.caDuration` | Lifetime of the root CA that signs the webhook serving certificate, when `source` is "cert-manager". The serving certificate is signed by this CA, so the CA outlives individual serving-certificate rotations. | ``"87600h"`` |
 | `operator.certificate.caRenewBefore` | How long before the root CA expires to renew it. Must be less than `caDuration`. | ``"8760h"`` |
 | `operator.certificate.secretName` | Name of a secret in the operator's namespace containing ca.crt, tls.crt, and tls.key entries. Only used if `source` is "secret". | ``nil`` |
-| `operator.certificate.source` | Where to obtain the certificate for orchestratord. Valid values are 'cert-manager' and 'secret'. | ``"cert-manager"`` |
+| `operator.certificate.source` | Where to obtain the certificate for orchestratord. Valid values are 'cert-manager' and 'secret'. Only used if `operator.args.installV1CRD` is true. | ``"cert-manager"`` |
 | `operator.cloudProvider.providers.aws.accountID` | When using AWS, accountID is required | ``""`` |
 | `operator.cloudProvider.providers.aws.enabled` |  | ``false`` |
 | `operator.cloudProvider.providers.aws.iam.roles.connection` | ARN for CREATE CONNECTION feature | ``""`` |

misc/helm-charts/operator/templates/certificate.yaml

@@ -7,7 +7,7 @@
 # the Business Source License, use of this software will be governed
 # by the Apache License, Version 2.0.
 
-{{- if eq .Values.operator.certificate.source "cert-manager" -}}
+{{- if and .Values.operator.args.installV1CRD (eq .Values.operator.certificate.source "cert-manager") -}}
 # We provision the webhook serving certificate from a stable root CA rather
 # than as a bare self-signed certificate. The serving certificate rotates
 # frequently, but it is always signed by the same long-lived CA, so the

misc/helm-charts/operator/templates/deployment.yaml

@@ -66,9 +66,12 @@ spec:
         {{- if not .Values.operator.args.enableLicenseKeyChecks }}
         - "--disable-license-key-checks"
         {{- end }}
+        {{- if .Values.operator.args.installV1CRD }}
+        - "--install-v1-crd"
         {{- if .Values.operator.args.webhookCertReloadInterval }}
         - "--webhook-cert-reload-interval={{ .Values.operator.args.webhookCertReloadInterval }}"
         {{- end }}
+        {{- end }}
 
         {{/* AWS Configuration */}}
         {{- if eq .Values.operator.cloudProvider.type "aws" }}
@@ -245,15 +248,19 @@ spec:
         - >
           --additional-crd-columns={{ toJson .Values.operator.additionalMaterializeCRDColumns }}
         {{- end }}
+        {{- if .Values.operator.args.installV1CRD }}
         - "--webhook-service-name"
         - {{ include "materialize-operator.fullname" . }}
         - "--webhook-service-namespace"
         - {{ .Release.Namespace }}
+        {{- end }}
         ports:
         - containerPort: 3100
           name: metrics
+        {{- if .Values.operator.args.installV1CRD }}
         - containerPort: 8001
           name: webhook
+        {{- end }}
         resources:
           {{- toYaml .Values.operator.resources | nindent 10 }}
         securityContext:
@@ -265,6 +272,7 @@ spec:
           runAsNonRoot: true
           seccompProfile:
             type: RuntimeDefault
+        {{- if .Values.operator.args.installV1CRD }}
         livenessProbe:
           httpGet:
             path: /healthz
@@ -289,3 +297,4 @@ spec:
             defaultMode: 256
             optional: false
             secretName: {{ if eq .Values.operator.certificate.source "cert-manager" }}{{ include "materialize-operator.fullname" . }}-cert{{ else }}{{ .Values.operator.certificate.secretName }}{{ end }}
+        {{- end }}

misc/helm-charts/operator/templates/service.yaml

@@ -7,6 +7,7 @@
 # the Business Source License, use of this software will be governed
 # by the Apache License, Version 2.0.
 
+{{- if .Values.operator.args.installV1CRD -}}
 ---
 apiVersion: v1
 kind: Service
@@ -23,3 +24,4 @@ spec:
       protocol: TCP
       port: 8001
       targetPort: 8001
+{{- end -}}

misc/helm-charts/operator/values.yaml

@@ -24,11 +24,16 @@ operator:
     enableInternalStatementLogging: true
     # Newer versions ignore this setting and always enforce license key checks.
     enableLicenseKeyChecks: false
+    # -- Whether to install the v1 version of the Materialize CRD and the
+    # conversion webhook that converts between v1 and v1alpha1. When false,
+    # only the v1alpha1 CRD version is installed and no webhook serving
+    # certificate or service is created.
+    installV1CRD: false
     # -- (string) How often orchestratord reloads its webhook TLS certificate
     # from disk and, when the CA changes, refreshes the conversion webhook's CA
     # bundle. Must be shorter than the certificate's lifetime. Accepts a
     # humantime duration (e.g. "1h", "30m"). Leave null to use the binary
-    # default.
+    # default. Only used if `installV1CRD` is true.
     webhookCertReloadInterval: null
 
   # -- Additional columns to display when printing the Materialize CRD in table format.
@@ -40,8 +45,10 @@ operator:
     #  priority: 2
     #  type: "string"
 
+  # Webhook serving certificate configuration. Only used if
+  # `operator.args.installV1CRD` is true.
   certificate:
-    # -- (string) Where to obtain the certificate for orchestratord. Valid values are 'cert-manager' and 'secret'.
+    # -- (string) Where to obtain the certificate for orchestratord. Valid values are 'cert-manager' and 'secret'. Only used if `operator.args.installV1CRD` is true.
     source: cert-manager
     # -- (string) Name of a secret in the operator's namespace containing ca.crt, tls.crt, and tls.key entries. Only used if `source` is "secret".
     secretName: null

src/orchestratord/src/bin/orchestratord.rs

@@ -39,7 +39,7 @@ use mz_orchestrator_kubernetes::{KubernetesImagePullPolicy, util::create_client}
 use mz_orchestrator_tracing::{StaticTracingConfig, TracingCliArgs};
 use mz_orchestratord::{
     controller,
-    k8s::register_crds,
+    k8s::{ConversionWebhookConfig, register_crds},
     metrics::{self, Metrics},
     tls::DefaultCertificateSpecs,
     webhook,
@@ -66,10 +66,17 @@ pub struct Args {
     #[clap(long, default_value = "[::]:8001")]
     webhook_listen_address: SocketAddr,
 
-    #[clap(long)]
-    webhook_service_name: String,
-    #[clap(long)]
-    webhook_service_namespace: String,
+    /// Whether to install the v1 version of the Materialize CRD and the
+    /// conversion webhook between v1 and v1alpha1. When false, only the
+    /// v1alpha1 version is installed and the webhook server is not started.
+    #[clap(long)]
+    install_v1_crd: bool,
+    /// Required when --install-v1-crd is set.
+    #[clap(long, required_if_eq("install_v1_crd", "true"))]
+    webhook_service_name: Option<String>,
+    /// Required when --install-v1-crd is set.
+    #[clap(long, required_if_eq("install_v1_crd", "true"))]
+    webhook_service_namespace: Option<String>,
     #[clap(long, default_value = "8001")]
     webhook_service_port: u16,
     #[clap(long, default_value = "/etc/tls/ca.crt")]
@@ -293,7 +300,7 @@ async fn run(args: Args) -> Result<(), anyhow::Error> {
     let tls_cert = args.tls_cert;
     let tls_key = args.tls_key;
     let tls_ca = args.tls_ca;
-    let reload_config = {
+    let reload_config = if args.install_v1_crd {
         let config = OpenSSLConfig::from_pem_file(&tls_cert, &tls_key).unwrap();
         let reload_config = config.clone();
         let webhook_listen_address = args.webhook_listen_address;
@@ -307,21 +314,27 @@ async fn run(args: Args) -> Result<(), anyhow::Error> {
             }
         });
 
-        reload_config
+        Some(reload_config)
+    } else {
+        None
     };
 
     let (client, namespace) = create_client(args.kubernetes_context.clone()).await?;
     let additional_crd_columns = args.additional_crd_columns.unwrap_or_default();
-    let webhook_service_name = args.webhook_service_name;
-    let webhook_service_namespace = args.webhook_service_namespace;
-    let webhook_service_port = args.webhook_service_port;
+    let conversion_webhook = args.install_v1_crd.then(|| ConversionWebhookConfig {
+        service_name: args
+            .webhook_service_name
+            .expect("clap requires --webhook-service-name with --install-v1-crd"),
+        service_namespace: args
+            .webhook_service_namespace
+            .expect("clap requires --webhook-service-namespace with --install-v1-crd"),
+        service_port: args.webhook_service_port,
+        ca_cert_path: tls_ca.clone(),
+    });
     register_crds(
         client.clone(),
         additional_crd_columns.clone(),
-        webhook_service_name.clone(),
-        webhook_service_namespace.clone(),
-        webhook_service_port,
-        tls_ca.clone(),
+        conversion_webhook.clone(),
     )
     .await?;
 
@@ -336,9 +349,12 @@ async fn run(args: Args) -> Result<(), anyhow::Error> {
     // Kubernetes API server would reject every conversion request. Refreshing
     // the CA bundle when the CA changes keeps the webhook working across CA
     // rotations.
-    {
+    if let Some(reload_config) = reload_config {
+        let conversion_webhook = conversion_webhook
+            .expect("conversion webhook config is set whenever the webhook server is started");
         let reload_interval = args.webhook_cert_reload_interval;
         let client = client.clone();
+        let additional_crd_columns = additional_crd_columns.clone();
         mz_ore::task::spawn(|| "webhook certificate reload", async move {
             let mut last_ca = tokio::fs::read(&tls_ca).await.ok();
             let mut interval = tokio::time::interval(reload_interval);
@@ -367,10 +383,7 @@ async fn run(args: Args) -> Result<(), anyhow::Error> {
                 match register_crds(
                     client.clone(),
                     additional_crd_columns.clone(),
-                    webhook_service_name.clone(),
-                    webhook_service_namespace.clone(),
-                    webhook_service_port,
-                    tls_ca.clone(),
+                    Some(conversion_webhook.clone()),
                 )
                 .await
                 {
@@ -664,3 +677,42 @@ async fn run(args: Args) -> Result<(), anyhow::Error> {
 
     future::pending().await
 }
+
+#[cfg(test)]
+mod tests {
+    use clap::Parser;
+
+    use super::Args;
+
+    const REQUIRED_ARGS: &[&str] = &[
+        "orchestratord",
+        "--cloud-provider=local",
+        "--region=kind",
+        "--console-image-tag-default=latest",
+    ];
+
+    #[mz_ore::test]
+    fn webhook_service_args_required_with_install_v1_crd() {
+        let args = Args::try_parse_from(REQUIRED_ARGS).expect("parses without webhook args");
+        assert!(!args.install_v1_crd);
+
+        assert!(
+            Args::try_parse_from(REQUIRED_ARGS.iter().copied().chain(["--install-v1-crd"]))
+                .is_err(),
+            "--install-v1-crd should require the webhook service args"
+        );
+
+        let args = Args::try_parse_from(REQUIRED_ARGS.iter().copied().chain([
+            "--install-v1-crd",
+            "--webhook-service-name=orchestratord",
+            "--webhook-service-namespace=materialize",
+        ]))
+        .expect("parses with webhook args");
+        assert!(args.install_v1_crd);
+        assert_eq!(args.webhook_service_name.as_deref(), Some("orchestratord"));
+        assert_eq!(
+            args.webhook_service_namespace.as_deref(),
+            Some("materialize")
+        );
+    }
+}

src/orchestratord/src/k8s.rs

@@ -99,51 +99,71 @@ where
     }
 }
 
+/// Configuration for the conversion webhook that serves the v1 version of the
+/// Materialize CRD. When present, the v1 version is registered alongside
+/// v1alpha1 with webhook conversion between them; when absent, only v1alpha1
+/// is registered.
+#[derive(Debug, Clone)]
+pub struct ConversionWebhookConfig {
+    pub service_name: String,
+    pub service_namespace: String,
+    pub service_port: u16,
+    pub ca_cert_path: String,
+}
+
 pub async fn register_crds(
     client: Client,
     additional_crd_columns: Vec<CustomResourceColumnDefinition>,
-    webhook_service_name: String,
-    webhook_service_namespace: String,
-    webhook_service_port: u16,
-    ca_cert_path: String,
+    conversion_webhook: Option<ConversionWebhookConfig>,
 ) -> Result<(), anyhow::Error> {
-    let ca_bytes = tokio::fs::read(ca_cert_path).await?;
-    let mut mz_crd = crd::materialize::v1::Materialize::crd();
-    let default_columns = mz_crd.spec.versions[0]
+    let (mut mz_crds, mz_conversion) = match conversion_webhook {
+        Some(config) => {
+            let ca_bytes = tokio::fs::read(config.ca_cert_path).await?;
+            let conversion = CustomResourceConversion {
+                strategy: "Webhook".to_owned(),
+                webhook: Some(WebhookConversion {
+                    client_config: Some(WebhookClientConfig {
+                        ca_bundle: Some(ByteString(ca_bytes)),
+                        service: Some(ServiceReference {
+                            name: config.service_name,
+                            namespace: config.service_namespace,
+                            path: Some("/convert".to_owned()),
+                            port: Some(config.service_port.into()),
+                        }),
+                        url: None,
+                    }),
+                    conversion_review_versions: vec!["v1".to_owned()],
+                }),
+            };
+            (
+                vec![
+                    crd::materialize::v1::Materialize::crd(),
+                    crd::materialize::v1alpha1::Materialize::crd(),
+                ],
+                Some(conversion),
+            )
+        }
+        None => (vec![crd::materialize::v1alpha1::Materialize::crd()], None),
+    };
+    let default_columns = mz_crds[0].spec.versions[0]
         .additional_printer_columns
         .take()
         .expect("should contain ImageRef and UpToDate columns");
-    mz_crd.spec.versions[0].additional_printer_columns = Some(
+    mz_crds[0].spec.versions[0].additional_printer_columns = Some(
         additional_crd_columns
             .into_iter()
             .chain(default_columns)
             .collect(),
     );
-    let mz_conversion = CustomResourceConversion {
-        strategy: "Webhook".to_owned(),
-        webhook: Some(WebhookConversion {
-            client_config: Some(WebhookClientConfig {
-                ca_bundle: Some(ByteString(ca_bytes)),
-                service: Some(ServiceReference {
-                    name: webhook_service_name,
-                    namespace: webhook_service_namespace,
-                    path: Some("/convert".to_owned()),
-                    port: Some(webhook_service_port.into()),
-                }),
-                url: None,
-            }),
-            conversion_review_versions: vec!["v1".to_owned()],
-        }),
-    };
     tokio::time::timeout(
         Duration::from_secs(120),
         register_versioned_crds(
             client.clone(),
             vec![
                 VersionedCrd {
-                    crds: vec![mz_crd, crd::materialize::v1alpha1::Materialize::crd()],
+                    crds: mz_crds,
                     stored_version: String::from("v1alpha1"),
-                    conversion: Some(mz_conversion),
+                    conversion: mz_conversion,
                 },
                 VersionedCrd {
                     crds: vec![crd::balancer::v1alpha1::Balancer::crd()],