Skip to content

Commit 352c509

Browse files
EricPonvelleEricPonvelle
committed
OSDOCS-17466: Added FIPS encryption documentation
1 parent 2c52309 commit 352c509

11 files changed

Lines changed: 359 additions & 35 deletions

‎_topic_maps/_topic_map_rosa_hcp.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,8 @@ Topics:
194194
File: rosa-hcp-creating-a-cluster-quickly-terraform
195195
- Name: Creating ROSA clusters using a custom AWS KMS encryption key
196196
File: rosa-hcp-creating-cluster-with-aws-kms-key
197+
- Name: Deploying Red Hat OpenShift Service on AWS clusters using FIPS encryption
198+
File: rosa-hcp-creating-cluster-with-fips-encryption
197199
- Name: Configuring a shared virtual private cloud for ROSA clusters
198200
File: rosa-hcp-shared-vpc-config
199201
- Name: Creating a private cluster on ROSA

‎modules/aws-encryption-key.adoc‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/monitoring/enabling-monitoring-for-user-defined-projects.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="aws-encryption-key_{context}"]
7+
= Create an AWS KMS encryption key
8+
9+
[role="_abstract"]
10+
Using your AWS account and the `aws` CLI tool, you can create an AWS KMS encryption key to encypt your resources.
11+
12+
.Procedure
13+
14+
. Set the AWS region where you installed your VPC by running the following command:
15+
+
16+
[NOTE]
17+
====
18+
You should use the same region where you installed your VPC.
19+
====
20+
+
21+
[source,terminal]
22+
----
23+
$ AWS_REGION=<aws_region>
24+
----
25+
26+
. Create a custom AWS customer-managed KMS key by running the following command:
27+
+
28+
[source,terminal]
29+
----
30+
$ KMS_ARN=$(aws kms create-key --region $AWS_REGION --description 'Custom ROSA Encryption Key' --tags TagKey=red-hat,TagValue=true --query KeyMetadata.Arn --output text)
31+
----
32+
+
33+
This command saves the Amazon Resource Name (ARN) output of this custom key for further steps.
34+
+
35+
[NOTE]
36+
====
37+
Customers must provide the `--tags TagKey=red-hat,TagValue=true` argument that is required for a customer KMS key.
38+
====
39+
40+
. Verify the KMS key has been created by running the following command:
41+
+
42+
[source,terminal]
43+
----
44+
$ echo $KMS_ARN
45+
----
46+
47+
. Set your AWS account ID to an environment variable by running the following command:
48+
+
49+
[source,terminal]
50+
----
51+
$ AWS_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
52+
----
53+
54+
. Create your AWS key policy by running the following command.
55+
+
56+
[NOTE]
57+
====
58+
If you use the default prefix, you need to modify the following code sample where you see `{PREFIX}-` to `ManagedOpenShift-`.
59+
====
60+
+
61+
[source,terminal]
62+
----
63+
cat << EOF > rosa-key-policy.json
64+
{
65+
"Version": "2012-10-17",
66+
"Id": "key-rosa-policy-1",
67+
"Statement": [
68+
{
69+
"Sid": "Enable IAM User Permissions",
70+
"Effect": "Allow",
71+
"Principal": {
72+
"AWS": "arn:aws:iam::${AWS_ACCOUNT}:root"
73+
},
74+
"Action": "kms:*",
75+
"Resource": "*"
76+
},
77+
{
78+
"Sid": "Allow ROSA use of the key",
79+
"Effect": "Allow",
80+
"Principal": {
81+
"AWS": [
82+
"arn:aws:iam::${AWS_ACCOUNT}:role/${PREFIX}-HCP-ROSA-Support-Role",
83+
"arn:aws:iam::${AWS_ACCOUNT}:role/${PREFIX}-HCP-ROSA-Installer-Role",
84+
"arn:aws:iam::${AWS_ACCOUNT}:role/${PREFIX}-HCP-ROSA-Worker-Role",
85+
"arn:aws:iam::${AWS_ACCOUNT}:role/${PREFIX}-openshift-cluster-csi-drivers-ebs-cloud-credentials",
86+
"arn:aws:iam::${AWS_ACCOUNT}:role/${PREFIX}-kube-system-kms-provider"
87+
]
88+
},
89+
"Action": [
90+
"kms:Encrypt",
91+
"kms:Decrypt",
92+
"kms:ReEncrypt*",
93+
"kms:GenerateDataKey*",
94+
"kms:DescribeKey"
95+
],
96+
"Resource": "*"
97+
},
98+
{
99+
"Sid": "Allow attachment of persistent resources",
100+
"Effect": "Allow",
101+
"Principal": {
102+
"AWS": [
103+
"arn:aws:iam::${AWS_ACCOUNT}:role/${PREFIX}-HCP-ROSA-Support-Role",
104+
"arn:aws:iam::${AWS_ACCOUNT}:role/${PREFIX}-HCP-ROSA-Installer-Role",
105+
"arn:aws:iam::${AWS_ACCOUNT}:role/${PREFIX}-HCP-ROSA-Worker-Role",
106+
"arn:aws:iam::${AWS_ACCOUNT}:role/${PREFIX}-openshift-cluster-csi-drivers-ebs-cloud-credentials"
107+
]
108+
},
109+
"Action": [
110+
"kms:CreateGrant",
111+
"kms:ListGrants",
112+
"kms:RevokeGrant"
113+
],
114+
"Resource": "*",
115+
"Condition": {
116+
"Bool": {
117+
"kms:GrantIsForAWSResource": "true"
118+
}
119+
}
120+
}
121+
]
122+
}
123+
EOF
124+
----
125+
126+
. Confirm the details of the policy file created by running the following command:
127+
+
128+
[source,terminal]
129+
----
130+
$ cat rosa-key-policy.json
131+
----
132+
133+
. Apply the newly generated key policy to the custom KMS key by running the following command:
134+
+
135+
[source,terminal]
136+
----
137+
aws kms put-key-policy --key-id $KMS_ARN --policy file://rosa-key-policy.json --policy-name default
138+
----
139+
+
140+
You can now create your cluster using this AWS KMS encryption key.

‎modules/creating-cluster-with-fips-encryption.adoc‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/monitoring/enabling-monitoring-for-user-defined-projects.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="creating-cluster-with-fips-encryption_{context}"]
7+
= Creating a {product-title} cluster using a custom AWS KMS key
8+
9+
[role="_abstract"]
10+
You can create a {product-title} cluster with Federal Information Processing Standards (FIPS) encryption that uses a customer-provided KMS key to encrypt either node root volumes, the etcd database, or both. A different KMS key ARN can be provided for each option.
11+
12+
[NOTE]
13+
====
14+
{product-title} does not automatically configure the `default` storage class to encrypt persistent volumes with the customer-provided KMS key. This is something that can be configured in-cluster after installation.
15+
====
16+
17+
.Procedure
18+
19+
. Verify the KMS key has been created by running the following command:
20+
+
21+
[source,terminal]
22+
----
23+
$ echo $KMS_ARN
24+
----
25+
26+
. Confirm the details of the policy file created by running the following command:
27+
+
28+
[source,terminal]
29+
----
30+
$ cat rosa-key-policy.json
31+
----
32+
33+
. Create the cluster by running the following command:
34+
+
35+
--
36+
include::snippets/rosa-long-cluster-name.adoc[]
37+
--
38+
+
39+
[source,terminal]
40+
----
41+
$ rosa create cluster \
42+
--cluster-name ${PREFIX}-test \
43+
--hosted-cp \
44+
--machine-cidr 10.0.0.0/16 \
45+
--oidc-config-id $OIDC_CONFIG \
46+
--mode auto \
47+
--region $AWS_REGION \
48+
--replicas 2 \
49+
--operator-roles-prefix $PREFIX \
50+
--installer-role-arn "arn:aws:iam::${AWS_ACCOUNT}:role/${PREFIX}-HCP-ROSA-Installer-Role" \
51+
--support-role-arn "arn:aws:iam::${AWS_ACCOUNT}:role/${PREFIX}-HCP-ROSA-Support-Role" \
52+
--worker-iam-role-arn "arn:aws:iam::${AWS_ACCOUNT}:role/${PREFIX}-HCP-ROSA-Worker-Role" \
53+
--subnet-ids <subnet-ids> \
54+
--etcd-encryption \
55+
--etcd-encryption-kms-arn $KMS_ARN \
56+
--fips
57+
----
58+
+
59+
--
60+
where:
61+
62+
`--subnet-ids`:: These subnet IDs should be at least one private subnet ID and public subnet ID.
63+
`--kms-key-arn`:: This KMS key ARN is used to encrypt all worker node root volumes. It is not required if only etcd database encryption is needed.
64+
`--etcd-encryption-kms-arn`:: This KMS key ARN is used to encrypt the etcd database. The etcd database is always encrypted by default with an AES cipher block, but can be encrypted instead with a KMS key. It is not required if only node root volume encryption is needed.
65+
--
66+
67+
.Verification
68+
69+
. Log in to your cluster as an admin user.
70+
. Set the node name as a variable by running the following command:
71+
+
72+
[source,terminal]
73+
----
74+
$ NODE=$(oc get nodes --no-headers | awk '$2=="Ready"{print $1; exit}')
75+
----
76+
77+
. Check your cluster's FIPS status by running the following command:
78+
+
79+
[source,terminal]
80+
----
81+
$ oc debug node/${NODE} --to-namespace=default -- chroot /host bash -c 'set -x; \
82+
fips-mode-setup --check; \
83+
update-crypto-policies --show; \
84+
cat /etc/system-fips; \
85+
cat /proc/sys/crypto/fips_enabled; \
86+
sysctl crypto.fips_enabled'
87+
----
88+
+
89+
.Example output
90+
[source,terminal]
91+
----
92+
Starting pod/ip-10-0-1-162us-east-2computeinternal-debug-86cnb ...
93+
To use host binaries, run `chroot /host`
94+
+ fips-mode-setup --check
95+
FIPS mode is enabled.
96+
+ update-crypto-policies --show
97+
FIPS
98+
+ cat /etc/system-fips
99+
# FIPS module installation complete
100+
+ cat /proc/sys/crypto/fips_enabled
101+
1
102+
+ sysctl crypto.fips_enabled
103+
crypto.fips_enabled = 1
104+
105+
Removing debug pod ...
106+
----

‎modules/rosa-hcp-creating-account-wide-sts-roles-and-policies.adoc‎

Lines changed: 26 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@
99
ifeval::["{context}" == "rosa-hcp-egress-zero-install"]
1010
:egress-lockdown:
1111
endif::[]
12+
ifeval::["{context}" == "rosa-hcp-creating-cluster-with-fips-encryption"]
13+
:fips:
14+
endif::[]
1215

1316
:_mod-docs-content-type: PROCEDURE
1417
[id="rosa-sts-creating-account-wide-sts-roles-and-policies_{context}"]
@@ -19,25 +22,35 @@ Account-wide roles, like, `account-roles` in the {rosa-cli-first} are required
1922

2023
[NOTE]
2124
====
22-
Specific AWS-managed policies for {product-title} must be attached to each role. Customer-managed policies must not be used with these required account roles. For more information regarding AWS-managed policies for {product-title} clusters, see link:https://docs.aws.amazon.com/ROSA/latest/userguide/security-iam-awsmanpol-account-policies.html[AWS managed policies for ROSA].
25+
Specific AWS-managed policies for {product-title} must be attached to each role. Customer-managed policies must not be used with these required account roles. For more information regarding AWS-managed policies for {product-title} clusters, see link:https://docs.aws.amazon.com/ROSA/latest/userguide/security-iam-awsmanpol-account-policies.html[AWS managed policies for {product-title}].
2326
====
2427

2528
.Prerequisites
2629

2730
* You have completed the AWS prerequisites for {product-title}.
2831
* You have available AWS service quotas.
2932
* You have enabled the {product-title} in the AWS Console.
30-
* You have installed and configured the latest ROSA CLI (`rosa`) on your installation host.
31-
* You have logged in to your Red{nbsp}Hat account by using the ROSA CLI.
33+
* You have installed and configured the latest {rosa-cli-first} on your installation host.
34+
* You have logged in to your Red{nbsp}Hat account by using the {rosa-cli}.
3235
3336
.Procedure
3437

3538
. If they do not exist in your AWS account, create the required account-wide STS roles and attach the policies by running the following command:
3639
+
40+
ifndef::fips[]
3741
[source,terminal]
3842
----
3943
$ rosa create account-roles --hosted-cp
4044
----
45+
endif::fips[]
46+
ifdef::fips[]
47+
[source,terminal]
48+
----
49+
$ export PREFIX=<custom_prefix>; rosa create account-roles --hosted-cp --prefix $PREFIX
50+
----
51+
+
52+
When using FIPS encryption, you need to set a custom prefix instead of using the default `ManagedOpenShift` prefix.
53+
endif::fips[]
4154

4255
ifdef::egress-lockdown[]
4356
. Ensure that the your worker role has the correct AWS policy by running the following command:
@@ -54,6 +67,7 @@ $ aws iam attach-role-policy \
5467
--
5568
endif::egress-lockdown[]
5669

70+
ifndef::fips[]
5771
. Optional: Set your prefix as an environmental variable by running the following command:
5872
+
5973
[source,terminal]
@@ -74,9 +88,16 @@ For example:
7488
----
7589
ManagedOpenShift
7690
----
77-
+
78-
For more information regarding AWS managed IAM policies for {product-title}, see link:https://docs.aws.amazon.com/ROSA/latest/userguide/security-iam-awsmanpol.html[AWS managed IAM policies for ROSA].
91+
endif::fips[]
92+
93+
[role="_additional-resources"]
94+
.Additional resources
7995

96+
* link:https://docs.aws.amazon.com/ROSA/latest/userguide/security-iam-awsmanpol.html[AWS managed IAM policies for {product-title}]
97+
98+
ifeval::["{context}" == "rosa-hcp-creating-cluster-with-fips-encryption"]
99+
:!fips:
100+
endif::[]
80101
ifeval::["{context}" == "rosa-hcp-egress-zero-install"]
81102
:!egress-lockdown:
82103
endif::[]

‎modules/rosa-hcp-creating-vpc.adoc‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,6 @@
1111
You must have an AWS Virtual Private Cloud (VPC) to create a {product-title} cluster. You can use the following methods to create a VPC:
1212

1313
* Create a VPC using the {rosa-cli}
14-
* Create a VPC by using a Terraform template
1514
* Manually create the VPC resources in the AWS console
1615

1716
[NOTE]

‎modules/rosa-operator-config.adoc‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@
77
// * rosa_hcp/rosa-hcp-egress-zero-install.adoc
88
// * rosa_planning/rosa-hcp-prepare-iam-roles-resources.adoc
99

10+
ifeval::["{context}" == "rosa-hcp-creating-cluster-with-fips-encryption"]
11+
:fips:
12+
endif::[]
13+
1014
:_mod-docs-content-type: PROCEDURE
1115
[id="rosa-operator-config_{context}"]
1216
= Creating Operator roles and policies
@@ -21,8 +25,18 @@ When you deploy a {product-title} cluster, you must create the Operator IAM role
2125
* You created the account-wide AWS roles.
2226
2327
.Procedure
24-
25-
* To create your Operator roles, run the following command:
28+
ifdef::fips[]
29+
. To create your Operator roles, run the following command:
30+
+
31+
[source,terminal]
32+
----
33+
$ rosa create operator-roles --hosted-cp --prefix=$PREFIX --oidc-config-id=$OIDC_ID
34+
----
35+
+
36+
The Operator roles are now created and ready to use for creating your {product-title} cluster.
37+
endif::fips[]
38+
ifndef::fips[]
39+
. To create your Operator roles, run the following command:
2640
+
2741
[source,terminal]
2842
----
@@ -82,6 +96,7 @@ where:
8296
--
8397
+
8498
The Operator roles are now created and ready to use for creating your {product-title} cluster.
99+
endif::fips[]
85100

86101
.Verification
87102

@@ -112,4 +127,8 @@ ROLE NAME ROLE ARN
112127
<prefix>-openshift-ingress-operator-cloud-credentials arn:aws:iam::4540112244:role/<prefix>-openshift-ingress-operator-cloud-credentials 4.13 No
113128
----
114129
+
115-
After the command runs, it displays all the prefixes associated with your AWS account and notes how many roles are associated with this prefix. If you need to see all of these roles and their details, enter "Yes" on the detail prompt to have these roles listed out with specifics.
130+
After the command runs, it displays all the prefixes associated with your AWS account and notes how many roles are associated with this prefix. If you need to see all of these roles and their details, enter "Yes" on the detail prompt to have these roles listed out with specifics.
131+
132+
ifeval::["{context}" == "rosa-hcp-creating-cluster-with-fips-encryption"]
133+
:!fips:
134+
endif::[]

0 commit comments

Comments
 (0)