Getting started with Terraform on IBM Cloud

Installing the Terraform CLI

Install Terraform on your machine is by following the instructions provided by HashiCorp. This guide provides installation steps for major operating systems, including Windows, macOS, and Linux.

Ensure that the Terraform installation directory has been added to your PATH environment variable.

Verify that the installation is successful by running the following command.

terraform -version

Configuring the IBM Cloud Provider plug-in

After the Terraform command-line installation is complete, set up and configure the IBM Cloud Provider plug-in for Terraform so that you can start working with resources and services in IBM Cloud.

The following steps show how to set up the provider plug-in for Terraform v1.x or higher.

1. In your Terraform installation directory, create a folder for your first Terraform project and navigate into the folder. This folder is used to store all configuration files and variable definitions.

   mkdir myproject && cd myproject
   

2. Create a versions.tf file with the following content. In this file, specify the IBM Cloud Provider plug-in version that you want to use with the version parameter for IBM Cloud Provider plug-in, and required_version to specify the Terraform template version. If no version parameter is specified, IBM Cloud automatically uses the latest version of the provider. For a list of supported IBM Cloud Provider versions, see IBM Cloud Provider plug-in releases.

   Example with version parameter in versions.tf file

   terraform {
       required_providers {
           ibm = {
           source = "IBM-Cloud/ibm"
           version = "<provider_version>"
           }
       }
   }
   

   Example with required_version parameter in versions.tf file

   terraform {
   required_version = ">=1.0.0, <2.0"
   required_providers {
       ibm = {
       source = "IBM-Cloud/ibm"
       }
   }
   }
   

   Example with both required_version and version parameter in versions.tf file

   terraform {
   required_version = ">=1.0.0, <2.0"
   required_providers {
       ibm = {
       source = "IBM-Cloud/ibm"
       version = "<provider_version>"
       }
   }
   }
   

   The version is specified in the following format <MAJOR_VERSION>.<MINOR_VERSION>.<PATCH>. You can modify the version constraint operator in this example by using combination of the supported operators in Terraform.

3. Create or retrieve an IBM Cloud API key. The API key is used to authenticate with the IBM Cloud platform and to determine your permissions for IBM Cloud services.

4. Create a variables file that is named terraform.tfvars and specify the IBM Cloud API key that you retrieved. In addition, you can specify the region where you want your IBM Cloud resources to be created. If no region is specified, Terraform on IBM Cloud automatically creates your resources in the us-south region. Variables that are defined in the terraform.tfvars file are automatically loaded by Terraform when the IBM Cloud Provider plug-in is initialized and you can reference them in every Terraform configuration file that you use.

   Because the terraform.tfvars file contains confidential information, do not push this file to a version control system. This file is meant to be on your local system only.

   Example of terraform.tfvars file

   ibmcloud_api_key = "<ibmcloud_api_key>"
   region = "<region>"
   

5. Create a providers file to configure your endpoint URLs, cloud regions, or other settings before Terraform can use them, so that Terraform can install and use them in the provider configuration file that is named providers.tf. Use this file to configure the IBM Cloud Provider plug-in with the IBM Cloud API key from your terraform.tfvars file. The plug-in uses this key to access IBM Cloud and to work with your IBM Cloud service. To access a variable value from the terraform.tfvars file, you must first declare the variable in the providers.tf file and then reference the variable by using the var.<variable_name> syntax.

   Example of providers.tf file

   variable "ibmcloud_api_key" {}
   variable "region" {}
   
   provider "ibm" {
       ibmcloud_api_key   = var.ibmcloud_api_key
       region = var.region
       }
   

   Classic infrastructure, Functions, Power Systems: Extra parameters are required when configuring the IBM Cloud Provider plug-in. To find sample configurations for these services, see Specifying the provider block.

Testing your configuration

Now that you have configured the IBM Cloud Provider plug-in for your resource, you can start by using Terraform on IBM Cloud to initialize, execute plan, and apply commands to provision the resource. For more information about Terraform commands to test your configuration, see Provisioning IBM Cloud resources.

Explore Terraform IBM Modules along with the complete Terraform configuration files to test. Review the module code structure and follow the deployment instructions provided here.

Overview of Terraform resources and data sources

For an overview of the Terraform resources and data sources that you can use, see the Terraform on IBM Cloud resources and data sources.

To get information on the up-to-date Terraform on IBM Cloud releases, refer to the Terraform on IBM Cloud.