Merge pull request #27 from MaterializeInc/certificates

Certificates

Author: alex-hunt-materialize

README.md

@@ -85,9 +85,10 @@ No providers.
 | Name | Source | Version |
 |------|--------|---------|
 | <a name="module_aks"></a> [aks](#module\_aks) | ./modules/aks | n/a |
+| <a name="module_certificates"></a> [certificates](#module\_certificates) | ./modules/certificates | n/a |
 | <a name="module_database"></a> [database](#module\_database) | ./modules/database | n/a |
 | <a name="module_networking"></a> [networking](#module\_networking) | ./modules/networking | n/a |
-| <a name="module_operator"></a> [operator](#module\_operator) | github.com/MaterializeInc/terraform-helm-materialize | v0.1.8 |
+| <a name="module_operator"></a> [operator](#module\_operator) | github.com/MaterializeInc/terraform-helm-materialize | v0.1.9 |
 | <a name="module_storage"></a> [storage](#module\_storage) | ./modules/storage | n/a |
 
 ## Resources
@@ -99,21 +100,26 @@ No resources.
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
 | <a name="input_aks_config"></a> [aks\_config](#input\_aks\_config) | AKS cluster configuration | <pre>object({<br/>    vm_size      = string<br/>    disk_size_gb = number<br/>    min_nodes    = number<br/>    max_nodes    = number<br/>  })</pre> | <pre>{<br/>  "disk_size_gb": 100,<br/>  "max_nodes": 5,<br/>  "min_nodes": 1,<br/>  "vm_size": "Standard_E8ps_v6"<br/>}</pre> | no |
+| <a name="input_cert_manager_chart_version"></a> [cert\_manager\_chart\_version](#input\_cert\_manager\_chart\_version) | Version of the cert-manager helm chart to install. | `string` | `"v1.17.1"` | no |
+| <a name="input_cert_manager_install_timeout"></a> [cert\_manager\_install\_timeout](#input\_cert\_manager\_install\_timeout) | Timeout for installing the cert-manager helm chart, in seconds. | `number` | `300` | no |
+| <a name="input_cert_manager_namespace"></a> [cert\_manager\_namespace](#input\_cert\_manager\_namespace) | The name of the namespace in which cert-manager is or will be installed. | `string` | `"cert-manager"` | no |
 | <a name="input_database_config"></a> [database\_config](#input\_database\_config) | Azure Database for PostgreSQL configuration | <pre>object({<br/>    sku_name         = optional(string, "GP_Standard_D2s_v3")<br/>    postgres_version = optional(string, "15")<br/>    password         = string<br/>    username         = optional(string, "materialize")<br/>    db_name          = optional(string, "materialize")<br/>  })</pre> | n/a | yes |
 | <a name="input_helm_chart"></a> [helm\_chart](#input\_helm\_chart) | Chart name from repository or local path to chart. For local charts, set the path to the chart directory. | `string` | `"materialize-operator"` | no |
 | <a name="input_helm_values"></a> [helm\_values](#input\_helm\_values) | Additional Helm values to merge with defaults | `any` | `{}` | no |
+| <a name="input_install_cert_manager"></a> [install\_cert\_manager](#input\_install\_cert\_manager) | Whether to install cert-manager. | `bool` | `false` | no |
 | <a name="input_install_materialize_operator"></a> [install\_materialize\_operator](#input\_install\_materialize\_operator) | Whether to install the Materialize operator | `bool` | `true` | no |
 | <a name="input_location"></a> [location](#input\_location) | The location where resources will be created | `string` | `"eastus2"` | no |
 | <a name="input_materialize_instances"></a> [materialize\_instances](#input\_materialize\_instances) | Configuration for Materialize instances | <pre>list(object({<br/>    name                    = string<br/>    namespace               = optional(string)<br/>    database_name           = string<br/>    environmentd_version    = optional(string, "v0.130.4")<br/>    cpu_request             = optional(string, "1")<br/>    memory_request          = optional(string, "1Gi")<br/>    memory_limit            = optional(string, "1Gi")<br/>    create_database         = optional(bool, true)<br/>    in_place_rollout        = optional(bool, false)<br/>    request_rollout         = optional(string)<br/>    force_rollout           = optional(string)<br/>    balancer_memory_request = optional(string, "256Mi")<br/>    balancer_memory_limit   = optional(string, "256Mi")<br/>    balancer_cpu_request    = optional(string, "100m")<br/>  }))</pre> | `[]` | no |
 | <a name="input_namespace"></a> [namespace](#input\_namespace) | Namespace for all resources, usually the organization or project name | `string` | `"materialize"` | no |
 | <a name="input_network_config"></a> [network\_config](#input\_network\_config) | Network configuration for the AKS cluster | <pre>object({<br/>    vnet_address_space   = string<br/>    subnet_cidr          = string<br/>    postgres_subnet_cidr = string<br/>    service_cidr         = string<br/>    docker_bridge_cidr   = string<br/>  })</pre> | n/a | yes |
 | <a name="input_operator_namespace"></a> [operator\_namespace](#input\_operator\_namespace) | Namespace for the Materialize operator | `string` | `"materialize"` | no |
 | <a name="input_operator_version"></a> [operator\_version](#input\_operator\_version) | Version of the Materialize operator to install | `string` | `null` | no |
-| <a name="input_orchestratord_version"></a> [orchestratord\_version](#input\_orchestratord\_version) | Version of the Materialize orchestrator to install | `string` | `"v0.130.4"` | no |
+| <a name="input_orchestratord_version"></a> [orchestratord\_version](#input\_orchestratord\_version) | Version of the Materialize orchestrator to install | `string` | `null` | no |
 | <a name="input_prefix"></a> [prefix](#input\_prefix) | Prefix to be used for resource names | `string` | `"materialize"` | no |
 | <a name="input_resource_group_name"></a> [resource\_group\_name](#input\_resource\_group\_name) | The name of the resource group | `string` | n/a | yes |
 | <a name="input_tags"></a> [tags](#input\_tags) | Tags to apply to all resources | `map(string)` | `{}` | no |
 | <a name="input_use_local_chart"></a> [use\_local\_chart](#input\_use\_local\_chart) | Whether to use a local chart instead of one from a repository | `bool` | `false` | no |
+| <a name="input_use_self_signed_cluster_issuer"></a> [use\_self\_signed\_cluster\_issuer](#input\_use\_self\_signed\_cluster\_issuer) | 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. | `bool` | `false` | no |
 
 ## Outputs
 
@@ -138,4 +144,26 @@ az aks get-credentials --resource-group $(terraform output -raw resource_group_n
 ```
 
 This command retrieves the AKS cluster credentials and merges them into the `~/.kube/config` file. You can now interact with the AKS cluster using `kubectl`.
+
+## Connecting to Materialize instances
+
+Access to the database is through the balancerd pods on:
+* Port 6875 for SQL connections.
+* Port 6876 for HTTP(S) connections.
+
+Access to the web console is through the console pods on port 8080.
+
+#### 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 for 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`
+1. Set `install_cert_manager` to `true`.
+1. Run `terraform apply`.
+1. Set `use_self_signed_cluster_issuer` to `true`.
+1. 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`.
 <!-- END_TF_DOCS -->

docs/footer.md

@@ -7,3 +7,25 @@ az aks get-credentials --resource-group $(terraform output -raw resource_group_n
 ```
 
 This command retrieves the AKS cluster credentials and merges them into the `~/.kube/config` file. You can now interact with the AKS cluster using `kubectl`.
+
+## Connecting to Materialize instances
+
+Access to the database is through the balancerd pods on:
+* Port 6875 for SQL connections.
+* Port 6876 for HTTP(S) connections.
+
+Access to the web console is through the console pods on port 8080.
+
+#### 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 for 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`
+1. Set `install_cert_manager` to `true`.
+1. Run `terraform apply`.
+1. Set `use_self_signed_cluster_issuer` to `true`.
+1. 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`.

examples/simple/main.tf

@@ -81,6 +81,9 @@ module "materialize" {
   operator_version      = var.operator_version
   orchestratord_version = var.orchestratord_version
 
+  install_cert_manager           = var.install_cert_manager
+  use_self_signed_cluster_issuer = var.use_self_signed_cluster_issuer
+
   materialize_instances = var.materialize_instances
 
   database_config = {
@@ -130,7 +133,7 @@ variable "operator_version" {
 variable "orchestratord_version" {
   description = "Version of the Materialize orchestrator to install"
   type        = string
-  default     = "v0.130.4"
+  default     = null
 }
 
 variable "tags" {
@@ -162,6 +165,18 @@ variable "materialize_instances" {
   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
+}
+
 # Output the Materialize instance details
 output "aks_cluster" {
   description = "AKS cluster details"

main.tf

@@ -72,12 +72,27 @@ module "storage" {
   tags = local.common_labels
 }
 
+module "certificates" {
+  source = "./modules/certificates"
+
+  install_cert_manager           = var.install_cert_manager
+  cert_manager_install_timeout   = var.cert_manager_install_timeout
+  cert_manager_chart_version     = var.cert_manager_chart_version
+  use_self_signed_cluster_issuer = var.use_self_signed_cluster_issuer
+  cert_manager_namespace         = var.cert_manager_namespace
+  name_prefix                    = var.prefix
+
+  depends_on = [
+    module.aks,
+  ]
+}
+
 locals {
   default_helm_values = {
     operator = {
-      image = {
+      image = var.orchestratord_version == null ? {} : {
         tag = var.orchestratord_version
-      }
+      },
       cloudProvider = {
         type   = "azure"
         region = var.location
@@ -88,6 +103,34 @@ locals {
         enabled = true
       }
     }
+    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)
@@ -131,14 +174,15 @@ locals {
 }
 
 module "operator" {
-  source = "github.com/MaterializeInc/terraform-helm-materialize?ref=v0.1.8"
+  source = "github.com/MaterializeInc/terraform-helm-materialize?ref=v0.1.9"
 
   count = var.install_materialize_operator ? 1 : 0
 
   depends_on = [
     module.aks,
     module.database,
-    module.storage
+    module.storage,
+    module.certificates,
   ]
 
   namespace          = var.namespace

modules/certificates/main.tf

@@ -0,0 +1,105 @@
+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    = var.cert_manager_chart_version
+  timeout    = var.cert_manager_install_timeout
+
+  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,
+  ]
+}

modules/certificates/outputs.tf

@@ -0,0 +1,4 @@
+output "cluster_issuer_name" {
+  description = "Name of the ClusterIssuer"
+  value       = var.use_self_signed_cluster_issuer ? kubernetes_manifest.root_ca_cluster_issuer[0].object.metadata.name : null
+}

modules/certificates/variables.tf

@@ -0,0 +1,29 @@
+variable "install_cert_manager" {
+  description = "Whether to install cert-manager."
+  type        = bool
+}
+
+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
+}
+
+variable "cert_manager_namespace" {
+  description = "The name of the namespace in which cert-manager is or will be installed."
+  type        = string
+}
+
+variable "name_prefix" {
+  description = "The name prefix to use for Kubernetes resources. Does not apply to cert-manager itself, as that is a singleton per cluster."
+  type        = string
+}
+
+variable "cert_manager_install_timeout" {
+  description = "Timeout for installing the cert-manager helm chart, in seconds."
+  type        = number
+}
+
+variable "cert_manager_chart_version" {
+  description = "Version of the cert-manager helm chart to install."
+  type        = string
+}

modules/certificates/versions.tf

@@ -0,0 +1,26 @@
+terraform {
+  required_version = ">= 1.0"
+
+  required_providers {
+
+    azurerm = {
+      source  = "hashicorp/azurerm"
+      version = ">= 3.75.0"
+    }
+
+    azuread = {
+      source  = "hashicorp/azuread"
+      version = ">= 2.45.0"
+    }
+
+    kubernetes = {
+      source  = "hashicorp/kubernetes"
+      version = "~> 2.0"
+    }
+
+    helm = {
+      source  = "hashicorp/helm"
+      version = "~> 2.0"
+    }
+  }
+}