page_title	Red Hat Cloud Services Terraform Provider
subcategory
description

Red Hat Cloud Services Terraform Provider

Please note that this Terraform provider and its modules are open source and will continue to iterate features, gradually maturing this code. If you encounter any issues, please report them in this repo.

Introduction

The Red Hat Cloud Services Terraform provider allows Terraform to manage Red Hat OpenShift Service on AWS (ROSA) clusters and relevant resources.

For more information about ROSA, see the Red Hat documentation here.

Prerequisites

• GoLang version 1.24 or newer
• Terraform version 1.4.6 or newer
• An offline OCM token
• AWS account
• Completed the ROSA getting started requirements
• ROSA CLI
• Optional: A configured *.tfvars file.

Contributor setup

BEFORE MAKING YOUR FIRST COMMIT IN A CLONE, YOU MUST INSTALL LOCAL GIT HOOKS:

make install-hooks

YOU MUST LET THESE HOOKS RUN ON EVERY COMMIT AND PUSH. DO NOT BYPASS LOCAL HOOKS. Installed hooks run staged-file formatting at commit time, commit-message validation during commit, and full verification checks before push.

Formatting commands:

• make fmt formats Go import order and syntax plus Terraform files under examples/ and tests/, then fails if rewrites were needed so you can review and stage the updates
• make fmt-staged formats staged Go import order and syntax plus staged Terraform files under examples/ and tests/, then fails if rewrites were needed so you can review and stage the updates
• make fmt-check validates Go import order/formatting plus Terraform formatting without changing files
• make lint runs the pinned golangci-lint v2 configuration used by CI

Recommended local commands before pushing:

make basic-checks      # convenience flow: starts with make fmt and may stop after rewrites so you can review/stage
make pre-push-checks   # exact non-mutating verification used by the pre-push hook

Changed-files coverage is enforced through make coverage-changed-files using gocovdiff with an 80% threshold for changed Go files under provider/ and internal/.

Provider documentation

See the Terraform Registry documentation for instructions on using this provider.

Limitations of the OCM Terraform provider

The following items are limitations with the current release of the OCM Terraform provider:

• The latest version is not backward compatible with version 1.0.1.
• When creating a cluster, the cluster uses AWS credentials configured on your local machine. These credentials provide access to the AWS API for validating your account.
• When creating a machine pool, you need to specify your replica count. You must define either the replicas= "<count>" variable or provide values for the following variables to build the machine pool:
  • min_replicas = "<count>"
  • max_replicas="<count>"
  • autoscaling_enabled=true
• The htpasswd identity provider does not support creating the identity provider with multiple users or adding additional users to the existing identity provider.
• The S3 bucket that is created as part of the OIDC configuration must be created in the same region as your OIDC provider.
• The Terraform provider does not support auto-generated operator_role_prefix. You must provide your operator_role_prefix when creating the account roles.

Examples

The example Terraform files are all considered in development:

Prior to creating clusters

• Account Roles Terraform

Cluster creation examples

• Create a ROSA cluster that uses STS and has a managed OIDC configuration
• Create a ROSA cluster that uses STS and has an unmanaged OIDC configuration

Post cluster installation

• Modifying default machine pools
• The following identity providers are supported:
  • Github
  • Gitlab
  • HTPasswd
  • Google
  • LDAP
• Upgrading or updating your cluster

Contributing to the Red Hat Cloud Service Terraform provider

If you want to build a local Red Hat Cloud Services provider to develop improvements for the Red Hat Cloud Services provider, you can run terraform plan against your local build with:

1. Run make install in the repository root directory. After running make install you will find the rhcs provider binary file in the directory:

   <HOME>/.terraform.d/plugins/terraform.local/local/rhcs/<VERSION>/<TARGET_ARCH>
   

   For example, the following location would contain the terraform-rhcs-provider binary file:

   ~/.terraform.d/plugins/terraform.local/local/rhcs/0.0.1/linux_amd64
   

2. You now need to update your main.tf to the location of the local provider by pointing the required_providers rhcs to the local terraform directory.

   terraform {
     required_providers {
       rhcs = {
         source  = "terraform.local/local/rhcs"
         version = ">=0.0.1"
       }
     }
   }
   
   provider "rhcs" {
     token = var.token
     url = var.url
   }
   
   

Testing binary

If you want to locally test the provider binary without building from sources, you can pull the latest binary container image and copy the binary file to your local by running make binary or the whole background command if you need to make custom changes:

    podman run --pull=always --rm registry.ci.openshift.org/ci/rhcs-tf-bin:latest cat /root/terraform-provider-rhcs > ~/terraform-provider-rhcs && chmod +x ~/terraform-provider-rhcs

You can also use specific commit images by substituting latest for the desired commit SHA. Binary image only runs on AMD64 architectures up to now.

Developing the Provider

Detailed documentation for developing and contributing to RHCS provider can be found in our contribution guide.