Chapter 3. Creating a ROSA cluster using Terraform

Procedure

1. Optional: Because the Terraform files get created in your current directory during this procedure, you can create a new directory to store these files and navigate into it by running the following command:

   $ mkdir terraform-cluster && cd terraform-cluster

   Copy to Clipboard Toggle word wrap
2. Grant permissions to your account by using an offline Red Hat OpenShift Cluster Manager token.

3. Copy your offline token, and set the token as an environmental variable by running the following command:

   $ export RHCS_TOKEN=<your_offline_token>

   Copy to Clipboard Toggle word wrap
   Note

   This environmental variable resets at the end of each session, such as restarting your machine or closing the terminal.

Procedure

1. Create the main.tf file by running the following command:

   $ cat<<-EOF>main.tf
   #
   # Copyright (c) 2023 Red Hat, Inc.
   #
   # Licensed under the Apache License, Version 2.0 (the "License");
   # you may not use this file except in compliance with the License.
   # You may obtain a copy of the License at
   #
   #   http://www.apache.org/licenses/LICENSE-2.0
   #
   # Unless required by applicable law or agreed to in writing, software
   # distributed under the License is distributed on an "AS IS" BASIS,
   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   # See the License for the specific language governing permissions and
   # limitations under the License.
   #
   terraform {
     required_providers {
       aws = {
         source  = "hashicorp/aws"
         version = ">= 4.20.0"
       }
       rhcs = {
         version = ">= 1.6.3"
         source  = "terraform-redhat/rhcs"
       }
     }
   }
   
   # Export token using the RHCS_TOKEN environment variable
   provider "rhcs" {}
   
   provider "aws" {
     region = var.aws_region
     ignore_tags {
       key_prefixes = ["kubernetes.io/"]
     }
     default_tags {
       tags = var.default_aws_tags
     }
   }
   
   data "aws_availability_zones" "available" {}
   
   locals {
     # Extract availability zone names for the specified region, limit it to 3 if multi az or 1 if single
     region_azs = var.multi_az ? slice([for zone in data.aws_availability_zones.available.names : format("%s", zone)], 0, 3) : slice([for zone in data.aws_availability_zones.available.names : format("%s", zone)], 0, 1)
   }
   
   resource "random_string" "random_name" {
     length  = 6
     special = false
     upper   = false
   }
   
   locals {
     worker_node_replicas = var.multi_az ? 3 : 2
     # If cluster_name is not null, use that, otherwise generate a random cluster name
     cluster_name = coalesce(var.cluster_name, "rosa-\${random_string.random_name.result}")
   }
   
   # 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
     aws_availability_zones = local.region_azs
     create_oidc            = true
     private                = var.private_cluster
     aws_subnet_ids         = var.create_vpc ? var.private_cluster ? module.vpc[0].private_subnets : concat(module.vpc[0].public_subnets, module.vpc[0].private_subnets) : var.aws_subnet_ids
     create_account_roles   = true
     create_operator_roles  = true
   # Optional: Configure a cluster administrator user \ 

   1

   
   #
   # Option 1: Default cluster-admin user
   # Create an administrator user (cluster-admin) and automatically
   # generate a password by uncommenting the following parameter:
   #  create_admin_user = true
   # Generated administrator credentials are displayed in terminal output.
   #
   # Option 2: Specify administrator username and password
   # Create an administrator user and define your own password
   # by uncommenting and editing the values of the following parameters:
   #  admin_credentials_username = <username>
   #  admin_credentials_password = <password>
   
     depends_on = [time_sleep.wait_60_seconds]
   }
   EOF

   Copy to Clipboard Toggle word wrap

   1

   Optional: Create an administrator user during cluster creation by uncommenting the appropriate parameters and editing their values if required.

2. Create the variables.tf file by running the following command:

   Note

   Copy and edit this file before running the command to build your cluster.

   $ cat<<-EOF>variables.tf
   #
   # Copyright (c) 2023 Red Hat, Inc.
   #
   # Licensed under the Apache License, Version 2.0 (the "License");
   # you may not use this file except in compliance with the License.
   # You may obtain a copy of the License at
   #
   #   http://www.apache.org/licenses/LICENSE-2.0
   #
   # Unless required by applicable law or agreed to in writing, software
   # distributed under the License is distributed on an "AS IS" BASIS,
   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   # See the License for the specific language governing permissions and
   # limitations under the License.
   #
   variable "openshift_version" {
     type        = string
     default     = "4.14.20"
     description = "Desired version of OpenShift for the cluster, for example '4.14.20'. If version is greater than the currently running version, an upgrade will be scheduled."
   }
   
   variable "create_vpc" {
     type        = bool
     description = "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'."
   }
   
   # ROSA Cluster info
   variable "cluster_name" {
     default     = null
     type        = string
     description = "The name of the ROSA cluster to create"
   }
   
   variable "additional_tags" {
     default = {
       Terraform   = "true"
       Environment = "dev"
     }
     description = "Additional AWS resource tags"
     type        = map(string)
   }
   
   variable "multi_az" {
     type        = bool
     description = "Multi AZ Cluster for High Availability"
     default     = true
   }
   
   variable "worker_node_replicas" {
     default     = 3
     description = "Number of worker nodes to provision. Single zone clusters need at least 2 nodes, multizone clusters need at least 3 nodes"
     type        = number
   }
   
   variable "aws_subnet_ids" {
     type        = list(any)
     description = "A list of either the public or public + private subnet IDs to use for the cluster blocks to use for the cluster"
     default     = ["subnet-01234567890abcdef", "subnet-01234567890abcdef", "subnet-01234567890abcdef"]
   }
   
   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'."
   }
   
   #VPC Info
   variable "vpc_name" {
     type        = string
     description = "VPC Name"
     default     = "tf-qs-vpc"
   }
   
   variable "vpc_cidr_block" {
     type        = string
     description = "value of the CIDR block to use for the VPC"
     default     = "10.0.0.0/16"
   }
   
   variable "private_subnet_cidrs" {
     type        = list(any)
     description = "The CIDR blocks to use for the private subnets"
     default     = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
   }
   
   variable "public_subnet_cidrs" {
     type        = list(any)
     description = "The CIDR blocks to use for the public subnets"
     default     = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]
   }
   
   variable "single_nat_gateway" {
     type        = bool
     description = "Single NAT or per NAT for subnet"
     default     = false
   }
   
   #AWS Info
   variable "aws_region" {
     type    = string
     default = "us-east-2"
   }
   
   variable "default_aws_tags" {
     type        = map(string)
     description = "Default tags for AWS"
     default     = {}
   }
   EOF

   Copy to Clipboard Toggle word wrap

3. Create the vpc.tf file by running the following command:

   $ cat<<-EOF>vpc.tf
   #
   # Copyright (c) 2023 Red Hat, Inc.
   #
   # Licensed under the Apache License, Version 2.0 (the "License");
   # you may not use this file except in compliance with the License.
   # You may obtain a copy of the License at
   #
   #   http://www.apache.org/licenses/LICENSE-2.0
   #
   # Unless required by applicable law or agreed to in writing, software
   # distributed under the License is distributed on an "AS IS" BASIS,
   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   # See the License for the specific language governing permissions and
   # limitations under the License.
   #
   module "vpc" {
     source  = "terraform-aws-modules/vpc/aws"
     version = "5.1.2"
   
     count = var.create_vpc ? 1 : 0
     name  = var.vpc_name
     cidr  = var.vpc_cidr_block
   
     azs             = local.region_azs
     private_subnets = var.multi_az ? var.private_subnet_cidrs : [var.private_subnet_cidrs[0]]
     public_subnets  = var.multi_az ? var.public_subnet_cidrs : [var.public_subnet_cidrs[0]]
   
     enable_nat_gateway   = true
     single_nat_gateway   = var.single_nat_gateway
     enable_dns_hostnames = true
     enable_dns_support   = true
   
     tags = var.additional_tags
   }
   EOF

   Copy to Clipboard Toggle word wrap

   You are ready to initiate Terraform.

Procedure

1. Set up Terraform to create your resources based on your Terraform files, run the following command:

   $ terraform init

   Copy to Clipboard Toggle word wrap

2. Optional: Verify that the Terraform you copied is correct by running the following command:

   $ terraform validate

   Copy to Clipboard Toggle word wrap

   Example output

   Success! The configuration is valid.

   Copy to Clipboard Toggle word wrap

3. Create your cluster with Terraform by running the following command:

   $ terraform apply

   Copy to Clipboard Toggle word wrap

   The Terraform interface asks two questions to create your cluster, similar to the following:

   Example output

   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:

   Copy to Clipboard Toggle word wrap

4. 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

   Plan: 63 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.

   Copy to Clipboard Toggle word wrap

   If you enter yes, your Terraform plan starts, creating your AWS account roles, Operator roles, and your Red Hat OpenShift Service on AWS cluster.

Verification

1. Verify that your cluster was created by running the following command:

   $ rosa list clusters

   Copy to Clipboard Toggle word wrap

   Example output showing a cluster’s ID, name, and status

   ID                                NAME          STATE  TOPOLOGY
   27c3snjsupa9obua74ba8se5kcj11269  rosa-tf-demo  ready  Hosted CP

   Copy to Clipboard Toggle word wrap

2. Verify that your account roles were created by running the following command:

   $ rosa list account-roles

   Copy to Clipboard Toggle word wrap

   Example output

   I: Fetching account roles
   ROLE NAME                                   ROLE TYPE      ROLE ARN                                                           OPENSHIFT VERSION  AWS Managed
   ROSA-demo-Installer-Role                    Installer      arn:aws:iam::<ID>:role/ROSA-demo-Installer-Role                    4.14               No
   ROSA-demo-Support-Role                      Support        arn:aws:iam::<ID>:role/ROSA-demo-Support-Role                      4.14               No
   ROSA-demo-Worker-Role                       Worker         arn:aws:iam::<ID>:role/ROSA-demo-Worker-Role                       4.14               No

   Copy to Clipboard Toggle word wrap

3. Verify that your Operator roles were created by running the following command:

   $ rosa list operator-roles

   Copy to Clipboard Toggle word wrap

   Example output showing Terraform-created Operator roles

   I: Fetching operator roles
   ROLE PREFIX    AMOUNT IN BUNDLE
   rosa-demo      8

   Copy to Clipboard Toggle word wrap

Procedure

1. In the directory where you ran the terraform apply command to create your cluster, run the following command to delete the cluster:

   $ terraform destroy

   Copy to Clipboard Toggle word wrap

   The Terraform interface prompts you for two variables. These should match the answers you provided when creating a cluster:

   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:

   Copy to Clipboard Toggle word wrap

2. Enter yes to start the role and cluster deletion:

   Example output

   Plan: 0 to add, 0 to change, 63 to destroy.
   
   Do you really want to destroy all resources?
     Terraform will destroy all your managed infrastructure, as shown above.
     There is no undo. Only 'yes' will be accepted to confirm.
   
     Enter a value: yes

   Copy to Clipboard Toggle word wrap

Verification

1. Verify that your cluster was destroyed by running the following command:

   $ rosa list clusters

   Copy to Clipboard Toggle word wrap

   Example output showing no cluster

   I: No clusters available

   Copy to Clipboard Toggle word wrap

2. Verify that the account roles were destroyed by running the following command:

   $ rosa list account-roles

   Copy to Clipboard Toggle word wrap

   Example output showing no Terraform-created account roles

   I: Fetching account roles
   I: No account roles available

   Copy to Clipboard Toggle word wrap

3. Verify that the Operator roles were destroyed by running the following command:

   $ rosa list operator-roles

   Copy to Clipboard Toggle word wrap

   Example output showing no Terraform-created Operator roles

   I: Fetching operator roles
   I: No operator roles available

   Copy to Clipboard Toggle word wrap