Using Terraform to configure Schematics

Example: Creating the Schematics workspaces by using Terraform

Complete the following steps to create a Schematics workspace using Terraform:

1. Follow the Terraform on IBM Cloud getting started tutorial to install the Terraform CLI and configure the IBM Cloud Provider Plug-in for Terraform. The plug-in abstracts the IBM Cloud APIs that are used to provision, update, or delete Schematics resources.

2. Create the Terraform configuration files named main.tf, terraform.tfvars, and versions.tf.

   You can use the Terraform example Git URL https://github.com/IBM-Cloud/terraform-provider-ibm/tree/master/examples/ibm-api-gateway. This example uses service instance to set up an API for an IBM Cloud service of your choice. You can specify the API endpoint that you want to use to access your service, and define subscription keys so that you can securely consume your API.

   If you have a workspace created other in a region other than us, you must set the API endpoint to that region. For example, if your region specified is eu, the API endpoint should be specified as IBMCLOUD_SCHEMATICS_API_ENDPOINT=https://eu.schematics.cloud.ibm.com in the environment variable. For more information about the Schematics workspace locations and endpoints to be used, see Where is my information stored?.

   Then create the Schematics workspace tf-testwks-apigwy in the default resource group of your region. This workspace points to a Terraform template of your choice that requires the Terraform version terraform_v1.0.

   versions.tf

   The sample versions.tf file to specify the provider version that you need to create the workspace.

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

   terraform.tfvars

   The sample terraform.tfvars file to store sensitive information, such as credentials. For more information, see Referencing credentials from a terraform.tfvars file. To create API keys, see Creating and API Keys.

   schematics_workspace_name="tf-testwks-apigwy"
   schematics_workspace_description="Sample workspace created with terraform with URL"
   schematics_workspace_type="terraform_v1.0"
   schematics_workspace_location="us-south"
   schematics_workspace_resource_group="default"
   ibmcloud_api_key="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   
   

   main.tf

   Review the following sample main.tf file. This file invokes the variables from the terraform.tfvars file by using the Git URL, then creates a Schematics workspace by using your IBM Cloud API key.

   variable "schematics_workspace_name" {}
   variable "schematics_workspace_description" {}
   variable "schematics_workspace_type" {}
   variable "schematics_workspace_location" {}
   variable "schematics_workspace_resource_group" {}
   variable "ibmcloud_api_key" {}
   
   resource "ibm_schematics_workspace" "schematics_workspace_instance" {
   name = var.schematics_workspace_name
   description = var.schematics_workspace_description
   location = var.schematics_workspace_location
   resource_group = var.schematics_workspace_resource_group
   tags = ["sample"]
   template_env_settings = [
       { env1 = "val1" },
       { env2 = "val2" }
   ]
   template_type= var.schematics_workspace_type
   template_git_url = "https://github.com/IBM-Cloud/terraform-provider-ibm/tree/master/examples/ibm-api-gateway"
   }
   
   provider "ibm" {
   region           = "us-south"
   ibmcloud_api_key = var.ibmcloud_api_key
   }
   
   

   The following table lists supported parameters when you create and initialize a service instance with Terraform. For more information about the detailed parameters to create workspace, see ibm_schematics_workspace resource.

   Supported parameters for creating Schematics workspaces with Terraform.

   Parameter	Description
   description	The description of the workspace.
   location	The location where you want to create your Schematics workspace and run Schematics actions.
   resource_group	The ID of the resource group where you want to provision the workspace.
   name	The name of your workspace. The name can be up to 128 characters long and can include alphanumeric characters, spaces, dashes, and underscores. When you create a workspace for your own Terraform template, consider including the microservice component that you set up with your Terraform template and the IBM Cloud environment where you want to deploy your resources in your name.
   tags	A list of tags that are associated with the workspace.
   template_env_settings	A list of environment variables that you want to apply during the execution of a Terraform action.
   template_git_url	The Git repository URL, where you have the configuration details to provision the resource.
   template_type	Specify the Terraform version that you want to apply in Schematics workspace.

3. Initialize the Terraform CLI.

   terraform init
   

   If the environment variable path for Terraform is not set, you can see command not found: terraform error. Fix the error by setting the path to your Terraform installed directory.

4. Create a Terraform execution plan. The Terraform execution plan summarizes all the actions that need to be run to create the Schematics workspace in your account.

   terraform plan
   

5. Create the Schematics workspace instance and IAM access policy in IBM Cloud.

   terraform apply
   

   For more information about troubleshooting the terraform apply command errors, see find the root cause of why Schematics apply is failing.

6. From the Schematics dashboard, check your tf-testwks-apigwy workspace is created. And the resources are provisioned from the IBM Cloud Schematics resource list.

7. Verify that the access policy is successfully assigned. For more information, see Reviewing assigned access in the console.

What's next?

Now that you successfully created your first Schematics workspace with Terraform on IBM Cloud, you can choose between the following tasks:

• Learn how to create an IBM Cloud Schematics job resource to run your Terraform template in IBM Cloud.
• To run Ansible playbooks in IBM Cloud check out the IBM Cloud Schematics action resource.
• Explore other supported Terraform resources and data sources for IBM Cloud Schematics or checkout other arguments and attributes that you can use for the Terraform resources that were used in this example.