Getting started with Terraform on IBM Cloud

Step 1: Installing the Terraform CLI

Use these steps to install the Terraform CLI.

1. Create a terraform folder on your local machine, and navigate to your terraform folder.

   mkdir terraform && cd terraform
   

2. Download the Terraform version that you want. The IBM Cloud Provider plug-in for Terraform currently supports Terraform stable version 1.x.x. For more information, about the supported Terraform version, see list of Terraform version.
3. Extract the Terraform zip file and copy the files to your terraform directory.
4. Set the environment PATH variable to your terraform folder.

   export PATH=$PATH:$HOME/terraform
   

5. Verify that the installation is successful by using a terraform command.

   terraform
   

   Example output:

   Usage: terraform [global options] <subcommand> [args]
   
   The available commands for execution are listed below.
   The primary workflow commands are given first, followed by
   less common or more advanced commands.
   
   Main commands:
   init          Prepare your working directory for other commands
   validate      Check whether the configuration is valid
   plan          Show changes required by the current configuration
   apply         Create or update infrastructure
   destroy       Destroy previously-created infrastructure
   
   All other commands:
   console       Try Terraform expressions at an interactive command prompt
   fmt           Reformat your configuration in the standard style
   force-unlock  Release a stuck lock on the current workspace
   get           Install or upgrade remote Terraform modules
   graph         Generate a Graphviz graph of the steps in an operation
   import        Associate existing infrastructure with a Terraform resource
   login         Obtain and save credentials for a remote host
   logout        Remove locally-stored credentials for a remote host
   output        Show output values from your root module
   providers     Show the providers required for this configuration
   refresh       Update the state to match remote systems
   show          Show the current state or a saved plan
   state         Advanced state management
   taint         Mark a resource instance as not fully functional
   test          Experimental support for module integration testing
   untaint       Remove the 'tainted' state from a resource instance
   version       Show the current Terraform version
   workspace     Workspace management
   
   Global options (use these before the subcommand, if any):
   -chdir=DIR    Switch to a different working directory before executing the
                   given subcommand.
   -help         Show this help output, or the help for a specified subcommand.
   -version      An alias for the "version" subcommand.
   

Step 2: Configuring the IBM Cloud Provider plug-in

After the Terraform command-line installation is complete. You must 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.

If you installed or want to use an Terraform v0.12.x and earlier version of Terraform, install the provider plug-in by following the steps in Terraform v0.12.x and earlier.

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 plugin, 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 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 provider.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 provider.tf file and then reference the variable by using the var.<variable_name> syntax .

   Example of provider.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: Additional parameters are required when configuring the IBM Cloud Provider plug-in. To find sample configurations for these services, see Specifying the provider block.

Step 3: Testing your configuration

Now that you configured the IBM Cloud Provider plug-in for your resource you can start 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.

To view sample Terraform templates with the complete Terraform configuration files to test, refer to Sample templates.

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