Merge pull request #28291 from lbarbeevargas/OCPCLOUD-980-gcp-disk-encryption-sets

Machine API - Support for Google Cloud Customer Managed Encryption Keys

Author: lbarbeevargas

machine_management/creating_machinesets/creating-machineset-gcp.adoc

@@ -16,3 +16,5 @@ include::modules/machineset-creating.adoc[leveloffset=+1]
 include::modules/machineset-non-guaranteed-instance.adoc[leveloffset=+1]
 
 include::modules/machineset-creating-non-guaranteed-instances.adoc[leveloffset=+1]
+
+include::modules/machineset-enabling-customer-managed-encryption.adoc[leveloffset=+1]

modules/machineset-enabling-customer-managed-encryption.adoc

@@ -0,0 +1,54 @@
+// Module included in the following assemblies:
+//
+// * machine_management/creating_machinesets/creating-machineset-gcp.adoc
+
+[id="machineset-enabling-customer-managed-encryption_{context}"]
+= Enabling customer-managed encryption keys for a machine set
+
+Google Cloud Platform (GCP) Compute Engine allows users to supply an encryption key to encrypt data on disks at rest. The key is used to encrypt the data encryption key, not to encrypt the customer's data. By default, Compute Engine encrypts this data by using Compute Engine keys.
+
+You can enable encryption with a customer-managed key by using the Machine API. You must first link:https://cloud.google.com/compute/docs/disks/customer-managed-encryption#before_you_begin[create a KMS key] and assign the correct permissions to a service account. The KMS key name, key ring name, and location are required to allow a service account to use your key.
+
+[NOTE]
+====
+If you do not want to use a dedicated service account for the KMS encryption, the Compute Engine default service account is used instead. You must grant the default service account permission to access the keys if you do not use a dedicated service account. The Compute Engine default service account name follows the `service-<project_number>@compute-system.iam.gserviceaccount.com` pattern.
+====
+
+.Procedure
+
+. Run the following command with your KMS key name, key ring name, and location to allow a specific service account to use your KMS key and to grant the service account the correct IAM role:
++
+[source,terminal]
+----
+gcloud kms keys add-iam-policy-binding <key_name> \
+  --keyring <key_ring_name> \
+  --location <key_ring_location> \
+  --member "serviceAccount:service-<project_number>@compute-system.iam.gserviceaccount.com” \
+  --role roles/cloudkms.cryptoKeyEncrypterDecrypter
+----
+
+. Configure the encryption key under the `providerSpec` field in your machine set YAML file. For example:
++
+[source,yaml]
+----
+providerSpec:
+  value:
+    …
+    disks:
+    - type: …
+      …
+      encryptionKey:
+        kmsKey:
+          name: machine-encryption-key <1>
+          keyRing: openshift-encrpytion-ring <2>
+          location: global <3>
+          projectID: openshift-gcp-project <4>
+        kmsKeyServiceAccount: openshift-service-account@openshift-gcp-project.iam.gserviceaccount.com <5>
+----
+<1> The name of the customer-managed encryption key that is used for the disk encryption.
+<2> The name of the KMS key ring that the KMS key belongs to.
+<3> The GCP location in which the KMS key ring exists.
+<4> Optional: The ID of the project in which the KMS key ring exists. If a project ID is not set, the machine set `projectID` in which the machine set was created is used. 
+<5> Optional: The service account that is used for the encryption request for the given KMS key. If a service account is not set, the Compute Engine default service account is used.
++
+After a new machine is created by using the updated `providerSpec` object configuration, the disk encryption key is encrypted with the KMS key.