Skip to main contentIBM Cloud Patterns

Setup Terraform Environment for IBM Cloud

Instructions to setup your environment to use Terraform for IBM Cloud

The first step before you start working with Infrastructure as Code or Terraform is to setup your environment. We will install terraform, then set it up for IBM Cloud and make sure it works with IBM Cloud.

Install IBM Cloud CLI

If you already have installed and setup the IBM Cloud CLI you may skip this section and go straight to install infrastructure IBM Cloud CLI Plugins.

In this pattern you will see ibmcloud CLI in most of the examples and instructions. This table provides simplified instructions to install ibmcloud CLI on different platforms, for more details, see the cli installation instructions.

The following one-liner script works on Linux to install the latest version of ibmcloud:

curl -fsSL | sh

Or, you can download the latest version of the Installer for Linux from the IBM Cloud CLI Releases page, extract the package and run the install script.

Verify ibmcloud was correctly installed by executing: ibmcloud version, you should see something like this:

$ ibmcloud version
ibmcloud version 1.0.0+908f90a-2020-03-30T10:19:41+00:00

IBM Cloud CLI Plugins

The next steps is to install all the required plugins, for Infrastructure as Code you’ll need the vpc-infrastructure (aka infrastructure-service) and the schematics plugins, to install them execute the following command:

ibmcloud plugin install -f -r "IBM Cloud" infrastructure-service
ibmcloud plugin install -f -r "IBM Cloud" schematics

To list all the available plugins use the command:

ibmcloud plugin repo-plugins

When a plugin version is out-of-date, you will see a reminder the first time you use that plugin in a cli session. To update plugins, you can use the following command to list available updates and select the ones to install:

ibmcloud plugin update

Login to IBM Cloud

Log in to IBM Cloud with the login sub-command. You may need to use the parameter -r to select a region (i.e. us-south or eu-gb), -g to select a resource group (i.e. Default), -c to select an account ID and --sso to request a one-time password if your IBMid is federated with another identity provider. When not using --sso, the command will interactively prompt for user name and password. Although these can be specified with the -u or -p parameters, for security reasons, it’s not recommended to do so.

ibmcloud login -r us-south -g Default --sso

You don’t have to select the region or the resource group at login, these can be set at any time in the cli. After login (with or without resource group), to list all the available resource groups use the resource groups sub-command then use the target sub-command to select it.

ibmcloud resource groups
ibmcloud target -g RESOURCE_GROUP_NAME

The target sub-command can be used also to select a new account ID or region.

Install Terraform

Terraform is Open Source software developed by HashiCorp to describe infrastructure as a code. Terraform allows you to build, change, and do versioning of the infrastructure safely and efficiently on multiple platforms and clouds. You can use Terraform to automate your IBM Cloud resource provisioning, rapidly build complex, multi-tier cloud environments, and implement Infrastructure as Code (IaC).

Terraform is distributed as a single binary for different platforms and architectures. To install Terraform follow the instructions below to install it from Terraform downloads or from the command prompt from your platform.

Download the latest version for your operative system from the Download Terraform page, then unzip it and move it to a directory included in your system’s PATH environment variable.

Verify terraform is correctly installed by executing: terraform version, you should see something like this:

$ terraform version
Terraform v0.12.24

Configure access to IBM Cloud

With Terraform you can create, manage and update almost any infrastructure resource such as virtual servers, virtual routers, load balancers, containers, kubernetes clusters, and more. All these infrastructure components are represented as a resource in Terraform. All these resources are defined in a Terraform provider which is responsible to interact and expose the resources using the cloud service API.

In order for Terraform to interact with IBM Cloud, it requires the IBM Cloud Provider. To install the IBM Cloud Provider just download the binary to the directory ~/.terraform.d/plugins. Download the latest version from, or execute the following simple script on Linux or Mac OS X, make sure to update the version number (i.e. v1.3.0) to the latest one.

mkdir -p ~/.terraform.d/plugins
curl -SL "$(uname | tr '[:upper:]' '[:lower:]')" | \
tar -xf - -C ~/.terraform.d/plugins
chmod +x ~/.terraform.d/plugins/terraform-provider-ibm_*

Now we need to setup the IBM Cloud credentials on the system to let the IBM Cloud provider to talk the IBM Cloud REST API.

If you haven’t logged in yet, follow the steps from login to IBM Cloud or just execute ibmcloud login and target a resource group.

ibmcloud login --sso
ibmcloud resource groups
ibmcloud target -g RESOURCE_GROUP_NAME

Create an API Key on the IBM Cloud web console following these instructions or simply using the ibmcloud command, like this:

ibmcloud iam api-key-create TerraformKey -d "API Key for Terraform" --file terraform_key.json

If you are in a GitHub repository directory, make sure the file is not pushed or ignore it adding the filename to .gitignore, executing:

echo "terraform_key.json" >> .gitignore

To give Terraform and the IBM Cloud provider access to the IBM Cloud credentials, store the API key as the environment variable IC_API_KEY.

export IC_API_KEY=$(grep '"apikey":' terraform_key.json | sed 's/.*: "\(.*\)".*/\1/')

Or by using jq:

export IC_API_KEY=$(jq -r .apikey terraform_key.json)

Testing access to IBM Cloud

The Terraform code can be done with JSON format or using HashiCorp Configuration Language (HCL). During this pattern guide we’ll use only HCL and we will call it HCL or Terraform Code.

A simple terraform code to verify your access could be something like the following:

provider "ibm" {
generation = 2
region = "us-south"
data "ibm_iam_access_group" "accgroup" {
output "accgroups" {

Create a file with the above terraform code in a temporary directory, then execute:

terraform init
terraform apply

The output of terraform apply should print any Access Groups that are visible to you in the account associated with your API key. The output should be similar to the execution of:

ibmcloud iam access-groups

In the following section we’ll see more examples.