Merge pull request #69250 from mjpytlak/osdocs-8828

OSDOCS#8828: User-managed encryption (BYOK) for IBM Cloud

Author: mjpytlak

_topic_maps/_topic_map.yml

@@ -287,6 +287,8 @@ Topics:
     File: installing-ibm-cloud-account
   - Name: Configuring IAM for IBM Cloud
     File: configuring-iam-ibm-cloud
+  - Name: User-managed encryption
+    File: user-managed-encryption-ibm-cloud
   - Name: Installing a cluster on IBM Cloud with customizations
     File: installing-ibm-cloud-customizations
   - Name: Installing a cluster on IBM Cloud with network customizations

installing/installing_ibm_cloud_public/user-managed-encryption-ibm-cloud.adoc

@@ -0,0 +1,42 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="user-managed-encryption-ibm-cloud"]
+= User-managed encryption for {ibm-cloud-title}
+include::_attributes/common-attributes.adoc[]
+:context: user-managed-encryption-ibm-cloud
+
+toc::[]
+
+By default, provider-managed encryption is used to secure the following when you deploy an {product-title} cluster:
+
+* The root (boot) volume of control plane and compute machines
+* Persistent volumes (data volumes) that are provisioned after the cluster is deployed
+
+You can override the default behavior by specifying an {ibm-name} Key Protect for {ibm-cloud-name} (Key Protect) or {ibm-name} Hyper Protect Crypto Services (Hyper Protect Crypto Services) root key as part of the installation process.
+
+When you bring our own root key, you modify the installation configuration file (`install-config.yaml`) to specify the Cloud Resource Name (CRN) of the root key by using the `encryptionKey` parameter.
+
+You can specify that:
+
+* The same root key be used be used for all cluster machines. You do so by specifying the key as part of the cluster's default machine configuration.
++
+When specified as part of the default machine configuration, all managed storage classes are updated with this key. As such, data volumes that are provisioned after the installation are also encrypted using this key.
+
+* Separate root keys be used for the control plane and compute machine pools.
+
+For more information about the `encryptionKey` parameter, see xref:../../installing/installing_ibm_cloud_public/installation-config-parameters-ibm-cloud-vpc.adoc#installation-configuration-parameters-additional-ibm-cloud_installation-config-parameters-ibm-cloud-vpc[Additional IBM Cloud configuration parameters].
+
+[NOTE]
+====
+Be sure you have integrated Key Protect or Hyper Protect Crypto Services with your IBM Cloud Block Storage service. For more information, see the Key Protect link:https://cloud.ibm.com/docs/key-protect?topic=key-protect-integrate-services#grant-access[documentation] or Hyper Protect Crypto Services link:https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-integrate-services[documentation].
+====
+
+
+[id="user-managed-encryption-ibm-cloud-next-steps"]
+== Next steps
+
+Install an {product-title} cluster:
+
+* xref:../../installing/installing_ibm_cloud_public/installing-ibm-cloud-customizations.adoc#installing-ibm-cloud-customizations[Installing a cluster on {ibm-cloud-title} with customizations]
+* xref:../../installing/installing_ibm_cloud_public/installing-ibm-cloud-network-customizations.adoc#installing-ibm-cloud-network-customizations[Installing a cluster on {ibm-cloud-title} with network customizations]
+* xref:../../installing/installing_ibm_cloud_public/installing-ibm-cloud-vpc.adoc#installing-ibm-cloud-vpc[Installing a cluster on {ibm-cloud-title} into an existing VPC]
+* xref:../../installing/installing_ibm_cloud_public/installing-ibm-cloud-private.adoc#installing-ibm-cloud-private[Installing a private cluster on {ibm-cloud-title}]

modules/installation-configuration-parameters.adoc

@@ -2273,6 +2273,38 @@ Additional {ibm-cloud-name} configuration parameters are described in the follow
 |====
 |Parameter|Description|Values
 
+|controlPlane:
+  platform:
+    ibmcloud:
+      bootVolume:
+        encryptionKey:
+|An {ibm-name} Key Protect for {ibm-cloud-name} (Key Protect) or {ibm-name} Hyper Protect Crypto Services (Hyper Protect Crypto Services) root key that should be used to encrypt the root (boot) volume of only control plane machines.
+d|The Cloud Resource Name (CRN) of the root key.
+
+The CRN must be enclosed in quotes ("").
+
+|compute:
+  platform:
+    ibmcloud:
+      bootVolume:
+        encryptionKey:
+|A Key Protect or Hyper Protect Crypto Services root key that should be used to encrypt the root (boot) volume of only compute machines.
+d|The CRN of the root key.
+
+The CRN must be enclosed in quotes ("").
+
+|platform:
+  ibmcloud:
+    defaultMachinePlatform:
+      bootvolume:
+        encryptionKey:
+d|A Key Protect or Hyper Protect Crypto Services root key that should be used to encrypt the root (boot) volume of all of the cluster's machines.
+
+When specified as part of the default machine configuration, all managed storage classes are updated with this key. As such, data volumes that are provisioned after the installation are also encrypted using this key.
+d|The CRN of the root key.
+
+The CRN must be enclosed in quotes ("").
+
 |platform:
   ibmcloud:
     resourceGroupName: