OSDOCS-2736 - Adding etcd encryption steps for OSD and ROSA

Author: pneedle-rh

modules/create-aws-cluster.adoc

@@ -5,7 +5,6 @@
 [id="create-aws-cluster_{context}"]
 = Creating a cluster on AWS
 
-
 You can create an {product-title} cluster on {AWS} using a standard cloud account owned by Red Hat or with your own cloud account using the Customer Cloud Subscription (CCS) model.
 
 Using the CCS model to deploy and manage {product-title} into your AWS account requires several prerequisites to be met.
@@ -64,7 +63,6 @@ Revoking these credentials in AWS will result in a loss of access to any cluster
 .... Host Prefix: /23
 
 ... Select your preferred cluster privacy. *Public* is selected by default.
-
 +
 [IMPORTANT]
 ====
@@ -73,6 +71,15 @@ CIDR configurations cannot be changed later. Confirm your selections with your n
 If the cluster privacy is set to *Private*, you will not be able to access your cluster until you configure private connections in your cloud provider.
 ====
 
+. Optional: Select *Enable etcd encryption* if you require etcd key value encryption. With this option, the etcd key values are encrypted, but not the keys. The option is in addition to the control plane storage encryption that encrypts the etcd volumes in {product-title} clusters by default.
++
+[IMPORTANT]
+====
+By enabling etcd encryption for the key values in etcd, you will incur a performance overhead of approximately 20%. The overhead is a result of introducing this second layer of encryption, in addition to the default control plane storage encryption that encrypts the etcd volumes. Red Hat recommends that you enable etcd encryption only if you specifically require it for your use case.
+====
+
+. Leave *Enable user workload monitoring* selected to monitor your own projects in isolation from Red Hat Site Reliability Engineer (SRE) platform metrics. The option is enabled by default.
+
 . Select your cluster update method.
 ** *Manual* is selected by default. With this option, you are responsible for updating your cluster. If your cluster version falls too far behind, it will be automatically updated.
 ** Select *Automatic* if you want your cluster to be automatically upgraded when new versions are available. If you opt for automatic upgrades, you must specify the preferred day of the week and the time (UTC) for the upgrade to start.

modules/create-gcp-cluster.adoc

@@ -5,7 +5,6 @@
 [id="create-gcp-cluster_{context}"]
 = Creating a cluster on GCP
 
-
 You can create an {product-title} cluster on {GCP} using a standard cloud account owned by Red Hat or with your own cloud account using the Customer Cloud Subscription (CCS) model.
 
 Using the CCS model to deploy and manage {product-title} into your GCP account requires several prerequisites to be met.
@@ -69,7 +68,6 @@ The project name must be 10 characters or less.
 .... Host Prefix: /23
 
 ... If you are creating a CCS {product-title} cluster, you can enable private clusters. This option is not available for standard clusters. Select your preferred cluster privacy. *Private* is selected by default.
-
 +
 [IMPORTANT]
 ====
@@ -78,7 +76,14 @@ CIDR configurations cannot be changed later. Confirm your selections with your n
 If the cluster privacy is set to *Private*, you will not be able to access your cluster until you configure private connections in your cloud provider.
 ====
 
+. Optional: Select *Enable etcd encryption* if you require etcd key value encryption. With this option, the etcd key values are encrypted, but not the keys. The option is in addition to the control plane storage encryption that encrypts the etcd volumes in {product-title} clusters by default.
++
+[IMPORTANT]
+====
+By enabling etcd encryption for the key values in etcd, you will incur a performance overhead of approximately 20%. The overhead is a result of introducing this second layer of encryption, in addition to the default control plane storage encryption that encrypts the etcd volumes. Red Hat recommends that you enable etcd encryption only if you specifically require it for your use case.
+====
 
+. Leave *Enable user workload monitoring* selected to monitor your own projects in isolation from Red Hat Site Reliability Engineer (SRE) platform metrics. The option is enabled by default.
 
 . Select your cluster update method.
 ** *Manual* is selected by default. With this option, you are responsible for updating your cluster. If your cluster version falls too far behind, it will be automatically updated.

modules/rosa-sdpolicy-security.adoc

@@ -1,7 +1,6 @@
-
 // Module included in the following assemblies:
 //
-// * assemblies/rosa-service-definition.adoc
+// * rosa_policy/rosa-service-definition.adoc
 
 [id="rosa-sdpolicy-security_{context}"]
 = Security
@@ -63,17 +62,17 @@ With {product-title}, AWS provides a standard DDoS protection on all load balanc
 
 In {product-title}, the control plane storage is encrypted at rest by default and this includes encryption of the etcd volumes. This storage-level encryption is provided through the storage layer of the cloud provider.
 
-You can also enable etcd encryption, which encrypts the key values in etcd state, but not the keys. If you enable etcd encryption, the following Kubernetes API server and OpenShift API server resources are encrypted:
+You can also enable etcd encryption, which encrypts the key values in etcd, but not the keys. If you enable etcd encryption, the following Kubernetes API server and OpenShift API server resources are encrypted:
 
 * Secrets
 * Config maps
 * Routes
 * OAuth access tokens
 * OAuth authorize tokens 
 
-The etcd encryption feature is not enabled by default and it can be enabled only at cluster installation time.
+The etcd encryption feature is not enabled by default and it can be enabled only at cluster installation time. Even with etcd encryption enabled, the etcd key values are accessible to anyone with access to the control plane nodes or `cluster-admin` privileges.
 
 [IMPORTANT]
 ====
-By enabling etcd encryption for the key values in etcd state, you might incur a performance overhead of approximately 20%. Red Hat only recommends that you enable etcd encryption in addition to the default storage-level encryption if you specifically require this for your use case.
+By enabling etcd encryption for the key values in etcd, you will incur a performance overhead of approximately 20%. The overhead is a result of introducing this second layer of encryption, in addition to the default control plane storage encryption that encrypts the etcd volumes. Red Hat recommends that you enable etcd encryption only if you specifically require it for your use case.
 ====

modules/rosa-sts-creating-a-cluster-with-customizations.adoc

@@ -99,6 +99,7 @@ You can reference the ARN of your KMS key when you create the cluster in the nex
 $ rosa create cluster --interactive --sts
 ----
 +
+--
 .Example output
 [source,terminal]
 ----
@@ -124,10 +125,11 @@ I: Using arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Support-Role for th
 ? Service CIDR: 172.30.0.0/16
 ? Pod CIDR: 10.128.0.0/14
 ? Host prefix: 23
+? Encrypt etcd data (optional): No <5>
 ? Disable Workload monitoring (optional): No
 I: Creating cluster '<cluster_name>'
 I: To create this cluster again in the future, you can run:
-   rosa create cluster --cluster-name <cluster_name> --role-arn arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Installer-Role --support-role-arn arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Support-Role --master-iam-role arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-ControlPlane-Role --worker-iam-role arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Worker-Role --operator-roles-prefix <cluster_name>-<random_string> --region us-east-1 --version 4.8.9 --compute-nodes 2 --machine-cidr 10.0.0.0/16 --service-cidr 172.30.0.0/16 --pod-cidr 10.128.0.0/14 --host-prefix 23 <5>
+   rosa create cluster --cluster-name <cluster_name> --role-arn arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Installer-Role --support-role-arn arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Support-Role --master-iam-role arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-ControlPlane-Role --worker-iam-role arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-Worker-Role --operator-roles-prefix <cluster_name>-<random_string> --region us-east-1 --version 4.8.9 --compute-nodes 2 --machine-cidr 10.0.0.0/16 --service-cidr 172.30.0.0/16 --pod-cidr 10.128.0.0/14 --host-prefix 23 <6>
 I: To view a list of clusters and their status, run 'rosa list clusters'
 I: Cluster '<cluster_name>' has been created.
 I: Once the cluster is installed you will need to add an Identity Provider before you can login into the cluster. See 'rosa create idp --help' for more information.
@@ -138,13 +140,18 @@ I: To watch your cluster installation logs, run 'rosa logs install -c <cluster_n
 <2> If more than one matching set of account-wide roles are available in your account for a cluster version, an interactive list of options is provided.
 <3> Multiple availability zones are recommended for production workloads. The default is a single availability zone.
 <4> Enable this option if you are using your own AWS KMS key to encrypt the control plane data volumes and the PVs for your applications. Specify the ARN for the KMS key that you added the account-wide role ARN to in the preceding step.
-<5> The output includes a custom command that you can run to create a cluster with the same configuration in the future.
+<5> Enable this option only if your use case requires etcd key value encryption in addition to the control plane storage encryption that encrypts the etcd volumes by default. With this option, the etcd key values are encrypted, but not the keys.
 +
-[NOTE]
+[IMPORTANT]
 ====
-As an alternative to using the `--interactive` mode, you can specify the customization options directly when you run `rosa create cluster`. Run `rosa create cluster --help` to view a list of available CLI options.
+By enabling etcd encryption for the key values in etcd, you will incur a performance overhead of approximately 20%. The overhead is a result of introducing this second layer of encryption, in addition to the default control plane storage encryption that encrypts the etcd volumes. Red Hat recommends that you enable etcd encryption only if you specifically require it for your use case.
 ====
 +
+<6> The output includes a custom command that you can run to create a cluster with the same configuration in the future.
+--
++
+As an alternative to using the `--interactive` mode, you can specify the customization options directly when you run `rosa create cluster`. Run `rosa create cluster --help` to view a list of available CLI options.
++
 [IMPORTANT]
 ====
 You must complete the following steps to create the Operator IAM roles and the OpenID Connect (OIDC) provider to move the state of the cluster to `ready`.

modules/rosa-sts-interactive-mode-reference.adoc

@@ -8,7 +8,7 @@
 You can create a {product-title} cluster with the AWS Security Token Service (STS) by using the interactive mode. You can enable the mode by specifying the `--interactive` option when you run `rosa create cluster`. The following table describes the interactive mode options.
 
 .`--interactive` mode options
-[cols="1,2",options="header"]
+[cols=".^2,.^3a",options="header"]
 |===
 
 |Field|Description
@@ -64,6 +64,14 @@ You can create a {product-title} cluster with the AWS Security Token Service (ST
 |`Host prefix`
 |Specify the subnet prefix length assigned to pods scheduled to individual machines. The host prefix determines the pod IP address pool for each machine. For example, if the host prefix is set to `/23`, each machine is assigned a `/23` subnet from the pod CIDR address range. The default is `/23`, allowing 512 cluster nodes and 512 pods per node, both of which are beyond our supported maximums. For information on the supported maximums, see the Additional Resources section below.
 
+|`Encrypt etcd data (optional)`
+|In {product-title}, the control plane storage is encrypted at rest by default and this includes encryption of the etcd volumes. You can additionally enable the `Encrypt etcd data` option to encrypt the key values for some resources in etcd, but not the keys.
+
+[IMPORTANT]
+====
+By enabling etcd encryption for the key values in etcd, you will incur a performance overhead of approximately 20%. The overhead is a result of introducing this second layer of encryption, in addition to the default control plane storage encryption that encrypts the etcd volumes. Red Hat recommends that you enable etcd encryption only if you specifically require it for your use case.
+====
+
 |`Disable workload monitoring`
 |Disable monitoring for user-defined projects. Monitoring for user-defined projects is enabled by default.
 

modules/sdpolicy-security.adoc

@@ -1,7 +1,6 @@
-
 // Module included in the following assemblies:
 //
-// * assemblies/osd-service-definition.adoc
+// * osd_policy/osd-service-definition.adoc
 
 [id="sdpolicy-security_{context}"]
 = Security
@@ -66,17 +65,17 @@ With {product-title} on AWS, AWS provides a standard DDoS protection on all Load
 
 In {product-title}, the control plane storage is encrypted at rest by default and this includes encryption of the etcd volumes. This storage-level encryption is provided through the storage layer of the cloud provider.
 
-You can also enable etcd encryption, which encrypts the key values in etcd state, but not the keys. If you enable etcd encryption, the following Kubernetes API server and OpenShift API server resources are encrypted:
+You can also enable etcd encryption, which encrypts the key values in etcd, but not the keys. If you enable etcd encryption, the following Kubernetes API server and OpenShift API server resources are encrypted:
 
 * Secrets
 * Config maps
 * Routes
 * OAuth access tokens
 * OAuth authorize tokens 
 
-The etcd encryption feature is not enabled by default and it can be enabled only at cluster installation time.
+The etcd encryption feature is not enabled by default and it can be enabled only at cluster installation time. Even with etcd encryption enabled, the etcd key values are accessible to anyone with access to the control plane nodes or `cluster-admin` privileges.
 
 [IMPORTANT]
 ====
-By enabling etcd encryption for the key values in etcd state, you might incur a performance overhead of approximately 20%. Red Hat only recommends that you enable etcd encryption in addition to the default storage-level encryption if you specifically require this for your use case.
+By enabling etcd encryption for the key values in etcd, you will incur a performance overhead of approximately 20%. The overhead is a result of introducing this second layer of encryption, in addition to the default control plane storage encryption that encrypts the etcd volumes. Red Hat recommends that you enable etcd encryption only if you specifically require it for your use case.
 ====

osd_cluster_create/creating-your-cluster.adoc

@@ -12,4 +12,12 @@ include::modules/understanding-clusters.adoc[leveloffset=+1]
 
 include::modules/create-aws-cluster.adoc[leveloffset=+1]
 
+.Additional resources
+
+* For more information about etcd encryption, see the xref:../osd_policy/osd-service-definition.adoc#etcd-encryption_osd-service-definition[etcd encryption service definition].
+
 include::modules/create-gcp-cluster.adoc[leveloffset=+1]
+
+.Additional resources
+
+* For more information about etcd encryption, see the xref:../osd_policy/osd-service-definition.adoc#etcd-encryption_osd-service-definition[etcd encryption service definition].

rosa_getting_started_sts/rosa_creating_a_cluster_with_sts/rosa-sts-creating-a-cluster-with-customizations.adoc

@@ -22,4 +22,5 @@ include::modules/rosa-sts-creating-a-cluster-with-customizations.adoc[leveloffse
 * For an overview of the options that are presented when you create a cluster using interactive mode, see xref:../../rosa_getting_started_sts/rosa_creating_a_cluster_with_sts/rosa-sts-interactive-mode-reference.adoc#rosa-sts-interactive-mode-reference[Interactive cluster creation mode reference].
 * For information about the prerequisites to installing ROSA with STS, see xref:../../rosa_getting_started_sts/rosa-sts-aws-prereqs.adoc#rosa-sts-aws-prerequisites[AWS prerequisites for ROSA with STS].
 * For more information about using OpenID Connect (OIDC) identity providers in AWS IAM, see link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html[Creating OpenID Connect (OIDC) identity providers] in the AWS documentation.
+* For more information about etcd encryption, see the xref:../../rosa_policy/rosa-service-definition.adoc#rosa-sdpolicy-etcd-encryption_rosa-service-definition[etcd encryption service definition].
 * For more information about troubleshooting ROSA cluster deployments, see xref:../../rosa_support/rosa-troubleshooting-deployments.adoc#rosa-troubleshooting-cluster-deployments[Troubleshooting cluster deployments].

rosa_getting_started_sts/rosa_creating_a_cluster_with_sts/rosa-sts-interactive-mode-reference.adoc

@@ -14,3 +14,4 @@ include::modules/rosa-sts-interactive-mode-reference.adoc[leveloffset=+1]
  * For a list of the supported maximums, see xref:../../rosa_planning/rosa-limits-scalability.adoc#tested-cluster-maximums_rosa-limits-scalability[ROSA tested cluster maximums].
 * For detailed steps to quickly create a ROSA cluster with STS, including the AWS IAM resources, see xref:../../rosa_getting_started_sts/rosa_creating_a_cluster_with_sts/rosa-sts-creating-a-cluster-quickly.adoc#rosa-sts-creating-a-cluster-quickly[Creating a ROSA cluster with STS quickly].
 * For detailed steps to create a ROSA cluster with STS using customizations, including the AWS IAM resources, see xref:../../rosa_getting_started_sts/rosa_creating_a_cluster_with_sts/rosa-sts-creating-a-cluster-with-customizations.adoc#rosa-sts-creating-a-cluster-with-customizations[Creating a ROSA cluster with STS using customizations].
+* For more information about etcd encryption, see the xref:../../rosa_policy/rosa-service-definition.adoc#rosa-sdpolicy-etcd-encryption_rosa-service-definition[etcd encryption service definition].