--- name: schematics-sc-workspaces-create title: Creating workspaces and importing your Terraform description: Use a Schematics to manage your IBM Cloud Schematics resources using Terraform. Workspace settings define the Terraform engine hosted in a Git repository to be used, along with any input variables to customize the template. last-updated: 2026-07-07 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/schematics?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Creating workspaces and importing your Terraform {: #sch-create-wks} Use a Schematics to manage your IBM Cloud Schematics resources using Terraform. Workspace settings define the Terraform engine hosted in a Git repository to be used, along with any input variables to customize the template. {: shortdesc} IBM Cloud Schematics is deprecating older versions of Terraform and introducing support for newer Terraform version. For more information, see the [Schematics Terraform deprecation lifecycle](https://cloud.ibm.com/docs/schematics?topic=schematics-deprecate-tf-version&format=markdown#deprecate-phase) and the [Deprecation Schedule](https://cloud.ibm.com/docs/schematics?topic=schematics-deprecate-tf-version&format=markdown#deprecate-timeline). {: deprecated} ## Before you begin {: #prerequisites-create} - [Create a Terraform configuration](https://cloud.ibm.com/docs/schematics?topic=schematics-create-tf-config&format=markdown), and store the configuration in a `GitHub`, `GitLab`, or `Bitbucket` repository. You can also upload a tape archive file (`.tar`) from your local workstation to provide your template to IBM Cloud Schematics. For more information, see the [`ibmcloud schematics workspace upload`](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-cli-reference&format=markdown#schematics-workspace-upload) command and see the [upload a `tar` file to your workspace](https://cloud.ibm.com/apis/schematics#template-repo-upload) API. - Make sure that you have the [permissions](https://cloud.ibm.com/docs/schematics?topic=schematics-access&format=markdown) to create a workspace. Ensure the `location` and the `url` endpoint are pointing to the same region when you create or update the Schematics workspaces and actions. For more information about location and endpoint, see [Where is your information stored](https://cloud.ibm.com/docs/schematics?topic=schematics-secure-data&format=markdown#pi-location)? {: note} ## Creating a workspace using the UI {: #create-wks-ui} {: ui} 1. Log in to [IBM Cloud console](https://cloud.ibm.com/){: external}. 2. Click the **Menu** icon ![hamburger icon](../images/icon_hamburger.svg) > **Platform Automation** > **Schematics** > **Terraform** > [**Create workspace**](https://cloud.ibm.com/schematics/workspaces/create){: external}. - In **Specify Template** section: - **GitHub, GitLab, or `Bitbucket` repository URL** - ``. You can click the `Open reference picker` to select a your Secrets Manager key reference. For more information, see [creating a Secrets Manager instance](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-create-instance&format=markdown). - Terraform Version - `terraform_v1.4`. You need to select Terraform version 1.4 or greater version. For example, if your Terraform templates are created by using Terraform v1.4, select the `Terraform version` parameter as **terraform_v1.4**. You can select `Terraform_v1.5` to use Terraform version 1.5, `terraform_v1.4` to use Terraform version 1.4. When you specify `terraform_v1.5` means that users can have Terraform `v1.5.0`, `v1.5.1`, or `v1.5.7`, so on. Schematics supports `Terraform_v1.x` and also plans to make releases available after `30 to 45 days` of HashiCorp Configuration Language (HCL) release. {: note} Schematics supports the current release of `Terraform v1.4`, through `Terraform_v1.6`. The Terraform must use the version constraint, such as `>` or `>=` or `~>` for the `required_version` of Terraform, to automatically pick the current version. ```terraform terraform { required_version = "~> 1.1" } ``` {: pre} - Click `Next`. - In **Workspace details** section. Enter a name for your `workspace name`. The name can be up to 128 characters long and can include alphanumeric characters, spaces, dashes, and underscores. - **Workspace name** as `schematics-agent-service`. - **Tags** as `my-tags`. Optional: Enter tags for your workspace. You can use the tags later to find your workspace faster. - **Resource group** as `default` or other resource group for this workspace. - **Location** as `North America` or other [region](https://cloud.ibm.com/docs/schematics?topic=schematics-multi-region-deployment&format=markdown) for this workspace. Decide where you want to create your workspace? The location determines where your Schematics jobs run?, and where your workspace data is stored? You can choose between a location, such as North America, or a metro city, such as Frankfurt or London. If you select a location, Schematics determines the location based on availability. If you select a metro city, your workspace is created in this location. For more information about where your data is stored, see [Where is your information stored](https://cloud.ibm.com/docs/schematics?topic=schematics-secure-data&format=markdown#pi-location)? The location that you choose is independent from the region or regions where you want to provision your Cloud resources. The console does not support all available locations. To create the workspace in a different location, use the [CLI](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-cli-reference&format=markdown#schematics-workspace-new) or [API](https://cloud.ibm.com/apis/schematics#create-workspace) instead. - Optional: enter a descriptive name for your workspace. - Click `Next`. - Click `Create`. Your workspace is created with a **Draft** state and the workspace **Settings** page opens. ### Importing your Terraform template {: #import-template} {: ui} If you want to upload a tape archive file (`.tar`) instead of importing your workspace to a Git repository, you must use the [`ibmcloud schematics workspace upload`](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-cli-reference&format=markdown#schematics-workspace-upload) command and see the [upload a tar file to your workspace](https://cloud.ibm.com/apis/schematics#template-repo-upload) API. {: tip} 1. On the workspace **Settings** page, enter the edit icon to edit your `Repository URL`. The link can point to the `master` branch, any other branch, or a subdirectory. - Example for `master` branch: `https://github.com/myorg/myrepo` - Example for other branches: `https://github.com/myorg/myrepo/tree/mybranch` - Example for subdirectory: `https://github.com/mnorg/myrepo/tree/mybranch/mysubdirectory` 2. If you want to use a private Git repository, enter your personal access token. The personal access token is used to authenticate with your Git repository to access your Terraform template. You can click the `Open reference picker` to select a your Secrets Manager key reference. For more information, see [Creating a personal access token for the command-line](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). And to securely validate and clone the template, you can click the `Open reference picker` to select your Secrets Manager key reference. For more information, see [creating a Secrets Manager instance](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-create-instance&format=markdown). 3. Select the `Terraform version` that your Terraform configuration files are written in. 4. Click the checkbox `I understand the changes that could happen if I edit this URL and I agree to these happening` option. 5. Click **Save**. IBM Cloud Schematics automatically downloads the Terraform configuration files from your repository, scans them for syntax errors, and retrieves all input variables that you declared in your configuration files. When all configuration files are downloaded successfully and no syntax errors are found, the workspace state changes to **Inactive**. After your Terraform configuration files are scanned, you can view the results on the workspace **Activity** page. The total number of files that were scanned in the source repository is displayed as `scanned`. The total number of files that are vulnerable, such as unsupported file extensions, is displayed as `discarded`. Click **Jobs** to find the details of the files that were scanned and discarded. For more information about viewing logs, see [Reviewing the Schematics job details](https://cloud.ibm.com/docs/schematics?topic=schematics-interrupt-job&format=markdown#sch-job-logs). {: tip} 6. Review the default input variable values for your Terraform template. To change an input variable value, click **Edit** from the Workspace actions menu. Depending on the data type that your variable uses, you must enter the value in a specific format. see the following table to find example values for each supported data type. | Type | Example | | --- | -- | | `number` | 4.56 | | `string` | example value | | `bool` | false | | `map(string)` | {key1 = "value1", key2 = "value2"} | | `set(string)` | ["hello", "he"] | | `map(number)` | {internal = 8080, external = 2020} | | `list(string)` | ["us-south", "eu-gb"] | | `list` | ["value", 30] | | `list(list(string))` | :[{internal = 8300 external = 8300 protocol = `"tcp"`},{internal = 8301 external = 8301 protocol = `"ldp"` } ] : list(object({internal = number external = number protocol = string})) : [{internal = 8300 external = 8300 protocol = `"tcp"`} {internal = 8301 external = 8301 protocol = `"ldp"`}]| {: caption="Input variables and its sample values" caption-side="bottom"} ### Using Terraform templates in IBM Cloud {: #run-template} {: ui} You can [Manage Cloud resources with Schematics](https://cloud.ibm.com/docs/schematics?topic=schematics-manage-lifecycle&format=markdown) to start creating, updating, or deleting Cloud resources with Terraform. ## Creating a workspace using the CLI {: #create-wks-cli} {: cli} 1. Create a JSON file on your local workstation and add your workspace configuration. For more configuration options when creating the workspace, see the [`ibmcloud schematics workspace new` command](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-cli-reference&format=markdown#schematics-workspace-new). To create a workspace with Agent, refer to [ibmcloud schematics workspace new with Agent](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-cli-reference&format=markdown#schematics-workspace-new) command. {: note} ```json { "name": "", "type": [ "" ], "location": "", "description": "", "tags": [], "template_repo": { "url": "" "branch": "master" }, "template_data": [ { "folder": ".", "type": "", "variablestore": [ { "name": "", "value": "", "type": "string", "secure": true }, { "name": "", "value": "", "type": "bool", "secure": false } ] } ] } ``` {: codeblock} | Parameter | Description | | --- | --- | | `workspace_name` | Enter a name for your workspace. The maximum length of character limit is set to 1 MB. For more information, see [Designing your workspace structure](https://cloud.ibm.com/docs/schematics?topic=schematics-workspaces-plan&format=markdown#structure-workspace). | | `terraform_version` | The Terraform version that you want to use to run your Terraform code. To use Terraform `version 1.4`, enter `terraform_v1.4`, and similarly `terraform_v1.5`, and `terraform_v1.6`. Make sure that your Terraform config files are compatible with the Terraform version that you specify. If the Terraform variable version is not specified. by default, Schematics selects the version from your template. | | `location` | Enter the location where you want to create your workspace. The location determines where your Schematics actions run and where your workspace data is stored. The location is independent from the region where you want to create your IBM Cloud services. | | `description` | Enter a description for your workspace. | | `github_source_repo_url` | Enter the URL to the GitHub or GitLab repository where your Terraform configuration files are stored. If you choose to create your workspace without a GitHub repository, your workspace is created with a **draft** state. To connect your workspace to a GitHub repository later, you must use the `ibmcloud schematics workspace update` command. | | `variable_name` | Optional: enter the name for the input variable that you declared in your Terraform configuration files. | | `variable_type` | Optional: enter the data type of your input variable. For supported data types, see the [`ibmcloud schematics workspace new` command](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-cli-reference&format=markdown#schematics-workspace-new). | {: caption="JSON file component description" caption-side="bottom"} 2. Create the workspace. ```sh ibmcloud schematics workspace new --file workspace.json ``` {: pre} 3. Verify that your workspace is created. Make sure that your workspace is in an **Inactive** state. ```sh ibmcloud schematics workspace list ``` {: pre} 4. Refer to, [Managing Cloud resources with Schematics](https://cloud.ibm.com/docs/schematics?topic=schematics-manage-lifecycle&format=markdown) to update or delete Cloud resources with Terraform. ## Creating a workspace using API {: #create-wks-api} {: api} 1. Follow the [steps](https://cloud.ibm.com/docs/schematics?topic=schematics-setup-api&format=markdown#cs_api) to retrieve your IAM access token and authenticate with IBM Cloud Schematics by using the API. 2. Create the workspace by using Terraform. ```sh curl --request POST --url https://schematics.cloud.ibm.com/v1/workspaces -H "Authorization: " -d '{"name": "","type": [""],"location": "","description": "","template_repo": {"url": ""},"template_data": [{"folder": ".","type": "","variablestore": [{"value": "","name": "","type": "","secure": true}]}]}' ``` {: pre} | Parameter | Description | | ----- | ----- | | `iam_access_token` | Enter the IAM access token that you retrieved in step 1. | | `workspace_name` | Enter a name for your workspace. The maximum length of character limit is set to 1 MB. For more information, see [Designing your workspace structure](https://cloud.ibm.com/docs/schematics?topic=schematics-workspaces-plan&format=markdown#structure-workspace). | | `terraform_version` | The Terraform version that you want to use to run your Terraform code. Enter `terraform_v1.4` to use Terraform version 1.4, and similarly `terraform_v1.5`, and `terraform_v1.6`. Make sure that your Terraform config files are compatible with the Terraform version that you specify. If the Terraform variable version is not specified, by default, Schematics selects the version from your template.| | `location` | Enter the location where you want to create your workspace. The location determines where your Schematics actions run and where your workspace data is stored. The location is independent from the region where you want to create your IBM Cloud services. | | `description` | Enter a description for your workspace. | | `github_source_repo_url` | Enter the URL to the GitHub or GitLab repository where your Terraform configuration files are store | | `variable_name` | Optional: enter the name for the input variable that you declared in your Terraform configuration files. | | `variable_value` | Optional: enter the value for your input variable. | | `variable_type` | Optional: enter the data type of your input variable. For supported data types, see the [`ibmcloud schematics workspace new` command](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-cli-reference&format=markdown#schematics-workspace-new). | {: caption="JSON file component description" caption-side="bottom"} 3. Verify that the workspace is created successfully. ```sh curl -X GET https://schematics.cloud.ibm.com/v1/workspaces -H "Authorization: " ``` {: pre} 4. See [Managing Cloud resources with Schematics](https://cloud.ibm.com/docs/schematics?topic=schematics-manage-lifecycle&format=markdown) to update, or delete the Cloud resources. ## Creating workspace using Terraform {: #create-wks-terraform} {: terraform} 1. Follow the steps in [Setting up Terraform for Schematics](https://cloud.ibm.com/docs/schematics?topic=schematics-terraform-setup&format=markdown) to create your workspace with Terraform. 2. See [Managing Cloud resources with Schematics](https://cloud.ibm.com/docs/schematics?topic=schematics-manage-lifecycle&format=markdown) to update, or delete the Cloud resources. ## Next steps {: #sch-create-wks-nextsteps} The next stage of working with workspaces is [deploying workspaces](https://cloud.ibm.com/docs/schematics?topic=schematics-sch-deploy-wks&format=markdown).