Merge pull request #60921 from mjpytlak/osdocs-6222

mjpytlak · web-flow · commit 6d28cda3de35 · 2023-07-25T15:31:21.000-04:00
OSDOCS#6222: Adding custom security groups in AWS
diff --git a/installing/installing_aws/installing-aws-china.adoc b/installing/installing_aws/installing-aws-china.adoc
@@ -33,6 +33,7 @@ include::modules/private-clusters-default.adoc[leveloffset=+1]
 include::modules/private-clusters-about-aws.adoc[leveloffset=+2]
 
 include::modules/installation-custom-aws-vpc.adoc[leveloffset=+1]
+include::modules/installation-aws-security-groups.adoc[leveloffset=+2]
 
 include::modules/ssh-agent-using.adoc[leveloffset=+1]
 
@@ -50,6 +51,8 @@ include::modules/installation-aws-arm-tested-machine-types.adoc[leveloffset=+2]
 
 include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 
+include::modules/installation-applying-aws-security-groups.adoc[leveloffset=+2]
+
 include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
 include::modules/cli-installing-cli.adoc[leveloffset=+1]
diff --git a/installing/installing_aws/installing-aws-government-region.adoc b/installing/installing_aws/installing-aws-government-region.adoc
@@ -32,6 +32,7 @@ include::modules/private-clusters-default.adoc[leveloffset=+1]
 include::modules/private-clusters-about-aws.adoc[leveloffset=+2]
 
 include::modules/installation-custom-aws-vpc.adoc[leveloffset=+1]
+include::modules/installation-aws-security-groups.adoc[leveloffset=+2]
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
@@ -51,6 +52,8 @@ include::modules/installation-aws-config-yaml.adoc[leveloffset=+2]
 
 include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 
+include::modules/installation-applying-aws-security-groups.adoc[leveloffset=+2]
+
 include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
 include::modules/cli-installing-cli.adoc[leveloffset=+1]
diff --git a/installing/installing_aws/installing-aws-localzone.adoc b/installing/installing_aws/installing-aws-localzone.adoc
@@ -74,6 +74,7 @@ include::modules/installation-aws-marketplace-subscribe.adoc[leveloffset=+1]
 include::modules/installation-creating-aws-vpc-localzone.adoc[leveloffset=+1]
 
 include::modules/installation-cloudformation-vpc-localzone.adoc[leveloffset=+2]
+include::modules/installation-aws-security-groups.adoc[leveloffset=+2]
 
 include::modules/installation-aws-add-local-zone-locations.adoc[leveloffset=+1]
 
@@ -97,7 +98,7 @@ include::modules/installation-aws-tested-machine-types.adoc[leveloffset=+2]
 [role="_additional-resources"]
 .Additional resources
 
-* See link:https://aws.amazon.com/about-aws/global-infrastructure/localzones/features/[AWS Local Zones features] in the AWS documentation for more information about AWS Local Zones and the supported instances types and services. 
+* See link:https://aws.amazon.com/about-aws/global-infrastructure/localzones/features/[AWS Local Zones features] in the AWS documentation for more information about AWS Local Zones and the supported instances types and services.
 
 include::modules/installation-generate-aws-user-infra-install-config.adoc[leveloffset=+2]
 // Suggest to standarize edge-pool's specific files with same prefixes, like: machine-edge-pool-[...] or compute-edge-pool-[...] (which is more compatible with install-config.yaml/compute)
diff --git a/installing/installing_aws/installing-aws-outposts-remote-workers.adoc b/installing/installing_aws/installing-aws-outposts-remote-workers.adoc
@@ -34,6 +34,7 @@ Since the cluster uses the provided AWS credentials to create AWS resources for
 * If the cloud identity and access management (IAM) APIs are not accessible in your environment, or if you do not want to store an administrator-level credential secret in the `kube-system` namespace, you can xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually create and maintain IAM credentials].
 
 include::modules/installation-custom-aws-vpc.adoc[leveloffset=+1]
+include::modules/installation-aws-security-groups.adoc[leveloffset=+2]
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
@@ -50,6 +51,7 @@ include::modules/installation-initializing.adoc[leveloffset=+1]
 include::modules/installation-configuration-parameters.adoc[leveloffset=+2]
 
 include::modules/installation-aws-config-yaml.adoc[leveloffset=+2]
+include::modules/installation-applying-aws-security-groups.adoc[leveloffset=+2]
 
 include::modules/installation-aws-editing-manifests.adoc[leveloffset=+1]
 
diff --git a/installing/installing_aws/installing-aws-private.adoc b/installing/installing_aws/installing-aws-private.adoc
@@ -27,6 +27,7 @@ include::modules/private-clusters-default.adoc[leveloffset=+1]
 include::modules/private-clusters-about-aws.adoc[leveloffset=+2]
 
 include::modules/installation-custom-aws-vpc.adoc[leveloffset=+1]
+include::modules/installation-aws-security-groups.adoc[leveloffset=+2]
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
@@ -47,6 +48,8 @@ include::modules/installation-aws-config-yaml.adoc[leveloffset=+2]
 
 include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 
+include::modules/installation-applying-aws-security-groups.adoc[leveloffset=+2]
+
 include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
 include::modules/cli-installing-cli.adoc[leveloffset=+1]
diff --git a/installing/installing_aws/installing-aws-secret-region.adoc b/installing/installing_aws/installing-aws-secret-region.adoc
@@ -35,6 +35,7 @@ include::modules/private-clusters-default.adoc[leveloffset=+1]
 include::modules/private-clusters-about-aws.adoc[leveloffset=+2]
 
 include::modules/installation-custom-aws-vpc.adoc[leveloffset=+1]
+include::modules/installation-aws-security-groups.adoc[leveloffset=+2]
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
@@ -49,6 +50,7 @@ include::modules/installation-configuration-parameters.adoc[leveloffset=+2]
 include::modules/installation-aws-tested-machine-types.adoc[leveloffset=+2]
 include::modules/installation-aws-config-yaml.adoc[leveloffset=+2]
 include::modules/installation-configure-proxy.adoc[leveloffset=+2]
+include::modules/installation-applying-aws-security-groups.adoc[leveloffset=+2]
 
 include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
diff --git a/installing/installing_aws/installing-aws-vpc.adoc b/installing/installing_aws/installing-aws-vpc.adoc
@@ -23,6 +23,7 @@ If you have an AWS profile stored on your computer, it must not use a temporary
 * If the cloud identity and access management (IAM) APIs are not accessible in your environment, or if you do not want to store an administrator-level credential secret in the `kube-system` namespace, you can xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually create and maintain IAM credentials].
 
 include::modules/installation-custom-aws-vpc.adoc[leveloffset=+1]
+include::modules/installation-aws-security-groups.adoc[leveloffset=+2]
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
@@ -43,6 +44,8 @@ include::modules/installation-aws-config-yaml.adoc[leveloffset=+2]
 
 include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 
+include::modules/installation-applying-aws-security-groups.adoc[leveloffset=+2]
+
 include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
 include::modules/cli-installing-cli.adoc[leveloffset=+1]
diff --git a/modules/installation-applying-aws-security-groups.adoc b/modules/installation-applying-aws-security-groups.adoc
@@ -0,0 +1,58 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/installing-aws-vpc.adoc
+// * installing/installing_aws/installing-aws-private.adoc
+// * installing/installing_aws/installing-aws-government-region.adoc
+// * installing/installing_aws/installing-aws-secret-region.adoc
+// * installing/installing_aws/installing-aws-china.adoc
+// * installing/installing_aws/installing-aws-outposts-remote-workers.adoc
+
+:_content-type: PROCEDURE
+[id="installation-aws-vpc-security-groups_{context}"]
+= Applying existing AWS security groups to the cluster
+
+Applying existing AWS security groups to your control plane and compute machines can help you meet the security needs of your organization, in such cases where you need to control the incoming or outgoing traffic of these machines.
+
+.Prerequisites
+* You have created the security groups in AWS. For more information, see the AWS documentation about working with link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-security-groups.html[security groups].
+* The security groups must be associated with the existing VPC that you are deploying the cluster to. The security groups cannot be associated with another VPC.
+* You have an existing `install-config.yaml` file.
+
+.Procedure
+
+. In the `install-config.yaml` file, edit the `compute.platform.aws.additionalSecurityGroupIDs` parameter to specify one or more custom security groups for your compute machines.
+. Edit the `controlPlane.platform.aws.additionalSecurityGroupIDs` parameter to specify one or more custom security groups for your control plane machines.
+. Save the file and reference it when deploying the cluster.
+
+.Sample `install-config.yaml` file that specifies custom security groups
+[source,yaml]
+----
+# ...
+compute:
+- hyperthreading: Enabled
+  name: worker
+  platform:
+    aws:
+      additionalSecurityGroupIDs:
+        - sg-1 <1>
+        - sg-2
+  replicas: 3
+controlPlane:
+  hyperthreading: Enabled
+  name: master
+  platform:
+    aws:
+      additionalSecurityGroupIDs:
+        - sg-3
+        - sg-4
+  replicas: 3
+platform:
+  aws:
+    region: us-east-1
+    subnets: <2>
+      - subnet-1
+      - subnet-2
+      - subnet-3
+----
+<1> Specify the name of the security group as it appears in the Amazon EC2 console, including the `sg` prefix.
+<2> Specify subnets for each availability zone that your cluster uses.
diff --git a/modules/installation-aws-security-groups.adoc b/modules/installation-aws-security-groups.adoc
@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_aws/installing-aws-vpc.adoc
+// * installing/installing_aws/installing-aws-private.adoc
+// * installing/installing_aws/installing-aws-government-region.adoc
+// * installing/installing_aws/installing-aws-secret-region.adoc
+// * installing/installing_aws/installing-aws-china.adoc
+// * installing/installing_aws/installing-aws-localzone.adoc
+// * installing/installing_aws/installing-aws-outposts-remote-workers.adoc
+
+ifeval::["{context}" == "installing-aws-localzone"]
+:localzone:
+endif::[]
+
+:_content-type: CONCEPT
+[id="installation-aws-security-groups_{context}"]
+= AWS security groups
+
+By default, the installation program creates and attaches security groups to control plane and compute machines. The rules associated with the default security groups cannot be modified.
+
+However, you can apply additional existing AWS security groups, which are associated with your existing VPC, to control plane and compute machines. Applying custom security groups can help you meet the security needs of your organization, in such cases where you need to control the incoming or outgoing traffic of these machines.
+
+As part of the installation process, you apply custom security groups by modifying the `install-config.yaml` file before deploying the cluster.
+
+ifndef::localzone[]
+For more information, see "Applying existing AWS security groups to the cluster".
+endif::localzone[]
+ifdef::localzone[]
+For more information, see "The edge compute pool for AWS Local Zones".
+endif::localzone[]
+
+ifeval::["{context}" == "installing-aws-localzone"]
+:!localzone:
+endif::[]
diff --git a/modules/machines-edge-machine-pool.adoc b/modules/machines-edge-machine-pool.adoc
@@ -18,9 +18,9 @@ The edge compute pool creates new labels that developers can use to deploy appli
 
 By default, the system creates the edge compute pool manifests only if users add AWS Local Zone subnet IDs to the list `platform.aws.subnets`.
 
-The edge compute pool's machine sets have a `NoSchedule taint` by default to prevent regular workloads from being spread out on those machines. Users can only run user workloads if the tolerations are defined on the pod spec. 
+The edge compute pool's machine sets have a `NoSchedule taint` by default to prevent regular workloads from being spread out on those machines. Users can only run user workloads if the tolerations are defined on the pod spec.
 
-The following examples show `install-config.yaml` files that use the edge machine pool. 
+The following examples show `install-config.yaml` files that use the edge machine pool.
 
 .Configuration that uses an edge pool with default settings
 [source,yaml]
@@ -102,4 +102,34 @@ pullSecret: '{"auths": ...}'
 sshKey: ssh-ed25519 AAAA...
 ----
 
-EBS types differ between locations. Check the AWS documentation to verify availability in the Local Zone in which the cluster will run.
+EBS types differ between locations. Check the AWS documentation to verify availability in the Local Zone in which the cluster will run.
+
+.Configuration that uses an edge pool with custom security groups
+[source,yaml]
+----
+apiVersion: v1
+baseDomain: devcluster.openshift.com
+metadata:
+  name: ipi-localzone
+compute:
+- name: edge
+  platform:
+    aws:
+      additionalSecurityGroupIDs:
+        - sg-1 <1>
+        - sg-2
+platform:
+  aws:
+    region: us-west-2
+    subnets:
+    - publicSubnetId-1
+    - publicSubnetId-2
+    - publicSubnetId-3
+    - privateSubnetId-1
+    - privateSubnetId-2
+    - privateSubnetId-3
+    - publicSubnetId-LocalZone-1
+pullSecret: '{"auths": ...}'
+sshKey: ssh-ed25519 AAAA...
+----
+<1> Specify the name of the security group as it appears in the Amazon EC2 console, including the `sg` prefix.
