--- name: schematics-sc-workspaces-plan title: Running a workspace plan description: A workspace plan, performs a Terraform plan to determine the IBM Cloud® resources that are created, modified or deleted on any subsequent workspace apply operation. Run the Schematics plan job against your workspace. You can use the plan summary logs to verify any resource changes before the template is applied. 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. # Running a workspace plan {: #sch-plan-wks} A workspace plan, performs a Terraform plan to determine the IBM Cloud® resources that are created, modified or deleted on any subsequent workspace apply operation. Run the Schematics plan job against your workspace. You can use the plan summary logs to verify any resource changes before the template is applied. {: 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 {: #plan-prerequisites} - [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 copy of the repo as a `tar` (tape archive file) 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 list 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)? - Run a Schematics plan job against your workspace. An plan job calculates which resources are provisioned, modified, or removed. This process might take a few minutes. During workspace plan execution, you cannot edit your workspace. {: note} ## Generate a workspace plan using the UI {: #plan-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**](https://cloud.ibm.com/automation/schematics/terraform){: external}. 3. Click your workspace name. 4. Click **Generate Plan** to create a plan for the workspace. ### Verifying workspace plan {: #verify-wks-plan-ui} 1. Click on your workspace that is listed in the [IBM Cloud console](https://cloud.ibm.com/automation/schematics/terraform){: external} 2. Click **Jobs** to see the job execution results. It are listed under the heading `Generate Plan` 3. On a successful plan, the cost for the proposed changes is reviewed by clicking on the `Cost Estimate` button. For more information, see [Infrastructure cost estimation](https://cloud.ibm.com/docs/schematics?topic=schematics-cost-estimation&format=markdown). ## Generate a workspace plan using the CLI {: #plan-wks-cli} {: cli} 1. Create a JSON file on your system and plan your workspace configuration. For more information about configuration options, see [`ibmcloud schematics workspace new`](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-cli-reference&format=markdown#schematics-workspace-new) command. Example ```json { "name": "testwspace31jan", "type": [ "terraform_v1.4" ], "description": "terraform workspace", "location": "us-east", "tags": [ "department:HR", "application:compensation", "environment:production" ], "template_repo": { "url": "https://github.com/Anil-CM/newrepo" }, "workspace_status": { "frozen": true }, "template_data": [{ "folder": ".", "type": "terraform_v1.4", "variablestore": [{ "name": "sample_var", "secure": true, "value": "THIS IS IBM CLOUD TERRAFORM CLI DEMO", "description": "Description of sample_var" }, { "name": "sleepy_time", "value": "15" } ] }] } ``` {: codeblock} Syntax ```sh ibmcloud schematics plan --id WORKSPACE_ID [--output OUTPUT] [--var-file PATH_TO_VARIABLES_FILE] [--var-file PATH_TO_VARIABLES_FILE] [] ``` {: pre} For more information about syntax and arguments flags, see [`ibmcloud schematics plan`](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-cli-reference&format=markdown#schematics-plan) command. {: note} 2. Verify that your workspace plan is applied. Make sure that your workspace is in an **Inactive** state. ```sh ibmcloud schematics workspace list ``` {: pre} 3. Refer to, [Managing Cloud resources with Schematics](https://cloud.ibm.com/docs/schematics?topic=schematics-manage-lifecycle&format=markdown) to view job logs. ### Verifying workspace plan execution {: #verify-wks-plan-cli} Execute CLI command to check the status of the workspace plan is success. ```sh ibmcloud schematics workspace list ``` {: pre} ```text Retrieving workspaces... Name ID Description Version Status Frozen testwspace31jan us-east.workspace.testwspace31jan.a31438c6 terraform workspace Terraform v1.0.11 INACTIVE True OK ``` {: screen} On successful plan returns the update details of an existing workspace. For more information about FAQ, see [troubleshooting section](https://cloud.ibm.com/docs/schematics?topic=schematics-wks-create-api&interface=cli&format=markdown). ## Generate a workspace plan using the API {: #plan-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. Generate plan for the existing workspace. Example ```json POST /v1/workspaces/{w_id}/plan HTTP/1.1 Host: schematics.cloud.ibm.com Content-Type: application/json Authorization: Cache-Control: no-cache Postman-Token: bdc869fd-dc7c-06a6-5e99-4de6e3aa7dd9 { "name": "testwspace31jan", "type": [ "terraform_v1.4" ], "description": "terraform workspace", "location": "us-east", "tags": [ "department:HR", "application:compensation", "environment:production" ], "template_repo": { "url": "" }, "workspace_status": { "frozen": true }, "template_data": [{ "folder": ".", "type": "terraform_v1.4", "variablestore": [{ "name": "sample_var", "secure": true, "value": "THIS IS IBM CLOUD TERRAFORM CLI DEMO", "description": "Description of sample_var" }, { "name": "sleepy_time", "value": "15" } ] }] } ``` {: codeblock} 3. See [Managing Cloud resources with Schematics](https://cloud.ibm.com/docs/schematics?topic=schematics-manage-lifecycle&format=markdown) to create, update, or delete Cloud resources with Terraform. ### Verifying workspace plan execution {: #verify-wks-plan-api} Verify that the workspace plan is successfully listed with the list of workspace jobs that were created. {: shortdesc} ```sh curl -X GET https://schematics.cloud.ibm.com/v1/workspaces -H "Authorization: " ``` {: pre} Output ```text { "activityid": "3815ef757cd34030bc43191f7d7c6744" } ``` {: screen} On successful, returns the list of the workspace. For more information, see [FAQ](https://cloud.ibm.com/docs/schematics?topic=schematics-workspaces-faq&format=markdown), and [troubleshooting section](https://cloud.ibm.com/docs/schematics?topic=schematics-wks-create-api&format=markdown). ## Generating a workspace plan using Terraform {: #plan-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 start creating, updating, or deleting Cloud resources with Terraform. ## Next steps {: #sch-plan-wks-nextsteps} The next stage of working with workspace is [deploying workspaces](https://cloud.ibm.com/docs/schematics?topic=schematics-sch-deploy-wks&format=markdown). For more information, see [FAQ](https://cloud.ibm.com/docs/schematics?topic=schematics-workspaces-faq&format=markdown), and [troubleshooting section](https://cloud.ibm.com/docs/schematics?topic=schematics-wks-create-api&format=markdown).