Workspaces

Answers to common questions about the IBM Cloud Schematics workspaces are classified into the following section.

Does IBM Cloud Schematics support multiple Terraform provider versions?

Yes, IBM Cloud Schematics supports multiple Terraform provider versions. You need to add the Terraform provider block with the right provider version. By default the provider run current version 1.21.0, and previous four versions such as 1.20.1, 1.20.0, 1.19.0, 1.18.0 are supported.

Example for a multiple provider configuration:

terraform{
    required_providers{
    ibm = ">= 1.21.0" // Error !! version unavailable.
    ibm = ">= 1.20.0" // Execute against latest version.
    ibm = "== 1.20.1" // Executes version v1.20.1. 
    }
}

Currently, version 1.21.0 is released. For more information, see provider version.

How do I update the Terraform version

IBM Cloud Schematics deprecates older version of Terraform. For more information, see Deprecating older version of Terraform process in IBM Cloud Schematics.

IBM Cloud Schematics deprecates creation of workspace using the IBM Cloud Provider Plug-in for Terraform v1.2, v1.3 template from 2nd week of April 2024.

You can follow the topics to upgrade from one Terraform version to another version

How do I `pull latest` code from a Git repo by using the command line?

Updating the IBM Cloud® Schematics workspaces through command line need the needed field name.

You need to run ibmcloud schematics workspace update --id <workspace-id> --file <updatefile.json> command. The sample updatefile.json contains the name field with the value.

{
    "name":"testworkspace"
}

What tools and utilities are used in the runtime?

Schematics runtime is built by using Universal Base Image (UBI-8) and the runtime utilities/softwares that come with the UBI-8 are available for Terraform provisions and Ansible actions. For more information, see the list of tools and utilities that are used in Schematics runtime.

How can I fix Git token issues when creating workspaces by using the CLI

Using schematics workspace new --file schematic-file.json -g xxxx command throws an Access token creation failed status, as the token is not specified in the command.

You need to check your authentication before performing the operation through command-line. Then, create a workspace by using schematics workspace new --file schematic-file.json --github-token xxxx command. For more information, see ibmcloud schematics workspace new command.

How do I fix authorization issues when creating or updating a workspace?

You see authorization issues when the role and permission access is insufficient while updating the workspace. For more information, see Managing user access.

How to use Schematics services with a test ID?

The test IDs are considered as a valid IBM ID to set the global catalog or resource controller-related API calls. If you are unable to access, do Contact support service.

How to limit Git repo folder cloning

By default when creating a workspace through the UI, Schematics default to cloning the full Git repository and all sub directory. De-select the 'Use full repository' flag to limit the folders that are cloned and improve download performance.

Schematics introduced a compact flag in the create workspace and update workspace API to download the sub directories in Git repositories. If the compact flag is set to true it downloads and save sub directories recursively, otherwise, you can continue to download and save the full repository on workspace creation.

You can get the response by starting get workspace API to view the compact flag value. The compact flag can be given only if the template_repo.url field is passed. On update, if this field is not passed, but the URL is passed, the download is compact.

Compact usage in the payload is .template_data[0].compact = true/false. For more information, see Compact download for Schematics workspaces.

How to delete a workspace when the delete fails?

If a resource is deleted outside the Schematics, a workspace delete operation displays that as resource no longer exists.

You need to delete the workspace and NOT destroying the resources as if resource is not available. For more information, see Deleting a workspace.

What is the best way to deploy a Helm chart by using credentials or secrets?

The best way is to use IBM Cloud catalog to manage the Helm charts where inside the catalog you can keep the credentials and mark it as secured. For more information, see List of catalog that is related to Helm.

How to address job failures that are caused by maintenance activities?

The unexpected impact due to maintenance results in the failure of the running activities in Schematics workspace. Such workspace and the ongoing activity are marked as Failed. The user can then re-run the activity. For more information, see workspace state diagram.

How do you set the Git release tag?

2021/11/08 12:34:06 -----  New Action  -----
 2021/11/08 12:34:06 Request: RepoURL=https://github.ibm.com/wh-hp-insights/hi-cloud-automation, workspaceSource=Schematics, Branch=2021.10, Release=, Folder=terraform-v2/workspace-hi-qa-automation-app
 2021/11/08 12:34:06 Related Activity: action=UPDATE_WORKSPACE,processedBy=sandbox-6bcf8bffcd-rxbww_2478
 2021/11/08 12:34:06 Getting download command
 2021/11/08 12:34:11 Fatal, could not download repo, Failed to clone git repository, couldn't find remote ref "refs/heads/2021.10" (most likely invalid branch name is passed)
 2021/11/08 12:34:12 Problems found with the Repository. Please Rectify and Retry

If the Release parameter is empty and the Branch was set with release tag.

Schematics does not support release tag, as it's difficult to identify if it’s a release tag or a branch from the Git repository URL. You need to set the release tag through the Schematics API.

Why do I get a 403 error instead of a 404 error when using an invalid workspace ID?

curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/badWOrkspaceId -H "Authorization: $IAM_TOKEN"
{"requestid":"3a3cbffe-e23a-4ccf-b764-042f7379c084","timestamp":"2021-11-11T17:00:07.169953698Z","messageid":"M1078","message":"Error while validating the location in the account. Verify you have permission to the location in the global catalog settings.","statuscode":403}

Yes there is a change in the API that checks for the location first and if it doesn’t get the proper location for the workspace it returns a 403 error instead of 404 error.

How can I enable Terraform debug logging

You can set the environment variable for setting the Terraform log debug TF_LOG=debug trace in the payload, as shown in the sample payload. For more information, see Schematics workspaces update.

{
  "name": "sample",
  "type": [
    "terraform_v0.12"
  ],
  "description": "terraform workspace",
  "tags": [
  ],
  "template_repo": {
    "url": "<your repo>"
  },
  "template_data": [
    {
      "folder": ".",
      "type": "terraform_v0.12",
      "env_values":[
      {
"TF_LOG":"debug"
      }
   ]
    }
  ]
}

How can I import Cloud resources into a workspace?

Use the ibmcloud schematics workspace import --options value, -o value : Optional command and the sample syntax to import from command line. For more information, see Schematics workspace import.


ibmcloud schematics workspaces import --id <workspace_id> --address <my terraform resource address> --resourceID <the CRN of the item to import> --options "-var IC_API_KEY=XXXXXXXX"

or 

ibmcloud schematics workspaces import --id <workspace_id> --address <my terraform resource address> --resourceID <the CRN of the item to import> --options "--var-file=<path-to-var-file>"

How can I download Job files?

Yes, you can download the Schematics Job files. For more information, see Download Schematics Job files.

How can I resolve Terraform resource timeout failures?

You need to update or increase the timeout value by 5 minutes or 10 minutes depending upon the service as shown in the Terraform block. Or you need to send null value to use the default values.

variable "create_timeout" 
{
 type = String
 description = "Timeout duration to create LogDNA instance in Schematics."
 default = "15m"
}

How do I set the TF_CLI_ARGS environment variable?

No, you cannot set an environment variable value in the Schematics workspaces console directly. Instead, you can use a CURL by using the Schematics API, or Schematics command line.

  "env_values": [
        {
          "TF_LOG": "debug"
        },
  ]

Can I use private Git repositories for modules?

Yes, Schematics supports downloading Terraform modules from private repositories. For more information, see Supporting to download modules from private remote host.

Can I edit all the variables in a workspace?

You can edit only one variable at a time from Schematics console. From the command line you can edit all the variables of the workspace in the JSON format by using ibmcloud schematics workspace update command.

How do I import keys when importing KMS resources?

Yes, you can set or manage the keys by using ibm_kms_key as shown in the sample code block. For more information, see ibm_kms_key.

resource "ibm_resource_instance" "kms_instance" {
  name     = "instance-name"
  service  = "kms"
  plan     = "tiered-pricing"
  location = "us-south"
}
resource "ibm_kms_key" "test" {
  instance_id  = ibm_resource_instance.kms_instance.guid
  key_name     = "key-name"
  standard_key = false
  force_delete =true
}
resource "ibm_cos_bucket" "smart-us-south" {
  bucket_name          = "atest-bucket"
  resource_instance_id = "cos-instance-id"
  region_location      = "us-south"
  storage_class        = "smart"
  key_protect          = ibm_kms_key.test.id
}

Can you enable the TRACE to help DEBUG Schematics API while running workspace list command?

No, currently Schematics do not support this feature while running IBMCLOUD_TRACE=true ibmcloud schematics workspace list command.

How do I resolve errors in listing workspaces?

When listing or retrieving workspaces the following error may be received. Error while retrieving Schematics Instance for the given account.

Error:
Bad status code [400] returned when getting workspace from Schematics: {"requestid":"fe5f0d6d-1d43-4643-a689-35d090463ce8","timestamp":"2022-01-25T20:23:54.727208017Z","messageid":"M1070","message":"Error while retrieving {{site.data.keyword.bpshort}} Instance for the given account.","statuscode":400}

You might have insufficient access for the workspaces in the specified location to fetch the instance. Do check the permission that is provided for your account and the locations where your instance need to be created. For more information, see Where is an information stored?

How can I use (IBM) GitLab repositories?

Yes, You can access the private (IBM) GitLab repository by using Schematics with the privileges.

If the private (IBM) GitLab repository git.cloud.ibm.com access token is not needed as the IAM token is used.
If the public GitLab gitlab.com, read_repository, and read_api access are needed to validate the branch name for private repository.

You can use the sample Terraform code block to configure the GitLab repository details.

"template_repo": {
"url": "<gitlab_source_repo_url>",
"branch": ""
},

Can IAM access groups be managed in Schematics?

Yes, Schematics supports the full IBM Cloud provider resource set. For more information about How IAM access group works? see ibm_iam_access_group.

How do I work with resources in another account?

Yes, you can create Schematics workspaces in IBM Cloud source account. Then, run Terraform providing resources in target account to provision, through CLI, and API calls by using the target account service ID with the authentication, appropriate cross account authorization, or API key. For more information, see Managing resources in other account.

What does `North America` location indicate?

North America always indicates both us-south, and us-east location during the Schematics workspace creation. For more information, see Where can I create Schematics workspaces?, and Where is my information stored?

What ports and IP addresses are used by Schematics?

Schematics communicates with the ports that are specified by the related resources. For example, VPC related ports, see VPC: Opening required ports and IP addresses in other network firewalls.

When do I use Schematics versus the individual resource dashboards?

With IBM Cloud Schematics, you can run your infrastructure code in IBM Cloud to manage the lifecycle of IBM Cloud resources. After you provision a resource, you use the dashboard of the individual resource to work and interact with your resource. For example, if you provision a virtual server instance in a Virtual Private Cloud (VPC) with IBM Cloud Schematics. You can use the VPC console, API, or command-line to stop, reboot, and power on your virtual server instance. However, to remove the virtual server instance, you can use IBM Cloud Schematics.

Are changes to Git repos refreshed in Schematics?

No, if you change the code of your Terraform template in GitHub, these changes are not available automatically when you create an execution plan in IBM Cloud Schematics. To pull the current changes from your GitHub repository, make sure that you click the Pull latest option from the workspace settings page before you create your execution plan.

Where is the Terraform state file stored?

After you successfully provisioned IBM Cloud resources by running a Schematics apply action, the state of resources is stored in a Terraform state file (terraform.tfstate). Schematics uses this state file as the single source of truth to determine what resources exist in your account. The state file maps the resources that you specified in your Terraform configuration file to the IBM Cloud resource that you provisioned.

Are resources removed on delete workspace?

Deleting a workspace from IBM Cloud Schematics does not remove any of your IBM Cloud resources. If you delete the workspace before you remove your resources, you must manually remove all your IBM Cloud resources from the individual resource dashboard.

Removing IBM Cloud resources cannot be undone. Make sure that you have backed up any data before you remove a resource. Resources are removed (deleted) if you remove the resource definition or comment out the resource in your Terraform configuration file. Review the Plan log file to verify that all your resources are included in the removal.

Can I set environment variables for workspaces?

You can set env values for a workspace by using the CLI and API. For more information, see usage of env_values.

Sample payload

{
  "name": "newName",
  "template_data": [
    {
      "type": "<same_as_before>",
      "env_values": [
        {
          "env_values_1": "dummy_text"
        },
        {
          "env_values_2": "dummy_text"
        }
      ],
      "env_values_metadata": [
        {
          "name": "env_values_1",
          "hidden": false,
          "secure": false
        },
        {
          "name": "env_values_2",
          "hidden": false,
          "secure": false
        }
      ]
    }
  ]
}

Does drift detection run automatically?

No, the drift detection is not an automatic method of detection in the IBM Cloud Schematics. For more information, see detecting drift in Schematics.

How can I initiate drift detection?

You can initiate drift detection by using the UI and CLI. For more information, see detecting drift in Schematics.

Where can I see the status of a drift detection job?

To verify the results of a drift detection job, you need to check the drift detection job log. The job log provides the details of the drift detection as in progress or completed with the appropriate status such as failure or success. For more information, see detecting drift in Schematics.

Can I `interrupt` or `terminate` running jobs?

Yes, you can interrupt, force-stop, or terminate the provisioning resources or a running job in Schematics by using the job types. For more information, see stopping the job types.

How do I correct an `Incorrect Location Input` error?

Error

{
    "requestid": "3f59c342-cd2c-4703-aa10-9e8e7072a3ac",
    "timestamp": "2022-06-28T20:02:58.529765308Z",
    "messageid": "M1097",
    "message": "Incorrect Location Input.",
    "statuscode": 400
}

The Schematics global endpoint is defaulted to us environment. Therefore, you need to use regional endpoints to point your location to a eu-de region.

How can I view workspace resources?

Use the state list CLI command to view the same resources as in IBM Cloud Schematics UI.

How do I fix the `CreateworkspaceWithContext failed Bad request` error?

Error

CreateWorkspaceWithContext failed Bad request. Check that the information you entered in the payload is complete and formatted correctly in JSON.

The Schematics public or private endpoint global URL by default points to us region. As a workaround you can set the environment variable key before the Terraform commands.

```sh
export IBMCLOUD_SCHEMATICS_API_ENDPOINT="https://eu-de.schematics.cloud.ibm.com"
```

You can also add the endpoints to a JSON file to categorize the endpoints service as public or private.

Sample provider declaration

{
    "IBMCLOUD_SCHEMATICS_API_ENDPOINT":{
        "public":{
            "eu-de":"https://eu-de.schematics.cloud.ibm.com"
        }
         }
}

Example Provider Block

provider "ibm" {

  endpoints_file_path= "endpoints.json"
}

Are sensitive values in the state file encrypted?

Schematics encrypts the Terraform state file when stored and also in transit by using TLS. Terraform does not separately encrypt sensitive values. For more information, see sensitive-data in state file.

Why do workspace variables that are defined by using CLI throw 400 errors?

The Schematics workspace list variables store value should always be an HCL string. The value field must contain an escaped string for the variable store for the list, map, or complex variable. For more information, see Providing values to Schematics for the declared variables.

Can you update the Terraform version (`TF_VERSION`) using a `JSON` file?

Currently, the workaround to updating the TF_VERSION is to pass the TF_VERSION while updating the variable store. Schematics auto detects what is specified in the Terraform version block in the TF files. This is the default behavior.

For more information, see setting and changing the version.

Can start with a new Terraform state file on each job run?

No, you need to create new workspace. For more information, see Workspace job execution.

Can I import an existing Terraform state file?

Yes, you can use --state flag option through the ibmcloud schematics workspace new.

What is the maximum variable size?

The maximum length of characters that Schematics workspace variables support is 1 MB.

What is the maximum state file size of import?

The terraform.tfstate file size must be less than 16 MB. When you create workspace from an existing Terraform state file, the terraform.tfstate file size must be less than 16 MB. Greater than 16 MB state file size is not supported in the Schematics. You see an error message with 413 Request Entity Too Large error when creating a new workspace.

How do I fix authentication errors when using the API?

You need to create the IAM access token for your IBM Cloud Account. For more information, see Get token password. You can see the following sample error message and the solution for the authentication error.

Error: Request fails with status code: 400, BXNIMO137E: For the original authentication, client id 'default' was passed, refresh the token, client id 'bx' is used.

The IAM API documentation shows how to create a default token. You can use the refresh token to get a new IAM access token if that token is expired. When the default client (no basic authorization header) as described in this documentation. The refresh_token cannot be used to retrieve a new IAM access token. When the IAM access token is about to be expired, use the API key to create a new access token as listed.

You need to create access_token and refresh_token.

export IBMCLOUD_API_KEY=<ibmcloud-api_key>
curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx

Export the access_token and refresh_token obtained in step 1 as environment variables for ACCESS_TOKEN and REFRESH_TOKEN.
```
export ACCESS_TOKEN=<access_token>
export REFRESH_TOKEN=<refresh_token>
```

Create workspace

curl --request POST --url https://cloud.ibm.com/schematics/overview/v1/workspaces -H "Authorization: Bearer <access_token>" -d '{"name":"","type": ["terraform_v0.12"],"description": "","resource_group": "","tags": [],"template_repo": {"url": ""},"template_data": [{"folder": ".","type": "terraform_v0.12","variablestore": [{"name": "variable_name1","value": "variable_value1"},{"name": "variable_name2","value": "variable_value2"}]}]}'