IBM Cloud Docs
Getting started with Terraform on IBM Cloud

Getting started with Terraform on IBM Cloud

Terraform on IBM Cloud enables predictable and consistent provisioning of IBM Cloud® platform, services, and VPC infrastructure resources so that you can rapidly build complex, multitier cloud environments, and adopt an Infrastructure as Code (IaC) approach to deploying environments.

An alternative to configuring IBM Cloud® with the standalone Terraform CLI is IBM Cloud Schematics. Schematics is an easy to use, managed Terraform as a service capability on IBM Cloud®, with a full featured UI along with CLI and API support. Schematics is integrated with the IBM Cloud Platform, with support for team usage, with locking and centralized state file management, IAM access controls, logging and monitoring. Free to use, it supports many additional features, including drift detection and configuration management with Red Hat Ansible. Get started now with IBM Cloud Schematics.

Here you learn how to install the Terraform command-line and the IBM Cloud Provider plug-in for Terraform on a local machine, laptop or server. Then how to configure the provider plug-in to create, update, or delete IBM Cloud services with Terraform.

See IBM Cloud Schematics if you want to start working with Terraform immediately without installation of the CLI and provider.

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

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

    Example with required_version parameter in 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 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 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 file and then reference the variable by using the var.<variable_name> syntax .

    Example of 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.