From e74deecb1872cbe5a62b9e395efd5276c3e058c2 Mon Sep 17 00:00:00 2001 From: EricPonvelle Date: Thu, 20 Jun 2024 09:22:56 -0400 Subject: [PATCH] POC: Created the general structure for Terraform tutorials --- _topic_maps/_topic_map_rosa.yml | 6 ++ cloud_experts_tutorials/terraform/_attributes | 1 + ...cloud-experts-terraform-customization.adoc | 21 ++++++ cloud_experts_tutorials/terraform/images | 1 + cloud_experts_tutorials/terraform/modules | 1 + cloud_experts_tutorials/terraform/snippets | 1 + ...assic-cluster-terraform-file-creation.adoc | 14 +--- ...a-hcp-cluster-terraform-file-creation.adoc | 6 +- .../rosa-sts-cluster-terraform-destroy.adoc | 11 ++- .../rosa-sts-cluster-terraform-execute.adoc | 15 ++--- ...of-the-default-cluster-specifications.adoc | 3 - modules/rosa-terraform-overview.adoc | 2 - modules/terraform-guide-autoscaling.adoc | 13 ++++ modules/terraform-guide-env-variables.adoc | 67 +++++++++++++++++++ modules/terraform-guide-private-clusters.adoc | 19 ++++++ ...-creating-a-cluster-quickly-terraform.adoc | 8 ++- snippets/terraform-apply.adoc | 65 ++++++++++++++++++ 17 files changed, 216 insertions(+), 38 deletions(-) create mode 120000 cloud_experts_tutorials/terraform/_attributes create mode 100644 cloud_experts_tutorials/terraform/cloud-experts-terraform-customization.adoc create mode 120000 cloud_experts_tutorials/terraform/images create mode 120000 cloud_experts_tutorials/terraform/modules create mode 120000 cloud_experts_tutorials/terraform/snippets create mode 100644 modules/terraform-guide-autoscaling.adoc create mode 100644 modules/terraform-guide-env-variables.adoc create mode 100644 modules/terraform-guide-private-clusters.adoc create mode 100644 snippets/terraform-apply.adoc diff --git a/_topic_maps/_topic_map_rosa.yml b/_topic_maps/_topic_map_rosa.yml index bdf669133e46..c4f659eca184 100644 --- a/_topic_maps/_topic_map_rosa.yml +++ b/_topic_maps/_topic_map_rosa.yml @@ -119,6 +119,12 @@ Topics: File: rosa-mobb-verify-permissions-sts-deployment - Name: Deploying ROSA with a Custom DNS Resolver File: cloud-experts-custom-dns-resolver +- Name: Terraform + Dir: terraform + Distros: openshift-rosa + Topics: + - Name: Customizing your cluster with Terraform + File: cloud-experts-terraform-customization - Name: Using AWS WAF and Amazon CloudFront to protect ROSA workloads File: cloud-experts-using-cloudfront-and-waf - Name: Using AWS WAF and AWS ALBs to protect ROSA workloads diff --git a/cloud_experts_tutorials/terraform/_attributes b/cloud_experts_tutorials/terraform/_attributes new file mode 120000 index 000000000000..20cc1dcb77bf --- /dev/null +++ b/cloud_experts_tutorials/terraform/_attributes @@ -0,0 +1 @@ +../../_attributes/ \ No newline at end of file diff --git a/cloud_experts_tutorials/terraform/cloud-experts-terraform-customization.adoc b/cloud_experts_tutorials/terraform/cloud-experts-terraform-customization.adoc new file mode 100644 index 000000000000..eade2740295b --- /dev/null +++ b/cloud_experts_tutorials/terraform/cloud-experts-terraform-customization.adoc @@ -0,0 +1,21 @@ +:_mod-docs-content-type: ASSEMBLY +[id="cloud-experts-cloud-experts-terraform-customization"] += Tutorial: Customizing your cluster with Terraform +include::_attributes/attributes-openshift-dedicated.adoc[] +:context: cloud-experts-terraform-customization + +toc::[] + +You can customize your cluster with Terraform by using the following guides. This tutorial assumes that you have created your cluster using either xref:../../rosa_hcp/terraform/rosa-hcp-creating-a-cluster-quickly-terraform.adoc#rosa-hcp-creating-a-cluster-quickly-terraform[Creating a default ROSA cluster using Terraform] or xref:../../rosa_install_access_delete_clusters/terraform/rosa-classic-creating-a-cluster-quickly-terraform.adoc#rosa-classic-creating-a-cluster-quickly-terraform[Creating a default {rosa-classic} cluster using Terraform] or link:https://registry.terraform.io/providers/terraform-redhat/rhcs/latest/docs[Terraform registry documentation]. + +include::modules/terraform-guide-env-variables.adoc[leveloffset=+1] + +include::modules/terraform-guide-autoscaling.adoc[leveloffset=+1] + +include::modules/terraform-guide-private-clusters.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="additional-resources_cloud-experts-terraform-customization"] +.Additional resources + +* See link:https://registry.terraform.io/providers/terraform-redhat/rhcs/latest/docs[Terraform registry documentation]. diff --git a/cloud_experts_tutorials/terraform/images b/cloud_experts_tutorials/terraform/images new file mode 120000 index 000000000000..847b03ed0541 --- /dev/null +++ b/cloud_experts_tutorials/terraform/images @@ -0,0 +1 @@ +../../images/ \ No newline at end of file diff --git a/cloud_experts_tutorials/terraform/modules b/cloud_experts_tutorials/terraform/modules new file mode 120000 index 000000000000..36719b9de743 --- /dev/null +++ b/cloud_experts_tutorials/terraform/modules @@ -0,0 +1 @@ +../../modules/ \ No newline at end of file diff --git a/cloud_experts_tutorials/terraform/snippets b/cloud_experts_tutorials/terraform/snippets new file mode 120000 index 000000000000..5a3f5add140e --- /dev/null +++ b/cloud_experts_tutorials/terraform/snippets @@ -0,0 +1 @@ +../../snippets/ \ No newline at end of file diff --git a/modules/rosa-classic-cluster-terraform-file-creation.adoc b/modules/rosa-classic-cluster-terraform-file-creation.adoc index f7ef48fdd5aa..69ffb46d5e0a 100644 --- a/modules/rosa-classic-cluster-terraform-file-creation.adoc +++ b/modules/rosa-classic-cluster-terraform-file-creation.adoc @@ -1,9 +1,7 @@ // Module included in the following assemblies: // // * rosa_install_access_delete_clusters/rosa-classic-creating-a-cluster-quickly-terraform.adoc - :_content-type: PROCEDURE - [id="rosa-classic-cluster-terraform-file-creation_{context}"] = Creating your Terraform files locally @@ -82,17 +80,11 @@ locals { resource "time_sleep" "wait_60_seconds" { count = var.create_vpc ? 1 : 0 depends_on = [module.vpc] - create_duration = "60s" } module "rosa-classic" { source = "terraform-redhat/rosa-classic/rhcs" version = "1.5.0" - cluster_name = local.cluster_name - openshift_version = var.openshift_version - account_role_prefix = local.cluster_name - operator_role_prefix = local.cluster_name - replicas = local.worker_node_replicas aws_availability_zones = local.region_azs create_oidc = true private = var.private_cluster @@ -130,7 +122,6 @@ Copy and edit this file _before_ running the command to build your cluster. + [source,terminal] ---- -$ cat<<-EOF>variables.tf # # Copyright (c) 2023 Red Hat, Inc. # @@ -200,6 +191,7 @@ variable "aws_subnet_ids" { variable "private_cluster" { type = bool description = "If you want to create a private cluster, set this value to 'true'. If you want a publicly available cluster, set this value to 'false'." + default = "false" } #VPC Info @@ -247,7 +239,7 @@ variable "default_aws_tags" { EOF ---- -. Create the `vpc.tf` file by running the following command: +. Create the vpc.tf file by running the following command: + [source,terminal] ---- @@ -289,4 +281,4 @@ module "vpc" { EOF ---- + -You are ready to initiate Terraform. +You are ready to initiate Terraform. \ No newline at end of file diff --git a/modules/rosa-hcp-cluster-terraform-file-creation.adoc b/modules/rosa-hcp-cluster-terraform-file-creation.adoc index ee281b131332..19bca61af649 100644 --- a/modules/rosa-hcp-cluster-terraform-file-creation.adoc +++ b/modules/rosa-hcp-cluster-terraform-file-creation.adoc @@ -79,15 +79,10 @@ locals { # The network validator requires an additional 60 seconds to validate Terraform clusters. resource "time_sleep" "wait_60_seconds" { count = var.create_vpc ? 1 : 0 - depends_on = [module.vpc] - create_duration = "60s" -} - module "rosa-hcp" { source = "terraform-redhat/rosa-hcp/rhcs" version = "1.6.3" cluster_name = local.cluster_name - openshift_version = var.openshift_version account_role_prefix = local.cluster_name operator_role_prefix = local.cluster_name replicas = local.worker_node_replicas @@ -190,6 +185,7 @@ variable "aws_subnet_ids" { variable "private_cluster" { type = bool description = "If you want to create a private cluster, set this value to 'true'. If you want a publicly available cluster, set this value to 'false'." + default = false } #VPC Info diff --git a/modules/rosa-sts-cluster-terraform-destroy.adoc b/modules/rosa-sts-cluster-terraform-destroy.adoc index 10f39deb4c14..c1428443b97d 100644 --- a/modules/rosa-sts-cluster-terraform-destroy.adoc +++ b/modules/rosa-sts-cluster-terraform-destroy.adoc @@ -1,15 +1,14 @@ // Module included in the following assemblies: // -// * rosa_install_access_delete_clusters/rosa-classic-creating-a-cluster-quickly-terraform.adoc -// +// * rosa_hcp/terraform/rosa-hcp-creating-a-cluster-quickly-terraform.adoc +// * rosa_install_access_delete_clusters/terraform/rosa-classic-creating-a-cluster-quickly-terraform.adoc ifeval::["{context}" == "rosa-classic-creating-a-cluster-quickly-terraform"] -:tf-defaults: +:tf-rosa-classic: endif::[] ifeval::["{context}" == "rosa-hcp-creating-a-cluster-quickly-terraform"] :tf-rosa-hcp: endif::[] :_content-type: PROCEDURE - [id="sd-terraform-cluster-destroy_{context}"] = Deleting your ROSA cluster with Terraform @@ -115,8 +114,8 @@ I: Fetching operator roles I: No operator roles available ---- ifeval::["{context}" == "rosa-classic-creating-a-cluster-quickly-terraform"] -:tf-defaults: +:!tf-rosa-classic: endif::[] ifeval::["{context}" == "rosa-hcp-creating-a-cluster-quickly-terraform"] -:tf-rosa-hcp: +:!tf-rosa-hcp: endif::[] \ No newline at end of file diff --git a/modules/rosa-sts-cluster-terraform-execute.adoc b/modules/rosa-sts-cluster-terraform-execute.adoc index be6a79120344..0aa028d907c2 100644 --- a/modules/rosa-sts-cluster-terraform-execute.adoc +++ b/modules/rosa-sts-cluster-terraform-execute.adoc @@ -1,7 +1,7 @@ // Module included in the following assemblies: // -// * rosa_install_access_delete_clusters/rosa-classic-creating-a-cluster-quickly-terraform.adoc -// +// * rosa_hcp/terraform/rosa-hcp-creating-a-cluster-quickly-terraform.adoc +// * rosa_install_access_delete_clusters/terraform/rosa-classic-creating-a-cluster-quickly-terraform.adoc ifeval::["{context}" == "rosa-classic-creating-a-cluster-quickly-terraform"] :tf-rosa-classic: endif::[] @@ -47,7 +47,7 @@ Success! The configuration is valid. $ terraform apply ---- + -The Terraform interface asks two questions to create your cluster, similiar to the following: +The Terraform interface asks a question to create your cluster, similiar to the following: + .Example output [source,terminal] @@ -55,11 +55,6 @@ The Terraform interface asks two questions to create your cluster, similiar to t var.create_vpc If you would like to create a new VPC, set this value to 'true'. If you do not want to create a new VPC, set this value to 'false'. - Enter a value: - -var.private_cluster - If you want to create a private cluster, set this value to 'true'. If you want a publicly available cluster, set this value to 'false'. - Enter a value: ---- @@ -69,7 +64,7 @@ ifdef::tf-rosa-hcp[] .Example output [source,terminal] ---- -Plan: 63 to add, 0 to change, 0 to destroy. +Plan: 64 to add, 0 to change, 0 to destroy. Do you want to perform these actions? Terraform will perform the actions described above. @@ -80,7 +75,7 @@ ifdef::tf-rosa-classic[] .Example output [source,terminal] ---- -Plan: 74 to add, 0 to change, 0 to destroy. +Plan: 75 to add, 0 to change, 0 to destroy. Do you want to perform these actions? Terraform will perform the actions described above. diff --git a/modules/rosa-sts-overview-of-the-default-cluster-specifications.adoc b/modules/rosa-sts-overview-of-the-default-cluster-specifications.adoc index b0444403f418..5ccd6893b5fd 100644 --- a/modules/rosa-sts-overview-of-the-default-cluster-specifications.adoc +++ b/modules/rosa-sts-overview-of-the-default-cluster-specifications.adoc @@ -107,11 +107,8 @@ endif::tf-classic,tf-hcp[] |Networking configuration | -ifndef::tf-classic,tf-hcp[] * Cluster privacy: Public -endif::tf-classic,tf-hcp[] ifdef::tf-classic,tf-hcp[] -* Cluster privacy: public or private * You can choose to create a new VPC during the Terraform cluster creation process. endif::tf-classic,tf-hcp[] ifdef::openshift-rosa[] diff --git a/modules/rosa-terraform-overview.adoc b/modules/rosa-terraform-overview.adoc index 00258c159fb5..248c5ac88ca8 100644 --- a/modules/rosa-terraform-overview.adoc +++ b/modules/rosa-terraform-overview.adoc @@ -2,9 +2,7 @@ // // * rosa_install_access_delete_clusters/rosa-classic-creating-a-cluster-quickly-terraform.adoc // - :_content-type: CONCEPT - [id="rosa-terraform-overview_{context}"] = Overview of Terraform diff --git a/modules/terraform-guide-autoscaling.adoc b/modules/terraform-guide-autoscaling.adoc new file mode 100644 index 000000000000..b889ad03000e --- /dev/null +++ b/modules/terraform-guide-autoscaling.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * cloud_experts_tutorials/terraform/cloud-experts-terraform-customization.adoc + +:_mod-docs-content-type: PROCESS +[id="terraform-guide-autoscaling_{context}"] += Enabling autoscaling on your cluster + +In your `variables.tf` file, set the default value to `true`: + +[source,terminal] +---- +---- \ No newline at end of file diff --git a/modules/terraform-guide-env-variables.adoc b/modules/terraform-guide-env-variables.adoc new file mode 100644 index 000000000000..980f5640b0db --- /dev/null +++ b/modules/terraform-guide-env-variables.adoc @@ -0,0 +1,67 @@ +// Module included in the following assemblies: +// +// * cloud_experts_tutorials/terraform/cloud-experts-terraform-customization.adoc + +:_mod-docs-content-type: CONCEPT +[id="terraform-guide-env-variable_{context}"] += Using environmental variables + +You can use locally set variables to specify a value once and reuse that value later. + +.Procedure + +. Set an environment variable by running the following command: ++ +[source,terminal] +---- +$ export <1> = <2> +VARIABLE_NAME="VARIABLE_VALUE" +---- ++ +Your variable name and value can be any string. For example, if you want to consistently refer to your cluster's name, you run the following commad: ++ +.Example input +[source,terminal] +---- +$ export CLUSTER_NAME="rosa-cluster" +---- + +. Confirm the environment variable by running the following: ++ +[source,terminal] +---- +$ echo $ +---- ++ +.Example output +[source,terminal] +---- +$ echo $CLUSTER_NAME +$ rosa-cluster +---- + +[id="terraform-guide-env-variable-table_{context}"] +== Examples of variables used for OpenShift resources + +Use this table as a guideline for your own environment. The table is not a comprehensive model of all possible environment variables. + +[cols="1,1"] +|=== +|Example variable name| Description + +|CLUSTER_NAME +|This is the text-based string that you use as the name of your cluster. + +|AWS_REGION +|This is text-based string is the AWS region that you want to use for your resource. + +|ACCOUNT_ROLES_PREFIX +| + +| +| + +|=== + +[id="terraform-guide-env-variable-example_{context}"] +== Example workflow using environmental variables to create a ROSA cluster \ No newline at end of file diff --git a/modules/terraform-guide-private-clusters.adoc b/modules/terraform-guide-private-clusters.adoc new file mode 100644 index 000000000000..c437ae60894d --- /dev/null +++ b/modules/terraform-guide-private-clusters.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * cloud_experts_tutorials/terraform/cloud-experts-terraform-customization.adoc + +ifeval::["{context}" == "cloud-experts-terraform-customization"] +:enable-vpc: +endif::[] +:_mod-docs-content-type: CONCEPT +[id="terraform-guide-private-cluster_{context}"] += Creating a private {hcp-title} cluster + +. Run the following command in your terminal to create a private {hcp-title} cluster: ++ +[source,terminal] +---- +$ export TF_VAR_private_cluster="true" +---- + +include::snippets/terraform-apply.adoc[] \ No newline at end of file diff --git a/rosa_install_access_delete_clusters/terraform/rosa-classic-creating-a-cluster-quickly-terraform.adoc b/rosa_install_access_delete_clusters/terraform/rosa-classic-creating-a-cluster-quickly-terraform.adoc index 1fa6fa0d762d..9c6b830a2166 100644 --- a/rosa_install_access_delete_clusters/terraform/rosa-classic-creating-a-cluster-quickly-terraform.adoc +++ b/rosa_install_access_delete_clusters/terraform/rosa-classic-creating-a-cluster-quickly-terraform.adoc @@ -1,6 +1,6 @@ :_content-type: ASSEMBLY [id="rosa-classic-creating-a-cluster-quickly-terraform"] -= Creating a default ROSA (classic architecture) cluster using Terraform += Creating a default {rosa-classic} cluster using Terraform include::_attributes/attributes-openshift-dedicated.adoc[] :context: rosa-classic-creating-a-cluster-quickly-terraform @@ -16,9 +16,12 @@ The cluster creation process described below uses a Terraform configuration that * All other AWS resources required to create a ROSA with STS cluster include::modules/rosa-terraform-overview.adoc[leveloffset=+1] + include::modules/rosa-sts-terraform-prerequisites.adoc[leveloffset=+1] + [discrete] include::modules/rosa-sts-terraform-considerations.adoc[leveloffset=+1] + include::modules/rosa-sts-overview-of-the-default-cluster-specifications.adoc[leveloffset=+1] [id="rosa-classic-creating-a-cluster-quickly-terraform-procedure"] @@ -27,8 +30,11 @@ include::modules/rosa-sts-overview-of-the-default-cluster-specifications.adoc[le The cluster creation process outlined below shows how to use Terraform to create your account-wide IAM roles and a {rosa-classic} cluster with a managed OIDC configuration. include::modules/rosa-sts-cluster-terraform-setup.adoc[leveloffset=+2] + include::modules/rosa-classic-cluster-terraform-file-creation.adoc[leveloffset=+2] + include::modules/rosa-sts-cluster-terraform-execute.adoc[leveloffset=+2] + include::modules/rosa-sts-cluster-terraform-destroy.adoc[leveloffset=+2] [role="_additional-resources"] diff --git a/snippets/terraform-apply.adoc b/snippets/terraform-apply.adoc new file mode 100644 index 000000000000..b68717a4d6c0 --- /dev/null +++ b/snippets/terraform-apply.adoc @@ -0,0 +1,65 @@ +// Text snippet included in the following assemblies: +// +// * applications/deployments/what-deployments-are.adoc +// * applications/deployments/managing-deployment-processes.adoc +// +// Text snippet included in the following modules: +// +// * modules/deployments-deploymentconfigs.adoc +// * modules/deployments-comparing-deploymentconfigs.adoc + +:_mod-docs-content-type: SNIPPET + +[start=2] +. Set up Terraform to create your resources based on your Terraform files, run the following command: ++ +[source,terminal] +---- +$ terraform init +---- + +. *Optional*: Verify that the Terraform you copied is correct by running the following command: ++ +[source,terminal] +---- +$ terraform validate +---- ++ +.Example output ++ +[source,terminal] +---- +Success! The configuration is valid. +---- + +. Create your cluster with Terraform by running the following command: ++ +[source,terminal] +---- +$ terraform apply +---- ++ +The Terraform interface asks a question to create your cluster, similiar to the following: ++ +.Example output +[source,terminal] +---- +var.create_vpc + If you would like to create a new VPC, set this value to 'true'. If you do not want to create a new VPC, set this value to 'false'. + + Enter a value: +---- + +. Enter `yes` to proceed or `no` to cancel when the Terraform interface lists the resources to be created or changed and prompts for confirmation: ++ +.Example output +[source,terminal] +---- +Plan: 64 to add, 0 to change, 0 to destroy. + +Do you want to perform these actions? + Terraform will perform the actions described above. + Only 'yes' will be accepted to approve. +---- ++ +If you enter `yes`, your Terraform plan starts, creating your AWS account roles, Operator roles, and your ROSA Classic cluster. \ No newline at end of file