Merge pull request #149 from zilliztech/add-gcp-byoc-i-gcs-cmek

Add GCP BYOC-I GCS CMEK support

Author: wenhuiZilliz

examples/gcp-project-byoc-I/README.md

@@ -47,6 +47,30 @@ The example grants the storage service account to the fixed BYOC-I Kubernetes se
 
 The booter VM always uses a dedicated booter service account. The Zilliz BYOC organization service account is not granted permission to impersonate the maintenance service account. The in-cluster `infra/infra-agent-sa` Kubernetes service account uses GKE Workload Identity to access the maintenance service account instead.
 
+### GCS Bucket CMEK
+
+The GCS bucket uses Google-managed encryption by default. To use a customer-managed Cloud KMS key for new bucket objects, enable CMEK:
+
+```hcl
+enable_gcs_kms = true
+```
+
+When `gcs_kms_key_name` is empty, Terraform creates a Cloud KMS key ring and crypto key in the BYOC-I region and uses that key for the bucket. The generated KMS resource names are derived from the bucket name.
+
+To use an existing Cloud KMS key instead, pass the full key resource name:
+
+```hcl
+gcs_kms_key_name = "projects/<gcp-project-id>/locations/<region>/keyRings/<key-ring>/cryptoKeys/<key>"
+```
+
+Terraform-created KMS keys are automatically granted to the bucket project's Cloud Storage service agent. When using an existing key, `grant_gcs_kms_key_iam = true` default grants the same `roles/cloudkms.cryptoKeyEncrypterDecrypter` permission on that key. The Terraform runner must be allowed to manage IAM on the KMS key. If the permission is already granted outside Terraform for an existing key, set:
+
+```hcl
+grant_gcs_kms_key_iam = false
+```
+
+The KMS key location must be compatible with the bucket location. Changing the bucket default KMS key affects new objects written after the change; existing objects are not automatically re-encrypted.
+
 The booter image is not required in `terraform.tfvars`. Production defaults to `gcr.io/zilliz-byoc-prod/gcp-byoc-i-booter:latest`; UAT defaults to `gcr.io/zilliz-byoc-uat/gcp-byoc-i-booter:latest`. For development testing only, override `booter_image` locally.
 
 For booter troubleshooting, set `booter_print_serial_logs_on_apply = true` to print the booter VM serial console logs during `terraform apply`. This requires `gcloud` to be installed and authenticated on the Terraform runner.

examples/gcp-project-byoc-I/main.tf

@@ -22,10 +22,14 @@ module "vpc" {
 module "gcs" {
   source = "../../modules/gcp_byoc_i/gcs"
 
-  bucket_name   = local.bucket_name
-  gcp_region    = local.gcp_region
-  force_destroy = var.bucket_force_destroy
-  labels        = local.common_labels
+  bucket_name           = local.bucket_name
+  gcp_project_id        = var.gcp_project_id
+  gcp_region            = local.gcp_region
+  force_destroy         = var.bucket_force_destroy
+  labels                = local.common_labels
+  enable_gcs_kms        = var.enable_gcs_kms
+  gcs_kms_key_name      = var.gcs_kms_key_name
+  grant_gcs_kms_key_iam = var.grant_gcs_kms_key_iam
 
   depends_on = [google_project_service.required]
 }

examples/gcp-project-byoc-I/outputs.tf

@@ -14,6 +14,10 @@ output "gcs_bucket_id" {
   value = module.gcs.bucket_id
 }
 
+output "gcs_kms_key_name" {
+  value = module.gcs.kms_key_name
+}
+
 output "management_sa" {
   value = module.iam.management_sa_email
 }

examples/gcp-project-byoc-I/services.tf

@@ -1,13 +1,13 @@
 locals {
-  required_project_services = toset([
+  required_project_services = toset(concat([
     "cloudresourcemanager.googleapis.com",
     "artifactregistry.googleapis.com",
     "compute.googleapis.com",
     "container.googleapis.com",
     "dns.googleapis.com",
     "iam.googleapis.com",
     "storage.googleapis.com",
-  ])
+  ], var.enable_gcs_kms ? ["cloudkms.googleapis.com"] : []))
 }
 
 resource "google_project_service" "required" {

examples/gcp-project-byoc-I/terraform.sample.tfvars

@@ -1,6 +1,6 @@
-project_id                        = "proj-xxxxxxxx"
-dataplane_id                      = "zilliz-byoc-gcp-us-west1-xxxxxxxx"
-gcp_project_id                    = "customer-gcp-project"
+project_id     = "proj-xxxxxxxx"
+dataplane_id   = "zilliz-byoc-gcp-us-west1-xxxxxxxx"
+gcp_project_id = "customer-gcp-project"
 
 # Optional overrides.
 # vpc_cidr = "10.0.0.0/16"
@@ -26,6 +26,12 @@ gcp_project_id                    = "customer-gcp-project"
 # customer_gke_cluster_name = "zilliz-byoc-gke"
 # customer_bucket_name = "zilliz-byoc-gcp-bucket"
 # bucket_force_destroy = true
+# Enable GCS bucket default encryption with a customer-managed Cloud KMS key. When gcs_kms_key_name is empty, Terraform creates a key ring and crypto key.
+# enable_gcs_kms = true
+# Optional existing key. Leave empty to let Terraform create one.
+# gcs_kms_key_name = "projects/customer-gcp-project/locations/us-west1/keyRings/example-key-ring/cryptoKeys/example-key"
+# For existing keys only, set to false if the Cloud Storage service agent has already been granted KMS encrypter/decrypter permission.
+# grant_gcs_kms_key_iam = true
 # enable_resource_manager_tags = true
 # Leave tag IDs empty to let Terraform create a per-dataplane tag.
 # vendor_tag_key_id = "tagKeys/1234567890"

examples/gcp-project-byoc-I/variables.tf

@@ -235,6 +235,24 @@ variable "bucket_force_destroy" {
   default     = false
 }
 
+variable "enable_gcs_kms" {
+  description = "Enable Cloud KMS customer-managed encryption key for the GCS bucket."
+  type        = bool
+  default     = false
+}
+
+variable "gcs_kms_key_name" {
+  description = "Existing Cloud KMS key resource name used as the default GCS bucket encryption key. Leave empty to let Terraform create one when enable_gcs_kms is true."
+  type        = string
+  default     = ""
+}
+
+variable "grant_gcs_kms_key_iam" {
+  description = "Whether Terraform should grant the Cloud Storage service agent roles/cloudkms.cryptoKeyEncrypterDecrypter on an existing gcs_kms_key_name. Terraform-created keys are always granted."
+  type        = bool
+  default     = true
+}
+
 variable "labels" {
   description = "Labels applied to supported GCP resources."
   type        = map(string)

modules/gcp_byoc_i/gcs/main.tf

@@ -1,3 +1,43 @@
+locals {
+  create_gcs_kms_key         = var.enable_gcs_kms && var.gcs_kms_key_name == ""
+  grant_gcs_kms_key_iam      = var.enable_gcs_kms && (local.create_gcs_kms_key || var.grant_gcs_kms_key_iam)
+  auto_gcs_kms_name_prefix   = trimsuffix(substr(replace(replace(lower(var.bucket_name), ".", "-"), "_", "-"), 0, 50), "-")
+  gcs_kms_key_ring_name      = "${local.auto_gcs_kms_name_prefix}-kr"
+  gcs_kms_crypto_key_name    = "${local.auto_gcs_kms_name_prefix}-key"
+  effective_gcs_kms_key_name = var.enable_gcs_kms ? (var.gcs_kms_key_name != "" ? var.gcs_kms_key_name : google_kms_crypto_key.gcs[0].id) : ""
+}
+
+data "google_project" "this" {
+  count = local.grant_gcs_kms_key_iam ? 1 : 0
+
+  project_id = var.gcp_project_id
+}
+
+resource "google_kms_key_ring" "gcs" {
+  count = local.create_gcs_kms_key ? 1 : 0
+
+  project  = var.gcp_project_id
+  name     = local.gcs_kms_key_ring_name
+  location = var.gcp_region
+}
+
+resource "google_kms_crypto_key" "gcs" {
+  count = local.create_gcs_kms_key ? 1 : 0
+
+  name     = local.gcs_kms_crypto_key_name
+  key_ring = google_kms_key_ring.gcs[0].id
+}
+
+resource "google_kms_crypto_key_iam_member" "gcs_cmek" {
+  count = local.grant_gcs_kms_key_iam ? 1 : 0
+
+  crypto_key_id = local.effective_gcs_kms_key_name
+  role          = "roles/cloudkms.cryptoKeyEncrypterDecrypter"
+  member        = "serviceAccount:service-${data.google_project.this[0].number}@gs-project-accounts.iam.gserviceaccount.com"
+
+  depends_on = [google_kms_crypto_key.gcs]
+}
+
 resource "google_storage_bucket" "this" {
   name                        = var.bucket_name
   location                    = var.gcp_region
@@ -12,4 +52,16 @@ resource "google_storage_bucket" "this" {
     },
     var.labels,
   )
+
+  dynamic "encryption" {
+    for_each = var.enable_gcs_kms ? [1] : []
+
+    content {
+      default_kms_key_name = local.effective_gcs_kms_key_name
+    }
+  }
+
+  depends_on = [
+    google_kms_crypto_key_iam_member.gcs_cmek,
+  ]
 }

modules/gcp_byoc_i/gcs/outputs.tf

@@ -5,3 +5,7 @@ output "bucket_id" {
 output "bucket_url" {
   value = google_storage_bucket.this.url
 }
+
+output "kms_key_name" {
+  value = local.effective_gcs_kms_key_name
+}

modules/gcp_byoc_i/gcs/variables.tf

@@ -8,6 +8,12 @@ variable "gcp_region" {
   type        = string
 }
 
+variable "gcp_project_id" {
+  description = "Customer GCP project ID."
+  type        = string
+  default     = ""
+}
+
 variable "force_destroy" {
   description = "Whether to force destroy non-empty buckets."
   type        = bool
@@ -19,3 +25,21 @@ variable "labels" {
   type        = map(string)
   default     = {}
 }
+
+variable "enable_gcs_kms" {
+  description = "Enable Cloud KMS customer-managed encryption key for the GCS bucket."
+  type        = bool
+  default     = false
+}
+
+variable "gcs_kms_key_name" {
+  description = "Existing Cloud KMS key resource name used as the default GCS bucket encryption key. Leave empty to let Terraform create one when enable_gcs_kms is true."
+  type        = string
+  default     = ""
+}
+
+variable "grant_gcs_kms_key_iam" {
+  description = "Whether Terraform should grant the Cloud Storage service agent roles/cloudkms.cryptoKeyEncrypterDecrypter on an existing gcs_kms_key_name. Terraform-created keys are always granted."
+  type        = bool
+  default     = true
+}