Merge pull request #66328 from laubai/osdocs-8034-custom-secgroups-day1-cli

OSDOCS#8034: additional custom security groups at ROSA cluster creation time

Author: michaelryanpeter

cli_reference/rosa_cli/rosa-manage-objects-cli.adoc

@@ -18,6 +18,7 @@ include::modules/rosa-create-objects.adoc[leveloffset=+1]
 * See xref:../../rosa_architecture/rosa_policy_service_definition/rosa-service-definition.adoc#rosa-sdpolicy-aws-instance-types_rosa-service-definition[AWS Instance types] for a list of supported instance types.
 * See xref:../../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-account-wide-roles-and-policies_rosa-sts-about-iam-resources[Account-wide IAM role and policy reference] for a list of IAM roles needed for cluster creation.
 * See xref:../../rosa_install_access_delete_clusters/rosa-sts-creating-a-cluster-with-customizations.adoc#rosa-sts-understanding-aws-account-association_rosa-sts-creating-a-cluster-with-customizations[Understanding AWS account association] for more information about the OCM role and user role.
+* See xref:../../rosa_install_access_delete_clusters/rosa_getting_started_iam/rosa-aws-prereqs.adoc#rosa-security-groups_prerequisites[Security groups] for information about security group requirements.
 
 include::modules/rosa-edit-objects.adoc[leveloffset=+1]
 include::modules/rosa-delete-objects.adoc[leveloffset=+1]

cloud_experts_tutorials/rosa-mobb-cli-quickstart.adoc

@@ -211,12 +211,13 @@ ROSA can be installed using command line parameters or in interactive mode.  For
   ```
   Cluster name:
   Multiple availability zones (y/N):
-  AWS region (select):
-  OpenShift version (select):
+  AWS region: (select)
+  OpenShift version: (select)
   Install into an existing VPC (y/N):
-  Compute nodes instance type (optional):
+  Compute nodes instance type (optional): (select)
   Enable autoscaling (y/N):
   Compute nodes [2]:
+  Additional Security Group IDs (optional): (select)
   Machine CIDR [10.0.0.0/16]:
   Service CIDR [172.30.0.0/16]:
   Pod CIDR [10.128.0.0/14]:

modules/creating-a-machine-pool-cli.adoc

@@ -31,6 +31,7 @@ $ rosa create machinepool --cluster=<cluster-name> \
 ifdef::openshift-rosa[]
                           --disk-size=<disk_size> <8>
                           --availability-zone=<az> <9>
+                          --additional-security-group-ids <sec_group_id> <10>
 
 endif::openshift-rosa[]
 ----
@@ -44,6 +45,7 @@ endif::openshift-rosa[]
 ifdef::openshift-rosa[]
 <8> Optional: Specifies the worker node disk size. The value can be in GB, GiB, TB, or TiB. Replace `<disk_size>` with a numeric value and unit, for example `--disk-size=200GiB`.
 <9> Optional: For Multi-AZ clusters, you can create a machine pool in a Single-AZ of your choice. Replace `<az>` with a Single-AZ.
+<10> Optional: For machine pools in clusters that do not have Red Hat managed VPCs, you can select additional custom security groups to use in your machine pools. You must have already created the security groups and associated them with the VPC you selected for this cluster. For more information, see the requirements for _Security groups_ in _Prepare your environment_.
 endif::openshift-rosa[]
 +
 [IMPORTANT]

modules/rosa-adding-node-labels.adoc

@@ -109,9 +109,9 @@ $ rosa list machinepools --cluster=<cluster_name>
 .Example output
 [source,terminal]
 ----
-ID           AUTOSCALING  REPLICAS  INSTANCE TYPE  LABELS                  TAINTS    AVAILABILITY ZONES    SPOT INSTANCES
-Default      No           2         m5.xlarge                                        us-east-1a            N/A
-db-nodes-mp  No           2         m5.xlarge      app=db, tier=backend              us-east-1a            No
+ID           AUTOSCALING  REPLICAS  INSTANCE TYPE  LABELS                  TAINTS    AVAILABILITY ZONES    SPOT INSTANCES   DISK SIZE   SG IDs
+Default      No           2         m5.xlarge                                        us-east-1a            N/A              300 GiB     sg-0e375ff0ec4a6cfa2
+db-nodes-mp  No           2         m5.xlarge      app=db, tier=backend              us-east-1a            No               300 GiB     sg-0e375ff0ec4a6cfa2
 ----
 
 . Verify that the labels are included for your machine pool in the output.

modules/rosa-adding-taints-cli.adoc

@@ -40,9 +40,9 @@ $ rosa list machinepools --cluster=<cluster_name>
 +
 [source,terminal]
 ----
-ID           AUTOSCALING  REPLICAS  INSTANCE TYPE  LABELS    TAINTS    AVAILABILITY ZONES    SPOT INSTANCES
-Default      No           2         m5.xlarge                          us-east-1a            N/A
-db-nodes-mp  No           2         m5.xlarge                          us-east-1a            No
+ID           AUTOSCALING  REPLICAS  INSTANCE TYPE  LABELS    TAINTS    AVAILABILITY ZONES    SPOT INSTANCES     DISK SIZE   SG IDs
+Default      No           2         m5.xlarge                          us-east-1a            N/A                300 GiB     sg-0e375ff0ec4a6cfa2
+db-nodes-mp  No           2         m5.xlarge                          us-east-1a            No                 300 GiB     sg-0e375ff0ec4a6cfa2
 ----
 
 . Add or update the taints for a machine pool:
@@ -110,9 +110,9 @@ $ rosa list machinepools --cluster=<cluster_name>
 .Example output
 [source,terminal]
 ----
-ID           AUTOSCALING  REPLICAS  INSTANCE TYPE  LABELS    TAINTS                                           AVAILABILITY ZONES    SPOT INSTANCES
-Default      No           2         m5.xlarge                                                                 us-east-1a            N/A
-db-nodes-mp  No           2         m5.xlarge                key1=value1:NoSchedule, key2=value2:NoExecute    us-east-1a            No
+ID           AUTOSCALING  REPLICAS  INSTANCE TYPE  LABELS    TAINTS                                           AVAILABILITY ZONES    SPOT INSTANCES  DISK SIZE   SG IDs
+Default      No           2         m5.xlarge                                                                 us-east-1a            N/A             300GiB      sg-0e375ff0ec4a6cfa2
+db-nodes-mp  No           2         m5.xlarge                key1=value1:NoSchedule, key2=value2:NoExecute    us-east-1a            No              300GiB      sg-0e375ff0ec4a6cfa2
 ----
 
 . Verify that the taints are included for your machine pool in the output.

modules/rosa-adding-tuning.adoc

@@ -34,9 +34,9 @@ $ rosa list machinepools --cluster=<cluster_name>
 +
 [source,terminal]
 ----
-ID           AUTOSCALING  REPLICAS  INSTANCE TYPE  LABELS    TAINTS    AVAILABILITY ZONES    SUBNET  VERSION  AUTOREPAIR  TUNING CONFIGS  MESSAGE
-Default      No           2         m5.xlarge                          us-east-1a            N/A     4.12.14  Yes
-db-nodes-mp  No           2         m5.xlarge                          us-east-1a            No      4.12.14  Yes
+ID           AUTOSCALING  REPLICAS  INSTANCE TYPE  LABELS    TAINTS    AVAILABILITY ZONES    SUBNETS  VERSION  AUTOREPAIR  TUNING CONFIGS  MESSAGE
+Default      No           2         m5.xlarge                          us-east-1a            N/A      4.12.14  Yes
+db-nodes-mp  No           2         m5.xlarge                          us-east-1a            No       4.12.14  Yes         
 ----
 
 . You can add tuning configurations to an existing or new machine pool.

modules/rosa-aws-privatelink-create-cluster.adoc

@@ -2,7 +2,7 @@
 //
 // * rosa_install_access_delete_clusters/rosa-aws-privatelink-creating-cluster.adoc
 :_mod-docs-content-type: PROCEDURE
-[id="rosa-aws-privatelink-create-cluster.adoc_{context}"]
+[id="rosa-aws-privatelink-create-cluster_{context}"]
 = Creating an AWS PrivateLink cluster
 
 You can create an AWS PrivateLink cluster using the {product-title} (ROSA) CLI, `rosa`.
@@ -14,13 +14,15 @@ AWS PrivateLink is supported on existing VPCs only.
 
 .Prerequisites
 
-You have installed {product-title}.
+* You have available AWS service quotas.
+* You have enabled the ROSA service in the AWS Console.
+* You have installed and configured the latest {product-title} (ROSA) CLI, `rosa`, on your installation host.
 
 .Procedure
 
 Creating a cluster can take up to 40 minutes.
 
-. With AWS PrivateLink, you can create a cluster with a single availability zone (Single-AZ) or multiple availability zones (Multi-AZ). In either case, your machine's  classless inter-domain routing (CIDR) must match your virtual private cloud's CIDR. See https://docs.openshift.com/container-platform/4.7/installing/installing_aws/installing-aws-vpc.html#installation-custom-aws-vpc-requirements_installing-aws-vpc[Requirements for using your own VPC] and link:https://docs.openshift.com/container-platform/4.7/installing/installing_aws/installing-aws-vpc.html#installation-custom-aws-vpc-validation_installing-aws-vpc[VPC Validation] for more information.
+. With AWS PrivateLink, you can create a cluster with a single availability zone (Single-AZ) or multiple availability zones (Multi-AZ). In either case, your machine's classless inter-domain routing (CIDR) must match your virtual private cloud's CIDR. See https://docs.openshift.com/container-platform/4.13/installing/installing_aws/installing-aws-vpc.html#installation-custom-aws-vpc-requirements_installing-aws-vpc[Requirements for using your own VPC] and link:https://docs.openshift.com/container-platform/4.13/installing/installing_aws/installing-aws-vpc.html#installation-custom-aws-vpc-validation_installing-aws-vpc[VPC Validation] for more information.
 +
 [IMPORTANT]
 ====

modules/rosa-aws-provisioned.adoc

@@ -80,15 +80,15 @@ A *public subnet* connects directly to the internet through an internet gateway.
 
 * *NAT gateways*: One NAT Gateway per public subnet.
 
-=== Sample VPC Architecture
-
+.Sample VPC Architecture
 image::VPC-Diagram.png[VPC Reference Architecture]
 
 [id="rosa-security-groups_{context}"]
 == Security groups
 
 AWS security groups provide security at the protocol and port access level; they are associated with EC2 instances and Elastic Load Balancing (ELB) load balancers. Each security group contains a set of rules that filter traffic coming in and out of one or more EC2 instances. You must ensure the ports required for the OpenShift installation are open on your network and configured to allow access between hosts.
 
+.Required ports for default security groups
 [cols="2a,2a,2a,2a",options="header"]
 |===
 
@@ -131,3 +131,11 @@ AWS security groups provide security at the protocol and port access level; they
 |`19531`
 
 |===
+
+[id="rosa-security-groups-custom_{context}"]
+=== Additional custom security groups
+When you create a cluster using an existing non-managed VPC, you can add additional custom security groups during cluster creation. Custom security groups are subject to the following limitations:
+
+* You must create the custom security groups in AWS before you create the cluster. For more information, see link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-security-groups.html[Amazon EC2 security groups for Linux instances].
+* You must associate the custom security groups with the VPC that the cluster will be installed into. Your custom security groups cannot be associated with another VPC.
+* You might need to request additional quota for your VPC if you are adding additional custom security groups. For information on AWS quota requirements for ROSA, see _Required AWS service quotas_ in _Prepare your environment_. For information on requesting an AWS quota increase, see link:https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html[Requesting a quota increase].

modules/rosa-create-objects.adoc

@@ -116,15 +116,15 @@ $ rosa create cluster --cluster-name=<cluster_name> [arguments]
 |===
 |Option |Definition
 
+|--additional-compute-security-group-ids <sec_group_id>
+|The identifier of one or more additional security groups to use in addition to the default security groups. For more information on additional security groups, see the requirements for _Security groups_ in _Prepare your environment_.
+
 a|--cluster-name <cluster_name>
 |Required. The name of the cluster. When used with the `create cluster` command, this argument is used to set the cluster name and to generate a sub-domain for your cluster on `openshiftapps.com`. The value for this argument must be unique within your organization.
 
 |--compute-machine-type <instance_type>
 |The instance type for compute nodes in the cluster. This determines the amount of memory and vCPU that is allocated to each compute node. For more information on valid instance types, see _AWS Instance types_ in _ROSA service definition_.
 
-|--compute-nodes n
-|The number of worker nodes to provision per availability zone. Single-zone clusters require at least 2 nodes. Multi-zone clusters require at least 3 nodes. Default: `2` for single-zone clusters; `3` for multi-zone clusters.
-
 |--controlplane-iam-role <arn>
 |The ARN of the IAM role to attach to control plane instances.
 
@@ -180,6 +180,9 @@ OVN-Kubernetes, the default network provider in ROSA 4.11 and later, uses the `1
 |--region <region_name>
 |The name of the AWS region where your worker pool will be located, for example, `us-east-1`. This argument overrides the `AWS_REGION` environment variable.
 
+|--replicas n
+|The number of worker nodes to provision per availability zone. Single-zone clusters require at least 2 nodes. Multi-zone clusters require at least 3 nodes. Default: `2` for single-zone clusters; `3` for multi-zone clusters.
+
 |--role-arn <arn>
 |The ARN of the installer role that {cluster-manager} uses to create the cluster. This is required if you have not already created account roles.
 
@@ -500,6 +503,10 @@ $ rosa create machinepool --cluster=<cluster_name> | <cluster_id> --replicas=<nu
 |===
 |Option |Definition
 
+// Note for writers: This command works the same way as rosa create --additional-compute-security-group-ids but all subsequent machinepools are compute only so we don't specify compute here yet; consistency across commands to come in OCM-3111.
+|--additional-security-group-ids <sec_group_id>
+|The identifier of one or more additional security groups to use in addition to the default security groups for this machine pool. For more information on additional security groups, see the requirements for _Security groups_ in _Prepare your environment_.
+
 a|--cluster <cluster_name>\|<cluster_id>
 |Required: The name or ID of the cluster to which the machine pool will be added.
 

modules/rosa-enabling-autoscaling-nodes.adoc

@@ -25,9 +25,9 @@ $ rosa list machinepools --cluster=<cluster_name>
 +
 [source,terminal]
 ----
-ID        AUTOSCALING   REPLICAS    INSTANCE TYPE  LABELS    TINTS   AVAILABILITY ZONES
-default   No            2           m5.xlarge                        us-east-1a
-mp1       No            2           m5.xlarge                        us-east-1a
+ID        AUTOSCALING   REPLICAS    INSTANCE TYPE  LABELS    TAINTS   AVAILABILITY ZONES    DISK SIZE   SG IDs
+default   No            2           m5.xlarge                         us-east-1a            300GiB      sg-0e375ff0ec4a6cfa2
+mp1       No            2           m5.xlarge                         us-east-1a            300GiB      sg-0e375ff0ec4a6cfa2
 ----
 +
 . Get the ID of the machine pools that you want to configure.