IBM Cloud Docs
Running a workspace plan

Running a workspace plan

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.

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.

Before you begin

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?

  • 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.

Generate a workspace plan using the UI

  1. Log in to IBM Cloud.
  2. Access Schematics > Workspaces > workspace.
  3. Search your workspace in specific location.
  4. Click Workspaces > workspace.
  5. Click Generate Plan to create a plan for the workspace.

Verifying workspace plan

  1. Click on your workspace that is listed in the IBM Cloud console
  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.

Generate a workspace plan using the 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 command.

    Example

    {
	"name": "testwspace31jan",
	"type": [
		"terraform_v1.0"
	],
	"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.0",
		"variablestore": [{
				"name": "sample_var",
				"secure": true,
				"value": "THIS IS IBM CLOUD TERRAFORM CLI DEMO",
				"description": "Description of sample_var"
			},
			{
				"name": "sleepy_time",
				"value": "15"
			}
		]
	}]
}

    Syntax

    ibmcloud schematics plan --id WORKSPACE_ID [--output OUTPUT] [--var-file PATH_TO_VARIABLES_FILE] [--var-file PATH_TO_VARIABLES_FILE] []

    For more information about syntax and arguments flags, see ibmcloud schematics plan command.

  2. Verify that your workspace plan is applied. Make sure that your workspace is in an Inactive state.

    ibmcloud schematics workspace list

  3. Refer to, Managing IBM Cloud resources with Schematics to view job logs.

Verifying workspace plan execution

Execute CLI command to check the status of the workspace plan is success.

```sh {: pre}
ibmcloud schematics workspace list
```
```text {: screen}
Retrieving workspaces...
Name                                          ID                                                                       Description                                   Version             Status           Frozen
testwspace31jan                               us-east.workspace.testwspace31jan.a31438c6                               terraform workspace                           Terraform v1.0.11   INACTIVE         True

OK
```

On successful plan returns the update details of an existing workspace.

For more information about FAQ, see troubleshooting section.

Generate a workspace plan using the API

  1. Follow the steps to retrieve your IAM access token and authenticate with IBM Cloud Schematics by using the API.

  2. Generate plan for the existing workspace.

    Example

    
POST /v1/workspaces/{w_id}/plan HTTP/1.1
Host: schematics.cloud.ibm.com
Content-Type: application/json
Authorization: <auth-token>
Cache-Control: no-cache
Postman-Token: bdc869fd-dc7c-06a6-5e99-4de6e3aa7dd9

{
	"name": "testwspace31jan",
	"type": [
		"terraform_v1.0"
	],
	"description": "terraform workspace",
	"location": "us-east",
	"tags": [
		"department:HR",
		"application:compensation",
		"environment:production"
	],
	"template_repo": {
		"url": "<gitrepo-url>"
	},
	"workspace_status": {
		"frozen": true
	},
	"template_data": [{
		"folder": ".",
		"type": "terraform_v1.0",
		"variablestore": [{
				"name": "sample_var",
				"secure": true,
				"value": "THIS IS IBM CLOUD TERRAFORM CLI DEMO",
				"description": "Description of sample_var"
			},
			{
				"name": "sleepy_time",
				"value": "15"
			}
		]
	}]
}

  3. See Managing IBM Cloud resources with Schematics to create, update, or delete IBM Cloud resources with Terraform.

Verifying workspace plan execution

Verify that the workspace plan is successfully listed with the list of workspace jobs that were created.

curl -X GET https://schematics.cloud.ibm.com/v1/workspaces -H "Authorization: <iam_access_token>"

Output

{
    "activityid": "3815ef757cd34030bc43191f7d7c6744"
}

On successful, returns the list of the workspace.

For more information, see FAQ, and troubleshooting section.

Generating a workspace plan using Terraform

  1. Follow the steps in Setting up Terraform for Schematics to create your workspace with Terraform.

  2. See Managing IBM Cloud resources with Schematics to start creating, updating, or deleting IBM Cloud resources with Terraform.

Next steps

The next stage of working with workspace is deploying workspaces.

For more information, see FAQ, and troubleshooting section.