Creating Terraform on IBM Cloud templates

Learn how to create Terraform on IBM Cloud templates that are well-structured, reusable, and comprehensive.

An Terraform on IBM Cloud template consists of one or more Terraform on IBM Cloud configuration files that declare the state that you want to achieve for your IBM Cloud resources. To successfully work with your resources, you must configure IBM as your cloud provider and add resources to your resource block. Optionally, you can use input variables to customize your resources.

You can write your Terraform on IBM Cloud configuration file by using HashiCorp Configuration Language (HCL) or JSON syntax. For more information, see Configuration language.

Configuring the `provider` block

Specify the cloud provider that you want to use in the provider block of your Terraform on IBM Cloud configuration file. The provider block includes all the input variables that the IBM Cloud Provider plug-in for the Terraform on IBM Cloud to provision your resources.

Do I need to provide the IBM Cloud API key?

The IBM Cloud API key is essential to authenticate with the IBM Cloud platform, receive the IAM token and IAM refresh token that Schematics requires to work with the resource's API, and to determine the permissions that you were granted. When you use native Terraform on IBM Cloud, you must always provide the IBM Cloud API key. In Schematics, the API key is automatically retrieved for all IAM-enabled resources, including IBM Cloud Kubernetes Service clusters, and VPC infrastructure resources. However, the API key is not retrieved for Cloud Foundry and classic infrastructure resources and must be provided in the provider block.

Can I specify a different IBM Cloud API key in the provider block?

If you want to use a different API key than the one that is associated with your IBM Cloud account, you can provide this API key in the provider block. If an API key is configured in the provider block, this key takes precedence over the API key that is stored in IBM Cloud.

Can I provide an API key for a service ID?

You can provide an API key for a service ID for all IAM-enabled services, including VPC infrastructure resources. You cannot use a service ID for classic infrastructure or Cloud Foundry resources.

To configure the provider block:

Choose how you want to configure the provider block.
- Option 1: Create a separate provider.tf file. The information in this file is loaded by Terraform on IBM Cloud and IBM Cloud Schematics, and applied to all Terraform on IBM Cloud configuration files that exist in the same GitHub directory or tape archive file (.tar). This approach is useful if you split out your infrastructure code across multiple files.
- Option 2: Add a provider block to your Terraform on IBM Cloud configuration file. You might choose this option if you prefer to specify the provider alongside with your variables and resources in one Terraform on IBM Cloud configuration file.
The providers file is used 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.
Review what credentials and information you must provide in the provider block to work with your resources in required input parameters for each resource category. Schematics automatically retrieves your IBM Cloud API key so that you do not need to specify this information in your provider block.

Create a provider.tf file or add the following code to your Terraform on IBM Cloud configuration file. For a full list of supported parameters that you can set in the provider block, see the IBM Cloud provider reference.

Example for VPC infrastructure resources

provider "ibm" {
    generation = 2
    region = "<region_name>"
}

Example for classic infrastructure resources

variable "iaas_classic_username" {
    type = "string"
}
variable "iaas_classic_api_key" {
    type = "string"
}

provider "ibm" {
    region = "<region_name>"
    iaas_classic_username = var.iaas_classic_username
    iaas_classic_api_key  = var.iaas_classic_api_key
}

Example for all IBM Cloud Kubernetes Service resources

provider "ibm" {
}

Example for all other resources

provider "ibm" {
    region = "<region_name>"
}

Adding IBM Cloud resources to the `resource` block

Use resource blocks to define the IBM Cloud resources that you want to manage with IBM Cloud Schematics.

To support a multi-cloud approach, Terraform on IBM Cloud works with multiple cloud providers. A cloud provider is responsible for understanding the resources that you can provision, their API, and the methods to expose these resources in the cloud. To make this knowledge available to users, every supported cloud provider must provide a command line plug-in for Terraform on IBM Cloud that users can use to work with the resources. To find an overview of the resources that you can provision in IBM Cloud, see the Terraform on IBM Cloud reference.

Example infrastructure code for provisioning a VPC

resource ibm_is_vpc "vpc" {
    name = "myvpc"
}

Referencing resources in other resource blocks

Review the options that you have to reference existing resources in other resource blocks of your Terraform on IBM Cloud configuration file.

The IBM Cloud Provider plug-in reference includes two types of objects, data sources and resources. You can use both objects to reference resources in other resource blocks.

Resources: To create a resource, you use the resource definition in the IBM Cloud Provider plug-in reference. A resource definition includes the syntax for configuring your IBM Cloud resources and an Attributes reference that shows the properties that you can reference as input parameters in other resource blocks. For example, when you create a VPC, the ID of the VPC is made available after the creation. You can use the ID as an input parameter when you create a subnet for your VPC. Use this option if you combine multiple resources in one Terraform on IBM Cloud configuration file.

Example infrastructure code
```
resource ibm_is_vpc "vpc" {
    name = "myvpc"
}

resource ibm_is_security_group "sg1" {
    name = "mysecuritygroup"
vpc  = ibm_is_vpc.vpc.id
}
```
Data sources: You can also use the data sources from the IBM Cloud Provider plug-in reference to retrieve information about an existing IBM Cloud resource. Review the Argument reference section in the IBM Cloud Provider plug-in reference to see what input parameters you must provide to retrieve an existing resource. Then, review the Attributes reference section to find an overview of parameters that are made available to you and that you can reference in your resource blocks. Use this option if you want to access the details of a resource that is configured in another Terraform on IBM Cloud configuration file.

Example infrastructure code
```
data ibm_is_image "ubuntu" {
    name = "ubuntu-18.04-amd64"
}

resource ibm_is_instance "vsi1" {
    name    = "$mysi"
    vpc     = ibm_is_vpc.vpc.id
    zone    = "us-south1"
    keys    = [data.ibm_is_ssh_key.ssh_key_id.id]
    image   = data.ibm_is_image.ubuntu.id
    profile = "cc1-2x4"

primary_network_interface {
    subnet          = ibm_is_subnet.subnet1.id
    security_groups = [ibm_is_security_group.sg1.id]
}
}
```

Using `variable` blocks to customize resources

You can use variable blocks to create templates for your infrastructure code. For example, instead of creating multiple Terraform on IBM Cloud configuration files for a resource that you want to deploy in multiple data centers, simply reuse the same configuration and use an input variable to define the data center.

Where do I store my variable declarations?
You can decide to declare your variables within the same Terraform on IBM Cloud configuration file where you specify the resources that you want to provision, or to create a separate variables.tf file that includes all your variable declarations. When you create a workspace, IBM Cloud Schematics automatically parses through your Terraform on IBM Cloud configuration files to find variable declarations.

What information do I need to include in my variable declaration?
When you declare an input variable, you must provide a name for your variable and the data type, such as string or integer, that the variable uses. You can optionally add a description and a default value for your variable. When input variables are imported into Schematics and a default value is specified, you can choose to overwrite the default value.

Is there a character limit for input variables?
Yes. If you define input variables in your Terraform on IBM Cloud configuration file, keep in mind that the value that you enter for these variables can be up to 2049 characters. If your input variable requires a value that exceeds this limit, the value is truncated after 2049 characters.

Example variable declaration without a default value

variable "datacenter" {
    type        = "string"
    description = "The data center that you want to deploy your Kubernetes cluster in."
}

Example variable declaration with a default value is

variable "datacenter" {
    type        = "string"
    description = "The data center that you want to deploy your Kubernetes cluster in."
    default = "dal10"
}

Referencing variables

You can reference the value of the variable in other blocks of your Terraform on IBM Cloud configuration files by using the "${var.<variable_name>}" syntax.

Example for referencing a datacenter variable:

resource ibm_container_cluster "test_cluster" {
    name         = "test"
    datacenter   = var.datacenter
}

For more information, about variable configurations, see the Terraform documentation.

Storing your Terraform on IBM Cloud templates

Your Terraform on IBM Cloud configuration files contain infrastructure code that you must treat as regular code. To support collaboration, source and version control, store your files in a GitHub or GitLab repository. With version control, you can revert to previous versions, audit changes, and share code with multiple teams. If you do not want to store your files in GitHub, you have the option to provide your template by uploading a tape archive file (.tar) from your local machine instead.

Cloning GitHub repository in IBM Cloud Schematics is allowed only to the listed extension files. The blocked extension files having more than 500 KB in size, and any invalid image is considered as vulnerable files while cloning.

Allowed extension: .tf .tfvars .md .yaml .sh .txt .yml .html .tf .json .gitignore license .js .pub .service _rsa
Blocked extension: .php5 .pht .phtml .shtml .asa .cer .asax .swf .xap .tfstate .tfstate.backup
Allowed image extension: .tif .tiff .gif .png .bmp .jpg .jpeg

The directory structure of the Terraform on IBM Cloud template in the GitHub repository looks like listed in the table with the last updated time.

File	Description
README.md	Create README.md
main.tf	Create main.tf
output.tf	Create output.tf
provider.tf	Create provider.tf
variables.tf	Create variables.tf