Support installing cert-manager and using a ClusterIssuer for TLS

Author: alex-hunt-materialize

docs/footer.md

@@ -17,6 +17,20 @@ By default, Network Load Balancers are created for each Materialize instance, wi
 
 The DNS name and ARN for the NLBs will be in the `terraform output` as `nlb_details`.
 
+#### TLS support
+
+For example purposes, optional TLS support is provided by using `cert-manager` and a self-signed `ClusterIssuer`.
+
+More advanced TLS support using user-provided CAs or per-Materialize `Issuer`s are out of scope of this Terraform module. Please refer to the [cert-manager documentation](https://cert-manager.io/docs/configuration/) for detailed guidance on more advanced usage.
+
+###### To enable installation of `cert-manager` and configuration of the self-signed `ClusterIssuer`
+* Set `install_cert_manager` to `true`.
+* Run `terraform apply`.
+* Set `use_self_signed_cluster_issuer` to `true`.
+* Run `terraform apply`.
+
+Due to limitations in Terraform, it cannot plan Kubernetes resources using CRDs that do not exist yet. We need to first install `cert-manager` in the first `terraform apply`, before defining any `ClusterIssuer` or `Certificate` resources which get created in the second `terraform apply`.
+
 ## Upgrade Notes
 
 #### v0.3.0

docs/operator-tls-setup.md

@@ -79,6 +79,10 @@ module "materialize_infrastructure" {
   enable_monitoring      = true
   metrics_retention_days = 3
 
+  # Certificates
+  install_cert_manager           = var.install_cert_manager
+  use_self_signed_cluster_issuer = var.use_self_signed_cluster_issuer
+
   # Enable and configure Materialize operator
   install_materialize_operator = true
   operator_version             = var.operator_version
@@ -155,6 +159,18 @@ variable "helm_values" {
   default     = {}
 }
 
+variable "install_cert_manager" {
+  description = "Whether to install cert-manager."
+  type        = bool
+  default     = false
+}
+
+variable "use_self_signed_cluster_issuer" {
+  description = "Whether to install and use a self-signed ClusterIssuer for TLS. Due to limitations in Terraform, this may not be enabled before the cert-manager CRDs are installed."
+  type        = bool
+  default     = false
+}
+
 # Outputs
 output "vpc_id" {
   description = "VPC ID"

examples/simple/main.tf

@@ -107,6 +107,24 @@ module "database" {
   ]
 }
 
+module "certificates" {
+  source = "./modules/certificates"
+
+  install_cert_manager           = var.install_cert_manager
+  use_self_signed_cluster_issuer = var.use_self_signed_cluster_issuer
+  cert_manager_namespace         = var.cert_manager_namespace
+  name_prefix                    = local.name_prefix
+
+  depends_on = [
+    module.eks,
+    # The AWS LBC installs webhooks, and all other K8S stuff can fail
+    # if they are deployed, but the AWS LBC pods aren't up yet.
+    # This doesn't actually need the LBC,
+    # but we want to avoid concurrently updating these.
+    module.aws_lbc,
+  ]
+}
+
 module "operator" {
   source = "github.com/MaterializeInc/terraform-helm-materialize?ref=v0.1.8"
 
@@ -119,6 +137,12 @@ module "operator" {
     module.database,
     module.storage,
     module.networking,
+    module.certificates,
+    # The AWS LBC installs webhooks, and all other K8S stuff can fail
+    # if they are deployed, but the AWS LBC pods aren't up yet.
+    # This doesn't actually need the LBC,
+    # but we want to avoid concurrently updating these.
+    module.aws_lbc,
   ]
 
   namespace          = var.namespace
@@ -198,6 +222,34 @@ locals {
         parameters  = local.disk_config.storage_class_parameters
       }
     } : {}
+    tls = var.use_self_signed_cluster_issuer ? {
+      defaultCertificateSpecs = {
+        balancerdExternal = {
+          dnsNames = [
+            "balancerd",
+          ]
+          issuerRef = {
+            name = module.certificates.cluster_issuer_name
+            kind = "ClusterIssuer"
+          }
+        }
+        consoleExternal = {
+          dnsNames = [
+            "console",
+          ]
+          issuerRef = {
+            name = module.certificates.cluster_issuer_name
+            kind = "ClusterIssuer"
+          }
+        }
+        internal = {
+          issuerRef = {
+            name = module.certificates.cluster_issuer_name
+            kind = "ClusterIssuer"
+          }
+        }
+      }
+    } : {}
   }
 
   merged_helm_values = merge(local.default_helm_values, var.helm_values)

main.tf

@@ -0,0 +1,104 @@
+resource "kubernetes_namespace" "cert_manager" {
+  count = var.install_cert_manager ? 1 : 0
+
+  metadata {
+    name = var.cert_manager_namespace
+  }
+}
+
+resource "helm_release" "cert_manager" {
+  count = var.install_cert_manager ? 1 : 0
+
+  # cert-manager is a singleton resource for the cluster,
+  # so not using name prefixes here.
+  name       = "cert-manager"
+  namespace  = kubernetes_namespace.cert_manager[0].metadata[0].name
+  repository = "https://charts.jetstack.io"
+  chart      = "cert-manager"
+  version    = "v1.17.1"
+
+  set {
+    name  = "crds.enabled"
+    value = "true"
+  }
+
+  depends_on = [
+    kubernetes_namespace.cert_manager,
+  ]
+}
+
+resource "kubernetes_manifest" "self_signed_cluster_issuer" {
+  # only create these after cert manager is installed
+  count = var.use_self_signed_cluster_issuer ? 1 : 0
+
+  manifest = {
+    "apiVersion" = "cert-manager.io/v1"
+    "kind"       = "ClusterIssuer"
+    "metadata" = {
+      "name" = "${var.name_prefix}-self-signed"
+    }
+    "spec" = {
+      "selfSigned" = {}
+    }
+  }
+
+  depends_on = [
+    helm_release.cert_manager,
+  ]
+}
+
+resource "kubernetes_manifest" "self_signed_root_ca_certificate" {
+  count = var.use_self_signed_cluster_issuer ? 1 : 0
+
+  manifest = {
+    "apiVersion" = "cert-manager.io/v1"
+    "kind"       = "Certificate"
+    "metadata" = {
+      "name"      = "${var.name_prefix}-self-signed-ca"
+      "namespace" = var.cert_manager_namespace
+    }
+    "spec" = {
+      "isCA"       = true
+      "commonName" = "${var.name_prefix}-self-signed-ca"
+      "secretName" = "${var.name_prefix}-root-ca"
+      "privateKey" = {
+        "algorithm"      = "RSA"
+        "encoding"       = "PKCS8"
+        "size"           = 4096
+        "rotationPolicy" = "Always"
+      }
+      "issuerRef" = {
+        "name"  = "${var.name_prefix}-self-signed"
+        "kind"  = "ClusterIssuer"
+        "group" = "cert-manager.io"
+      }
+    }
+  }
+
+  depends_on = [
+    helm_release.cert_manager,
+    kubernetes_manifest.self_signed_cluster_issuer,
+  ]
+}
+
+resource "kubernetes_manifest" "root_ca_cluster_issuer" {
+  count = var.use_self_signed_cluster_issuer ? 1 : 0
+
+  manifest = {
+    "apiVersion" = "cert-manager.io/v1"
+    "kind"       = "ClusterIssuer"
+    "metadata" = {
+      "name" = "${var.name_prefix}-root-ca"
+    }
+    "spec" = {
+      "ca" = {
+        "secretName" = "${var.name_prefix}-root-ca"
+      }
+    }
+  }
+
+  depends_on = [
+    helm_release.cert_manager,
+    kubernetes_manifest.self_signed_root_ca_certificate,
+  ]
+}