Skip to content

Commit 7198bfe

Browse files
EricPonvelleEricPonvelle
committed
OSDOSC-6528: Created documentation for creating a shared VPC
1 parent 246fa7b commit 7198bfe

File tree

6 files changed

+216
-0
lines changed

6 files changed

+216
-0
lines changed

‎_topic_maps/_topic_map_rosa.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -437,6 +437,8 @@ Topics:
437437
File: route-configuration
438438
- Name: Secured routes
439439
File: secured-routes
440+
- Name: Configuring a shared virtual private cloud for ROSA clusters
441+
File: rosa-shared-vpc-config
440442
---
441443
Name: Application development
442444
Dir: applications

‎modules/rosa-sharing-vpc-cluster-creation.adoc‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/rosa-shared-vpc-config.adoc
4+
:_content-type: PROCEDURE
5+
[id="rosa-sharing-vpc-cluster-creation_{context}"]
6+
= Creating your cluster in a shared VPC
7+
To create a cluster in a shared VPC, complete the following step.
8+
9+
[NOTE]
10+
====
11+
Installing a cluster in a shared VPC is supported only for OpenShift 4.13.9 and later.
12+
====
13+
14+
.Procedure
15+
* In a terminal, the *cluster-creating AWS account* user enters the following command to create the cluster in the shared VPC:
16+
17+
[source,terminal]
18+
----
19+
rosa create cluster --cluster-name <cluster_name> --sts --operator-roles-prefix <prefix> --oidc-config-id <oidc_config_id> --region us-east-1 --subnet-ids <subnet_ids> --private-hosted-zone-id <hosted_zone_ID> --shared-vpc-role-arn <vpc-role-arn> --base-domain <dns-domain>
20+
----
21+
22+
[IMPORTANT]
23+
====
24+
After you delete a shared-VPC cluster, three DNS records will not be removed from the private hosted zone. If you make any subsequent install attempts by using the same values, installation errors will occur.
25+
26+
This issue might also manifest when shared-VPC networking prerequisites are not correctly configured. See this article for more information link:https://access.redhat.com/articles/7031016[on this limitation].
27+
====

‎modules/rosa-sharing-vpc-creation-and-sharing.adoc‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/rosa-shared-vpc-config.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="rosa-sharing-vpc-creation-and-sharing_{context}"]
7+
= Configuring a VPC to share within your AWS organization
8+
9+
You can share subnets within a configured VPC with another AWS user account if that account is within your current AWS organization.
10+
11+
.Procedure
12+
13+
. From the AWS account that centrally manages your VPC, create or modify a VPC to your specifications in the link:https://us-east-1.console.aws.amazon.com/vpc/[VPC section of the AWS console]. This AWS account will be the *VPC-owning AWS account*.
14+
. In the link:https://us-east-1.console.aws.amazon.com/iamv2/[Identity and Access Management (IAM) section of the AWS console], create a custom trust policy role for the shared VPC permissions. This role needs to have the following permissions:
15+
* A trust policy to assume roles:
16+
+
17+
[source,terminal]
18+
----
19+
{
20+
"Version": "2012-10-17",
21+
"Statement": [
22+
{
23+
"Sid": "Statement1",
24+
"Effect": "Allow",
25+
"Principal": {
26+
"AWS": "arn:aws:iam::<Account-ID>:root"
27+
}, <1>
28+
"Action": "sts:AssumeRole"
29+
}
30+
]
31+
}
32+
----
33+
+
34+
--
35+
<1> The following principals are be added later in this process after the *cluster-creating AWS account* user has created these roles. On creation, you must create a root user placeholder by using the *cluster-creator's AWS Account* ID as `arn:aws:iam::{Account}:root`.
36+
--
37+
* The `ResourceGroupandTagEditorFullAccess` permissions policy
38+
* The `Route53minimalPermissions` permissions policy
39+
+
40+
After you create this IAM role, provide the created role's ARN to the cluster creator.
41+
42+
. In the link:https://us-east-1.console.aws.amazon.com/ram/[Resource Access Manager of the AWS console], create a Resource Share that shares the previously created public and private subnets to the *cluster-creating AWS account* ID.
43+
44+
After you create the Resource Share, notify the *cluster-creating AWS account* user to reserve an `openshiftapps.com` DNS domain and create Operator roles to continue configuration.

‎modules/rosa-sharing-vpc-dns-and-roles.adoc‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/rosa-shared-vpc-config.adoc
4+
:_content-type: PROCEDURE
5+
[id="rosa-sharing-vpc-dns-and-roles_{context}"]
6+
= Creating your DNS and cluster creation roles
7+
8+
After the *VPC-owning AWS account* user creates a virtual private cloud, subnets, and an IAM role for sharing the VPC resources, the *cluster-creating AWS account* user must reserve an `openshiftapps.com` DNS domain and create Operator roles to communicate back to the *VPC-owning AWS account*.
9+
10+
.Prerequisites
11+
12+
* You have the ARN for the IAM role that is used to share your VPC.
13+
14+
.Procedure
15+
16+
. The cluster creator reserves an `openshiftapps.com` DNS domain with the following command:
17+
+
18+
[source,terminal]
19+
----
20+
$ rosa create dns-domain
21+
----
22+
+
23+
The command creates a reserved `openshiftapps.com` DNS domain.
24+
+
25+
[source,terminal]
26+
----
27+
I: DNS domain '14eo.p1.openshiftapps.com' has been created.
28+
I: To view all DNS domains, run 'rosa list dns-domains'
29+
----
30+
. After creating the DNS domain, the *cluster-creating AWS account* user needs to create an OIDC configuration. Review this article for more information link:https://access.redhat.com/articles/7031018[on the ODIC configuration process]. The following command produces the OIDC config ID that you need:
31+
+
32+
[source,terminal]
33+
----
34+
$ rosa create oidc-config
35+
----
36+
+
37+
You receive confirmation that the command created an OIDC configuration.
38+
+
39+
[source,terminal]
40+
----
41+
I: To create Operator Roles for this OIDC Configuration, run the following command and remember to replace <user-defined> with a prefix of your choice:
42+
rosa create operator-roles --prefix <user-defined> --oidc-config-id 25tu67hq45rto1am3slpf5lq6jargg
43+
----
44+
. After the OIDC configuration is created, create the Operator roles by entering the following command:
45+
+
46+
[source,terminal]
47+
----
48+
$ rosa create operator-roles --oidc-config-id <oidc-config-ID> <1>
49+
--installer-role-arn <Installer_Role> <2>
50+
--shared-vpc-role-arn <Created_VPC_Role_Arn> <3>
51+
--prefix <operator-prefix> <4>
52+
----
53+
+
54+
--
55+
<1> Provide the OIDC configuration ID that you created in the previous step.
56+
<2> Provide the cluster creator's installer ARN that was created as part of the `rosa create account-roles` process.
57+
<3> Provide the ARN for the role that the *VPC-owning AWS account* created.
58+
<4> Provide a prefix for the Operator roles.
59+
--
60+
+
61+
[NOTE]
62+
====
63+
The Installer account role and the shared VPC role must have a one-to-one relationship. If you want to create multiple shared VPC roles, you should create one set of account roles per shared VPC role.
64+
====
65+
66+
After you create the Operator roles, share the full domain name, which is created with `<intended_cluster_name>.<created_dns_domain>`, your _Ingress Operator Cloud Credentials_ and _Installer_ roles' ARN with the *VPC-owning AWS account* user.
67+
68+
This information resembles these examples:
69+
70+
* ``my-rosa-cluster.14eo.p1.openshiftapps.com``
71+
* ``arn:aws:iam::111122223333:role/ManagedOpenShift-Installer-Role``
72+
* ``arn:aws:iam::111122223333:role/my-rosa-cluster-openshift-ingress-operator-cloud-credentials``

‎modules/rosa-sharing-vpc-hosted-zones.adoc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/rosa-shared-vpc-config.adoc
4+
:_content-type: PROCEDURE
5+
[id="rosa-sharing-vpc-hosted-zones_{context}"]
6+
= Updating the shared VPC role and creating hosted zones
7+
8+
After the *cluster-creating AWS account* user provides the DNS domain and the IAM roles, *the VPC-owning AWS account* user must create a private hosted zone and update the trust policy on the IAM role that was created for sharing the VPC.
9+
10+
.Procedure
11+
12+
. The *VPC-owning AWS account* user who owns the VPC must update the VPC sharing IAM role and add the _Installer_ and _Ingress Operator Cloud Credentials_ roles to the principal section of the trust policy.
13+
+
14+
[source,terminal]
15+
----
16+
{
17+
"Version": "2012-10-17",
18+
"Statement": [
19+
{
20+
"Sid": "Statement1",
21+
"Effect": "Allow",
22+
"Principal": {
23+
"AWS": [
24+
"arn:aws:iam::<Cluster-Creator's-AWS-Account-ID>:role/<prefix>-ingress-operator-cloud-credentials",
25+
"arn:aws:iam::<Cluster-Creator's-AWS-Account-ID>:role/<prefix>-Installer-Role"
26+
]
27+
},
28+
"Action": "sts:AssumeRole"
29+
}
30+
]
31+
}
32+
----
33+
. After updating the trust policy, the *VPC-owning AWS account* user creates a private hosted zone in the link:https://us-east-1.console.aws.amazon.com/route53/v2/[Route 53 section of the AWS console]. In the hosted zone configuration, the domain name is `<cluster-name>.<dns_domain>`. The private hosted zone must be associated with the created VPC.
34+
. After the hosted zone is created and associated with the VPC, provide the following to the *cluster-creating AWS account* user:
35+
* Hosted zone ID
36+
* AWS region
37+
* Intended subnet IDs

‎networking/rosa-shared-vpc-config.adoc‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
include::_attributes/attributes-openshift-dedicated.adoc[]
2+
[id="rosa-shared-vpc-config"]
3+
= Configuring a shared virtual private cloud for ROSA clusters
4+
:context: rosa-shared-vpc-config
5+
6+
toc::[]
7+
8+
You can create {product-title} clusters in shared, centrally-managed AWS virtual private clouds (VPCs). This process requires two separate AWS accounts that belong to the same AWS organization. One account functions as the VPC owner while the other account creates the cluster in this VPC.
9+
10+
.Prerequisites
11+
* You installed the ROSA CLI (`rosa`) 1.2.26 or later.
12+
* You created all of the required ROSA account roles for creating a cluster.
13+
* You have an AWS account with the proper permissions to create roles and share resources.
14+
* You are using an AWS account to create your cluster ("*cluster-creating AWS account*") that is separate from the AWS account that creates your VPC ("*VPC-owning AWS account*").
15+
* Both AWS accounts belong to the same AWS organization.
16+
* You enabled resource sharing from the management account for your organization.
17+
* You have access to the link:https://signin.aws.amazon.com[AWS console].
18+
19+
[NOTE]
20+
====
21+
Installing a cluster in a shared VPC is supported only for OpenShift 4.13.9 and later.
22+
====
23+
24+
include::modules/rosa-sharing-vpc-creation-and-sharing.adoc[leveloffset=+1]
25+
26+
[role="_additional-resources"]
27+
[id="additional-resources_shared-vpc_vpc-creation"]
28+
[discrete]
29+
=== Additional resources
30+
* See the AWS documentation for link:https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html[sharing your AWS resources].
31+
32+
include::modules/rosa-sharing-vpc-dns-and-roles.adoc[leveloffset=+1]
33+
include::modules/rosa-sharing-vpc-hosted-zones.adoc[leveloffset=+1]
34+
include::modules/rosa-sharing-vpc-cluster-creation.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)