From 90e44d1466cda3f9b0b5439cbe046317666a6f04 Mon Sep 17 00:00:00 2001 From: EricPonvelle Date: Mon, 7 Apr 2025 14:56:07 -0400 Subject: [PATCH] OSDOCS-13576: Added info on rosa create network command --- modules/rosa-create-objects.adoc | 26 ++++++ modules/rosa-hcp-create-network.adoc | 92 +++++++++++++++++++ ...hcp-creating-cluster-with-aws-kms-key.adoc | 25 ++++- .../rosa-hcp-egress-lockdown-install.adoc | 45 +++++++-- rosa_hcp/rosa-hcp-quickstart-guide.adoc | 31 ++++++- ...sa-hcp-sts-creating-a-cluster-quickly.adoc | 24 ++--- snippets/vpc-troubleshooting.adoc | 23 +++++ 7 files changed, 241 insertions(+), 25 deletions(-) create mode 100644 modules/rosa-hcp-create-network.adoc create mode 100644 snippets/vpc-troubleshooting.adoc diff --git a/modules/rosa-create-objects.adoc b/modules/rosa-create-objects.adoc index 4c888f4fa9..f321828c6b 100644 --- a/modules/rosa-create-objects.adoc +++ b/modules/rosa-create-objects.adoc @@ -932,6 +932,32 @@ Create a basic network with regular arguments and flags. $ rosa create network rosa-quickstart-default-vpc --param Tags=key1=value1,key2=value2 --param Name=example-stack --param Region=us-west-2 ---- +* The full list of parameters is available in the default template. ++ +.Example template ++ +[source,yaml] +---- +Parameters: + AvailabilityZoneCount: + Type: Number + Description: "Number of Availability Zones to use" + Default: 1 + MinValue: 1 + MaxValue: 3 + Region: + Type: String + Description: "AWS Region" + Default: "us-west-2" + Name: + Type: String + Description: "Name prefix for resources" + VpcCidr: + Type: String + Description: CIDR block for the VPC + Default: '10.0.0.0/16' +---- + [id="rosa-create-ocm-role_{context}"] == create ocm-role diff --git a/modules/rosa-hcp-create-network.adoc b/modules/rosa-hcp-create-network.adoc new file mode 100644 index 0000000000..eec633b16f --- /dev/null +++ b/modules/rosa-hcp-create-network.adoc @@ -0,0 +1,92 @@ +// Module included in the following assemblies: +// +// * rosa_hcp/rosa-hcp-creating-cluster-with-aws-kms-key.adoc +// * rosa_hcp/rosa-hcp-egress-lockdown-install.adoc +// * rosa_hcp/rosa-hcp-quickstart-guide.adoc +// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc + +ifeval::["{context}" == "rosa-hcp-egress-lockdown-install"] +:egress-lockdown-rosa: +endif::[] + +:_mod-docs-content-type: PROCEDURE +[id="rosa-hcp-create-network_{context}"] += Creating a Virtual Private Cloud using the ROSA CLI + +The `rosa create network` command is available in v.1.2.48 or later of the ROSA command-line interface (CLI). The command uses AWS CloudFormation to create a VPC and the other networking components used to install a ROSA cluster. CloudFormation is a native AWS infrastructure-as-code tool and is compatible with the AWS CLI. + +If you do not specify a template, CloudFormation uses a default template that creates the following parameters: + +[cols="2a,3a",options="header"] +|=== +|VPC parameter +|Value + +| Availability zones +| 1 + +| Region +| `us-east-1` + +| VPC CIDR +| `10.0.0.0/16` +|=== + +You can create and customize CloudFormation templates to use with the `rosa create network` command. See the additional resources of this section for information on the default VPC template. + +.Prerequisites + +* You have configured your AWS account +* You have configured your Red Hat accounts +* You have installed the ROSA CLI and configured it to the latest version + +.Procedure +. Create an AWS VPC using the default CloudFormations template by running the following command: ++ +[source,terminal] +---- +$ rosa create network +---- + +. Optional: Customize your VPC by specifying additional parameters. ++ +You can use the `--param` flag to specify changes to the default VPC template. The following example command specifies custom values for `region`, `Name`, `AvailabilityZoneCount` and `VpcCidr`. ++ +[source,terminal] +---- +$ rosa create network --param Region=us-east-2 --param Name=quickstart-stack --param AvailabilityZoneCount=3 --param VpcCidr=10.0.0.0/16 +---- ++ +The command takes about 5 minutes to run and provides regular status updates from AWS as resources are created. If there is an issue with CloudFormation, a rollback is attempted. For all other errors that are encountered, please follow the error message instructions or contact AWS support. + +.Verification +* When completed, you receive a summary of the created resources: ++ +[source,bash] +---- +INFO[0140] Resources created in stack: +INFO[0140] Resource: AttachGateway, Type: AWS::EC2::VPCGatewayAttachment, ID: +INFO[0140] Resource: EC2VPCEndpoint, Type: AWS::EC2::VPCEndpoint, ID: +INFO[0140] Resource: EcrApiVPCEndpoint, Type: AWS::EC2::VPCEndpoint, ID: +INFO[0140] Resource: EcrDkrVPCEndpoint, Type: AWS::EC2::VPCEndpoint, ID: +INFO[0140] Resource: ElasticIP1, Type: AWS::EC2::EIP, ID: +INFO[0140] Resource: ElasticIP2, Type: AWS::EC2::EIP, ID: +INFO[0140] Resource: InternetGateway, Type: AWS::EC2::InternetGateway, ID: igw-016e1a71b9812464e +INFO[0140] Resource: KMSVPCEndpoint, Type: AWS::EC2::VPCEndpoint, ID: +INFO[0140] Resource: NATGateway1, Type: AWS::EC2::NatGateway, ID: +INFO[0140] Resource: PrivateRoute, Type: AWS::EC2::Route, ID: +INFO[0140] Resource: PrivateRouteTable, Type: AWS::EC2::RouteTable, ID: +INFO[0140] Resource: PrivateSubnetRouteTableAssociation1, Type: AWS::EC2::SubnetRouteTableAssociation, ID: +INFO[0140] Resource: PublicRoute, Type: AWS::EC2::Route, ID: +INFO[0140] Resource: PublicRouteTable, Type: AWS::EC2::RouteTable, ID: +INFO[0140] Resource: PublicSubnetRouteTableAssociation1, Type: AWS::EC2::SubnetRouteTableAssociation, ID: +INFO[0140] Resource: S3VPCEndpoint, Type: AWS::EC2::VPCEndpoint, ID: +INFO[0140] Resource: STSVPCEndpoint, Type: AWS::EC2::VPCEndpoint, ID: +INFO[0140] Resource: SecurityGroup, Type: AWS::EC2::SecurityGroup, ID: +INFO[0140] Resource: SubnetPrivate1, Type: AWS::EC2::Subnet, ID: \ <1> +INFO[0140] Resource: SubnetPublic1, Type: AWS::EC2::Subnet, ID: \ <1> +INFO[0140] Resource: VPC, Type: AWS::EC2::VPC, ID: +INFO[0140] Stack rosa-network-stack-5555 created \ <2> +---- +<1> These two subnet IDs are used to create your cluster when using the `rosa create cluster` command. +<2> The network stack name is used to delete the resource later. \ No newline at end of file diff --git a/rosa_hcp/rosa-hcp-creating-cluster-with-aws-kms-key.adoc b/rosa_hcp/rosa-hcp-creating-cluster-with-aws-kms-key.adoc index e04f39e5a2..83b44419e0 100644 --- a/rosa_hcp/rosa-hcp-creating-cluster-with-aws-kms-key.adoc +++ b/rosa_hcp/rosa-hcp-creating-cluster-with-aws-kms-key.adoc @@ -22,10 +22,11 @@ To create a {hcp-title} cluster, you must have the following items: * Operator roles [id="rosa-hcp-creating-cluster-with-aws-kms-key-creating-vpc"] -=== Creating a Virtual Private Cloud for your {hcp-title} clusters +== Creating a Virtual Private Cloud for your {hcp-title} clusters -You must have a Virtual Private Cloud (VPC) to create {hcp-title} cluster. You can use the following methods to create a VPC: +You must have a Virtual Private Cloud (VPC) to create {hcp-title} cluster. Use one of the following methods to create a VPC: +* Create a VPC using the ROSA command-line interface (CLI) * Create a VPC by using a Terraform template * Manually create the VPC resources in the AWS console @@ -34,24 +35,40 @@ You must have a Virtual Private Cloud (VPC) to create {hcp-title} cluster. You c The Terraform instructions are for testing and demonstration purposes. Your own installation requires some modifications to the VPC for your own use. You should also ensure that when you use this Terraform script it is in the same region that you intend to install your cluster. In these examples, use `us-east-2`. ==== -include::snippets/imp-rosa-hcp-no-shared-vpc-support.adoc[leveloffset=+0] +[discrete] +include::modules/rosa-hcp-create-network.adoc[leveloffset=+3] + +[role="_additional-resources"] +[id="additional-resources_rosa-hcp-create-network-kms-key"] +.Additional resources + +* See the link:https://aws.amazon.com/cloudformation/[AWS CloudFormation] for more information about structuring CloudFormation files to create VPCs. +* See the link:https://github.com/openshift/rosa/blob/master/cmd/create/network/templates/rosa-quickstart-default-vpc/cloudformation.yaml[default VPC AWS CloudFormation template] for more information. [discrete] include::modules/rosa-hcp-vpc-terraform.adoc[leveloffset=+3] [role="_additional-resources"] +[id="additional-resources_rosa-hcp-vpc-terraform-kms-key"] .Additional resources * See the link:https://github.com/openshift-cs/terraform-vpc-example[Terraform VPC] repository for a detailed list of all options available when customizing the VPC for your needs. [discrete] -include::modules/rosa-hcp-vpc-manual.adoc[leveloffset=+3] +include::modules/rosa-hcp-vpc-manual.adoc[leveloffset=+2] + +include::snippets/vpc-troubleshooting.adoc[leveloffset=+2] + +[discrete] +include::modules/rosa-hcp-vpc-subnet-tagging.adoc[leveloffset=+3] [role="_additional-resources"] +[id="additional-resources_rosa-hcp-vpc-aws-kms-key"] .Additional resources * link:https://docs.aws.amazon.com/vpc/latest/userguide/vpc-getting-started.html[Get Started with Amazon VPC] * link:https://developer.hashicorp.com/terraform[HashiCorp Terraform documentation] +* link:https://kubernetes-sigs.github.io/aws-load-balancer-controller/v2.2/deploy/subnet_discovery/[Subnet Auto Discovery] include::modules/rosa-hcp-creating-account-wide-sts-roles-and-policies.adoc[leveloffset=+2] diff --git a/rosa_hcp/rosa-hcp-egress-lockdown-install.adoc b/rosa_hcp/rosa-hcp-egress-lockdown-install.adoc index 3b7d76a58c..1ba5e745b7 100644 --- a/rosa_hcp/rosa-hcp-egress-lockdown-install.adoc +++ b/rosa_hcp/rosa-hcp-egress-lockdown-install.adoc @@ -51,28 +51,59 @@ While you may install and upgrade your clusters as you would a regular cluster, ==== [id="rosa-hcp-egress-lockdown-install-creating_{context}"] -== Creating a Virtual Private Cloud for your egress lockdown {hcp-title} clusters +== Creating a Virtual Private Cloud for your {hcp-title} clusters -You must have a Virtual Private Cloud (VPC) to create {hcp-title} clusters. You can use one of the following methods to create a VPC: +You must have a Virtual Private Cloud (VPC) to create a {hcp-title} cluster. Use one of the following methods to create a VPC: +* Create a VPC using the ROSA command-line interface (CLI) * Create a VPC by using a Terraform template * Manually create the VPC resources in the AWS console [NOTE] ==== -The Terraform instructions are for testing and demonstration purposes. Your own installation requires modifications to the VPC for your specific needs and constraints. You should also ensure that when you use the following Terraform script it is in the same region that you intend to install your cluster. +The Terraform instructions are for testing and demonstration purposes. Your own installation requires some modifications to the VPC for your own use. You should also ensure that when you use this Terraform script it is in the same region that you intend to install your cluster. In these examples, use `us-east-2`. ==== -include::modules/rosa-hcp-vpc-terraform.adoc[leveloffset=+2] +[discrete] +include::modules/rosa-hcp-create-network.adoc[leveloffset=+3] + +[role="_additional-resources"] +[id="additional-resources_rosa-hcp-create-network-egress-lockdown"] +.Additional resources + +* See the link:https://aws.amazon.com/cloudformation/[AWS CloudFormation documentation] for more information about structuring CloudFormation files to create VPCs. +* See the link:https://github.com/openshift/rosa/blob/master/cmd/create/network/templates/rosa-quickstart-default-vpc/cloudformation.yaml[default VPC AWS CloudFormation template] for more information. + +[discrete] +include::modules/rosa-hcp-vpc-terraform.adoc[leveloffset=+3] + +[role="_additional-resources"] +[id="additional-resources_rosa-hcp-vpc-terraform-egress-lockdown"] +.Additional resources + +* See the link:https://github.com/openshift-cs/terraform-vpc-example[Terraform VPC] repository for a detailed list of all options available when customizing the VPC to your needs. + +[discrete] +include::modules/rosa-hcp-vpc-manual.adoc[leveloffset=+2] + +include::snippets/vpc-troubleshooting.adoc[leveloffset=+2] + +[discrete] +include::modules/rosa-hcp-vpc-subnet-tagging.adoc[leveloffset=+3] + +[role="_additional-resources"] +[id="additional-resources_rosa-hcp-vpc-aws-egress-lockdown"] +.Additional resources + +* link:https://docs.aws.amazon.com/vpc/latest/userguide/vpc-getting-started.html[Get Started with Amazon VPC] +* link:https://developer.hashicorp.com/terraform[HashiCorp Terraform documentation] +* link:https://kubernetes-sigs.github.io/aws-load-balancer-controller/v2.2/deploy/subnet_discovery/[Subnet Auto Discovery] [role="_additional-resources"] .Additional resources * See the link:https://github.com/openshift-cs/terraform-vpc-example/tree/main/zero-egress[Zero Egress Terraform VPC Example] repository for a detailed list of all options available when customizing the VPC for your needs. -include::modules/rosa-hcp-vpc-manual.adoc[leveloffset=+2] -[discrete] -include::modules/rosa-hcp-vpc-subnet-tagging.adoc[leveloffset=+3] [discrete] include::modules/rosa-hcp-sgs-and-vpce.adoc[leveloffset=+3] diff --git a/rosa_hcp/rosa-hcp-quickstart-guide.adoc b/rosa_hcp/rosa-hcp-quickstart-guide.adoc index 199654f113..a4b002af65 100644 --- a/rosa_hcp/rosa-hcp-quickstart-guide.adoc +++ b/rosa_hcp/rosa-hcp-quickstart-guide.adoc @@ -28,6 +28,7 @@ include::modules/rosa-sts-creating-account-wide-sts-roles-and-policies.adoc[leve You must have a Virtual Private Cloud (VPC) to create {hcp-title} cluster. You can use the following methods to create a VPC: +* Create a VPC using the ROSA CLI * Create a VPC by using a Terraform template * Manually create the VPC resources in the AWS console @@ -37,14 +38,40 @@ The Terraform instructions are for testing and demonstration purposes. Your own ==== [discrete] -include::modules/rosa-hcp-vpc-terraform.adoc[leveloffset=1] +include::modules/rosa-hcp-create-network.adoc[leveloffset=+3] [role="_additional-resources"] -[id="additional-resources_rosa-hcp-quickstart-vpc-terraform"] +[id="additional-resources_rosa-hcp-create-network-quickstart"] +.Additional resources + +* See the link:https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/quickref-ec2-vpc.html[AWS CloudFormation documentation] for more information about structuring CloudFormation files to create VPCs. +* See the link:https://github.com/openshift/rosa/blob/master/cmd/create/network/templates/rosa-quickstart-default-vpc/cloudformation.yaml[default VPC AWS CloudFormation template] for more information. + +[discrete] +include::modules/rosa-hcp-vpc-terraform.adoc[leveloffset=+3] + +[role="_additional-resources"] +[id="additional-resources_rosa-hcp-vpc-terraform-quickstart"] .Additional resources * See the link:https://github.com/openshift-cs/terraform-vpc-example[Terraform VPC] repository for a detailed list of all options available when customizing the VPC for your needs. +[discrete] +include::modules/rosa-hcp-vpc-manual.adoc[leveloffset=+2] + +include::snippets/vpc-troubleshooting.adoc[leveloffset=+2] + +[discrete] +include::modules/rosa-hcp-vpc-subnet-tagging.adoc[leveloffset=+3] + +[role="_additional-resources"] +[id="additional-resources_rosa-hcp-vpc-aws-quickstart"] +.Additional resources + +* link:https://docs.aws.amazon.com/vpc/latest/userguide/vpc-getting-started.html[Get Started with Amazon VPC] +* link:https://developer.hashicorp.com/terraform[HashiCorp Terraform documentation] +* link:https://kubernetes-sigs.github.io/aws-load-balancer-controller/v2.2/deploy/subnet_discovery/[Subnet Auto Discovery] + include::modules/rosa-sts-byo-oidc.adoc[leveloffset=+1] include::modules/rosa-operator-config.adoc[leveloffset=+1] include::modules/rosa-hcp-sts-creating-a-cluster-cli.adoc[leveloffset=+1] diff --git a/rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc b/rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc index 0960b00312..46d2d29c1a 100644 --- a/rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc +++ b/rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc @@ -73,6 +73,7 @@ To create a {hcp-title} cluster, you must have the following items: You must have a Virtual Private Cloud (VPC) to create {hcp-title} cluster. You can use the following methods to create a VPC: +* Create a VPC using the ROSA CLI * Create a VPC by using a Terraform template * Manually create the VPC resources in the AWS console @@ -81,6 +82,16 @@ You must have a Virtual Private Cloud (VPC) to create {hcp-title} cluster. You c The Terraform instructions are for testing and demonstration purposes. Your own installation requires some modifications to the VPC for your own use. You should also ensure that when you use this Terraform script it is in the same region that you intend to install your cluster. In these examples, use `us-east-2`. ==== +[discrete] +include::modules/rosa-hcp-create-network.adoc[leveloffset=+3] + +[role="_additional-resources"] +[id="additional-resources_rosa-hcp-create-network"] +.Additional resources + +* See the link:https://aws.amazon.com/cloudformation/[AWS CloudFormation documentation] for more information about structuring CloudFormation files to create VPCs. +* See the link:https://github.com/openshift/rosa/blob/master/cmd/create/network/templates/rosa-quickstart-default-vpc/cloudformation.yaml[default VPC AWS CloudFormation template] for more information. + [discrete] include::modules/rosa-hcp-vpc-terraform.adoc[leveloffset=+3] @@ -93,18 +104,7 @@ include::modules/rosa-hcp-vpc-terraform.adoc[leveloffset=+3] [discrete] include::modules/rosa-hcp-vpc-manual.adoc[leveloffset=+2] -[id="troubleshooting_shared-vpc-hcp_vpc-creation"] -==== Troubleshooting - -If your cluster fails to install, check these common troubleshooting issues: - -* Make sure your link:https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html[DHCP option set] includes a domain name, and ensure that the domain name does not include any spaces or capital letters. -* If your VPC uses a custom DNS resolver (the `domain name servers` field of your DHCP option set is not `AmazonProvideDNS`), make sure it is able to properly resolve the private hosted zones configured in Route53. - -For more information about troubleshooting ROSA cluster installations, see xref:../support/troubleshooting/rosa-troubleshooting-installations.adoc#rosa-troubleshooting-installations[Troubleshooting {product-title} installations]. - -===== Get support -If you need additional xref:../support/getting-support.adoc#getting-support[support], visit the Red Hat Customer Portal to review knowledge base articles, submit a support case, and review additional product documentation and resources. +include::snippets/vpc-troubleshooting.adoc[leveloffset=+2] [discrete] include::modules/rosa-hcp-vpc-subnet-tagging.adoc[leveloffset=+3] diff --git a/snippets/vpc-troubleshooting.adoc b/snippets/vpc-troubleshooting.adoc new file mode 100644 index 0000000000..507aed2c22 --- /dev/null +++ b/snippets/vpc-troubleshooting.adoc @@ -0,0 +1,23 @@ +// Snippet included in the following assemblies: +// +// * rosa_hcp/rosa-hcp-creating-cluster-with-aws-kms-key.adoc +// * rosa_hcp/rosa-hcp-egress-lockdown-install.adoc +// * rosa_hcp/rosa-hcp-quickstart-guide.adoc +// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc + +:_mod-docs-content-type: SNIPPET + +[id="troubleshooting_shared-vpc-hcp_vpc-creation_{context}"] += Troubleshooting + +If your cluster fails to install, troubleshoot these common issues: + +* Make sure your link:https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html[DHCP option set] includes a domain name, and ensure that the domain name does not include any spaces or capital letters. +* If your VPC uses a custom DNS resolver (the `domain name servers` field of your DHCP option set is not `AmazonProvideDNS`), make sure it is able to properly resolve the private hosted zones configured in Route53. + +For more information about troubleshooting ROSA cluster installations, see xref:../support/troubleshooting/rosa-troubleshooting-installations.adoc#rosa-troubleshooting-installations[Troubleshooting {product-title} installations]. + +[discrete] +[id="troubleshooting_vpc-support_{context}"] +== Get support +If you need additional xref:../support/getting-support.adoc#getting-support[support], visit the Red Hat Customer Portal to review knowledge base articles, submit a support case, and review additional product documentation and resources. \ No newline at end of file