Skip to content

Commit 39a5583

Browse files
EricPonvelleEricPonvelle
committed
OSDOCS-7235: Porting Terraform information
1 parent 00546f4 commit 39a5583

File tree

4 files changed

+401
-0
lines changed

4 files changed

+401
-0
lines changed

‎_topic_maps/_topic_map_rosa.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,8 @@ Topics:
140140
File: rosa-sts-required-aws-service-quotas
141141
- Name: Setting up your environment
142142
File: rosa-sts-setting-up-environment
143+
- Name: Preparing Terraform to install ROSA clusters
144+
File: rosa-understanding-terraform
143145
---
144146
Name: Install ROSA with HCP clusters
145147
Dir: rosa_hcp

‎modules/rosa-sts-account-roles-terraform.adoc

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * rosa_planning/rosa-understanding-terraform.adoc
4+
ifeval::["{context}" == "rosa-understanding-terraform"]
5+
:tf-full:
6+
endif::[]
7+
:_content-type: PROCEDURE
8+
9+
[id="sd-terraform-account-roles_{context}"]
10+
ifdef::tf-full[]
11+
= Account roles Terraform example
12+
endif::tf-full[]
13+
ifndef::tf-full[]
14+
= Creating your account-wide IAM roles with Terraform
15+
endif::tf-full[]
16+
17+
The following example shows how Terraform can be used to create your Amazon Web Services (AWS) Identity and Access Management (IAM) account roles for ROSA.
18+
19+
[NOTE]
20+
====
21+
If you want to edit the Terraform files, you can use any text editor. You must re-run the `terraform init` and `terraform apply` commands if you change any values in the files.
22+
====
23+
24+
.Procedure
25+
26+
. Check your AWS account for existing roles and policies by running the following command:
27+
+
28+
[source,terminal]
29+
----
30+
$ rosa list account-roles
31+
----
32+
+
33+
34+
35+
. In your terminal, run the following command to export link:https://console.redhat.com/openshift/token[your {cluster-manager-first} token]. This value must include the full {cluster-manager} token:
36+
+
37+
[source,terminal]
38+
----
39+
$ export RHCS_TOKEN="<your_offline_token>"
40+
----
41+
+
42+
You can verify that your token is saved by running the following command:
43+
+
44+
[source,terminal]
45+
----
46+
$ echo $RHCS_TOKEN
47+
----
48+
+
49+
You see your token in the command line.
50+
51+
. Optional: You can specify your own account-role prefix that prepends the roles you create by running the following command:
52+
+
53+
[NOTE]
54+
====
55+
If you do not specify an account-role prefix, a prefix is generated in the format of `account-role-` followed by a string of four random characters.
56+
====
57+
+
58+
[source,terminal]
59+
----
60+
$ export account_role_prefix=<account_role_prefix>
61+
----
62+
63+
. Create the Terraform files locally by using the following code templates:
64+
+
65+
[NOTE]
66+
====
67+
These files are created in your current directory. Ensure that you are in the directory where you want to run Terraform.
68+
====
69+
70+
.. The `main.tf` file calls the Red Hat Cloud Services Terraform provider, which allows you to use OpenShift services with Terraform. Run the following command to create the `main.tf` file:
71+
+
72+
[source,terminal]
73+
----
74+
$ cat<<-EOF>main.tf
75+
#
76+
# Copyright (c) 2022 Red Hat, Inc.
77+
#
78+
# Licensed under the Apache License, Version 2.0 (the "License");
79+
# you may not use this file except in compliance with the License.
80+
# You may obtain a copy of the License at
81+
#
82+
# http://www.apache.org/licenses/LICENSE-2.0
83+
#
84+
# Unless required by applicable law or agreed to in writing, software
85+
# distributed under the License is distributed on an "AS IS" BASIS,
86+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
87+
# See the License for the specific language governing permissions and
88+
# limitations under the License.
89+
#
90+
91+
terraform {
92+
required_providers {
93+
aws = {
94+
source = "hashicorp/aws"
95+
version = ">= 4.20.0"
96+
}
97+
rhcs = {
98+
version = ">= 1.3.0"
99+
source = "terraform-redhat/rhcs"
100+
}
101+
}
102+
}
103+
104+
data "rhcs_policies" "all_policies" {}
105+
106+
data "rhcs_versions" "all" {}
107+
108+
module "create_account_roles" {
109+
source = "terraform-redhat/rosa-sts/aws"
110+
version = "0.0.15"
111+
112+
create_operator_roles = false
113+
create_oidc_provider = false
114+
create_account_roles = true
115+
116+
account_role_prefix = var.account_role_prefix
117+
rosa_openshift_version = var.openshift_version
118+
account_role_policies = data.rhcs_policies.all_policies.account_role_policies
119+
operator_role_policies = data.rhcs_policies.all_policies.operator_role_policies
120+
all_versions = data.rhcs_versions.all
121+
tags = var.tags
122+
}
123+
EOF
124+
----
125+
126+
.. You define the account role prefix structure in the `output.tf` file. This output definition allows you to specify how the various generated roles are constructed. Run the following command to create your `output.tf` file:
127+
+
128+
[source,terminal]
129+
----
130+
$ cat<<-EOF>output.tf
131+
output "account_role_prefix" {
132+
value = module.create_account_roles.account_role_prefix
133+
}
134+
EOF
135+
----
136+
137+
.. The `variables.tf` allows you to specify values you want for select variables. If you exported a variable for the `account_role_prefix` earlier, leave this variable's default value blank. Setting the variable in both places with different values can produce unexpected results. Run the following command to create your `variables.tf` file:
138+
+
139+
[IMPORTANT]
140+
====
141+
Do not include your {cluster-manager} token in this file if it is not stored in a safe location.
142+
====
143+
+
144+
[source,terminal]
145+
----
146+
$ cat<<-EOF>variables.tf
147+
variable "openshift_version" {
148+
type = string
149+
default = "4.13"
150+
description = "Enter the desired OpenShift version as X.Y. This version should match what you intend for your ROSA cluster. For example, if you plan to create a ROSA cluster using '4.13.10', then this version should be '4.13'. You can see the supported versions of OpenShift by running 'rosa list version'."
151+
}
152+
153+
variable "account_role_prefix" {
154+
type = string
155+
default = ""
156+
description = "Your account roles are prepended with whatever value you enter here. The default value in the ROSA CLI is 'ManagedOpenshift-' before all of your account roles."
157+
}
158+
159+
variable "tags" { <1>
160+
type = map
161+
default = null
162+
description = "(Optional) List of AWS resource tags to apply."
163+
}
164+
EOF
165+
----
166+
+
167+
--
168+
<1> The `tags` parameter uses a map of strings variable. The format that it takes looks like the following example:
169+
+
170+
[source,terraform]
171+
----
172+
variable "tags" {
173+
type = "map"
174+
default = {
175+
"us-east-1" = "image-1234"
176+
"us-west-2" = "image-4567"
177+
}
178+
}
179+
----
180+
--
181+
. In the directory where you saved these Terraform files, run the following command to set up Terraform to create these resources:
182+
+
183+
[source,terminal]
184+
----
185+
$ terraform init
186+
----
187+
. Optional: Run the following command to confirm that the Terraform code you copied is correct:
188+
+
189+
[source,terminal]
190+
----
191+
$ terraform validate
192+
----
193+
+
194+
.Sample output
195+
+
196+
[source,terminal]
197+
----
198+
Success! The configuration is valid.
199+
----
200+
. Optional: Test your Terraform template and create a reusable Terraform plan file by running the following command:
201+
+
202+
[source,terminal]
203+
----
204+
$ terraform plan -out account-roles.tfplan
205+
----
206+
. Run the following command to build your account-wide IAM roles with Terraform:
207+
+
208+
[source,terminal]
209+
----
210+
$ terraform apply "account-roles.tfplan"
211+
----
212+
+
213+
[NOTE]
214+
====
215+
If you used the `terraform plan` command first, you can provide your created `account-roles.tf` file here. Otherwise, Terraform temporarily creates this plan before it applies your desired outcome.
216+
====
217+
218+
.Verification
219+
* Run the following command to verify that your account-roles have been created:
220+
+
221+
[source,terminal]
222+
----
223+
$ rosa list account-roles
224+
----
225+
+
226+
.Sample output
227+
228+
[source,terminal]
229+
----
230+
I: Fetching account roles
231+
ROLE NAME ROLE TYPE ROLE ARN OPENSHIFT VERSION AWS Managed
232+
account-role-6kn4-ControlPlane-Role Control plane arn:aws:iam::269733383066:role/account-role-6kn4-ControlPlane-Role 4.13 No
233+
account-role-6kn4-Installer-Role Installer arn:aws:iam::269733383066:role/account-role-6kn4-Installer-Role 4.13 No
234+
account-role-6kn4-Support-Role Support arn:aws:iam::269733383066:role/account-role-6kn4-Support-Role 4.13 No
235+
account-role-6kn4-Worker-Role Worker arn:aws:iam::269733383066:role/account-role-6kn4-Worker-Role 4.13 No
236+
----
237+
238+
.Clean up
239+
240+
When you are finished using the resources that you created using Terraform, you should purge these resources with the following command:
241+
[source,terminal]
242+
----
243+
$ terraform destroy
244+
----
245+
ifeval::["{context}" == "rosa-understanding-terraform"]
246+
:!tf-full:
247+
endif::[]

‎modules/rosa-sts-terraform-prerequisites.adoc

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * rosa_planning/rosa-understanding-terraform.adoc
4+
ifeval::["{context}" == "rosa-understanding-terraform"]
5+
:tf-full:
6+
endif::[]
7+
8+
:_content-type: CONCEPT
9+
[id="rosa-sts-terraform-prerequisites_{context}"]
10+
ifdef::tf-full[]
11+
= Prerequisites for Terraform
12+
endif::tf-full[]
13+
ifndef::tf-full[]
14+
.Prerequisites
15+
endif::tf-full[]
16+
17+
To use link:https://registry.terraform.io/providers/terraform-redhat/rhcs/latest/docs[the Red Hat Cloud Services provider] inside your Terraform configuration, you must meet the following prerequisites:
18+
19+
* You have installed the {product-title} (ROSA) command-line interface (CLI) tool.
20+
ifdef::tf-full[]
21+
+
22+
See the Additional resources for further installation instructions.
23+
endif::tf-full[]
24+
* You have your offline link:https://console.redhat.com/openshift/token/rosa[{cluster-manager-first} token].
25+
ifdef::tf-full[]
26+
+
27+
This token is generated through the Red Hat Hybrid Cloud Console. It is unique to your account and should not be shared. The token is generated based off your account access and permissions.
28+
endif::tf-full[]
29+
* You have installed link:https://developer.hashicorp.com/terraform/downloads[Terraform version 1.4.6] or newer.
30+
ifdef::tf-full[]
31+
+
32+
You must have Terraform configured for your local system. The Terraform website contains installation options for MacOS, Windows, and Linux.
33+
endif::tf-full[]
34+
ifndef::tf-full[]
35+
* You have created your AWS account-wide IAM roles.
36+
+
37+
The specific account-wide IAM roles and policies provide the STS permissions required for ROSA support, installation, control plane, and compute functionality. This includes account-wide Operator policies. See the Additional resources for more information on the AWS account roles.
38+
endif::tf-full[]
39+
* You have an link:https://aws.amazon.com/free/?all-free-tier[AWS account] and link:https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html[associated credentials] that allow you to create resources. The credentials are configured for the AWS provider. See the link:https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration[Authentication and Configuration] section in AWS Terraform provider documentation.
40+
* You have, at minimum, the following permissions in your AWS IAM role policy that is operating Terraform. Check for these permissions in the AWS console.
41+
+
42+
.Minimum AWS permissions for Terraform
43+
[%collapsible]
44+
====
45+
[source,json]
46+
----
47+
{
48+
"Version": "2012-10-17",
49+
"Statement": [
50+
{
51+
"Sid": "VisualEditor0",
52+
"Effect": "Allow",
53+
"Action": [
54+
"iam:GetPolicyVersion",
55+
"iam:DeletePolicyVersion",
56+
"iam:CreatePolicyVersion",
57+
"iam:UpdateAssumeRolePolicy",
58+
"secretsmanager:DescribeSecret",
59+
"iam:ListRoleTags",
60+
"secretsmanager:PutSecretValue",
61+
"secretsmanager:CreateSecret",
62+
"iam:TagRole",
63+
"secretsmanager:DeleteSecret",
64+
"iam:UpdateOpenIDConnectProviderThumbprint",
65+
"iam:DeletePolicy",
66+
"iam:CreateRole",
67+
"iam:AttachRolePolicy",
68+
"iam:ListInstanceProfilesForRole",
69+
"secretsmanager:GetSecretValue",
70+
"iam:DetachRolePolicy",
71+
"iam:ListAttachedRolePolicies",
72+
"iam:ListPolicyTags",
73+
"iam:ListRolePolicies",
74+
"iam:DeleteOpenIDConnectProvider",
75+
"iam:DeleteInstanceProfile",
76+
"iam:GetRole",
77+
"iam:GetPolicy",
78+
"iam:ListEntitiesForPolicy",
79+
"iam:DeleteRole",
80+
"iam:TagPolicy",
81+
"iam:CreateOpenIDConnectProvider",
82+
"iam:CreatePolicy",
83+
"secretsmanager:GetResourcePolicy",
84+
"iam:ListPolicyVersions",
85+
"iam:UpdateRole",
86+
"iam:GetOpenIDConnectProvider",
87+
"iam:TagOpenIDConnectProvider",
88+
"secretsmanager:TagResource",
89+
"sts:AssumeRoleWithWebIdentity",
90+
"iam:ListRoles"
91+
],
92+
"Resource": [
93+
"arn:aws:secretsmanager:*:<ACCOUNT_ID>:secret:*",
94+
"arn:aws:iam::<ACCOUNT_ID>:instance-profile/*",
95+
"arn:aws:iam::<ACCOUNT_ID>:role/*",
96+
"arn:aws:iam::<ACCOUNT_ID>:oidc-provider/*",
97+
"arn:aws:iam::<ACCOUNT_ID>:policy/*"
98+
]
99+
},
100+
{
101+
"Sid": "VisualEditor1",
102+
"Effect": "Allow",
103+
"Action": [
104+
"s3:*"
105+
],
106+
"Resource": "*"
107+
}
108+
]
109+
}
110+
----
111+
====
112+
ifeval::["{context}" == "rosa-understanding-terraform"]
113+
:!tf-full:
114+
endif::[]

0 commit comments

Comments
 (0)