Stopping or terminating running jobs

After invoking a workspace job, like a plan, an apply, or a destroy, you may want to stop the running job, or to stop the provisioning of resources. When stopping, or canceling a long running job, it is advisable to first check the job logs to determine whether the job is actually stuck and needs stopping, or if it is performing long running operations that are taking time to complete.

Schematics provides a number of options to allows users to (gracefully) stop, force-stop, or terminate the running job in order of immediacy and impact of the stop operation.

Stop job types

The table provides the list of stop job types:

Types of job stop
Types	Description
`stop`	Sends an interrupt signal to the running Terraform command. This performs the same function as when running Terraform standalone, where an `interrupt` is sent using `cntl-C` or similar to Terraform. Interrupt signals can be sent multiple times to notify Terraform to stop. Terraform attempts to stop the running command (plan, apply, delete) after any executing resource operations have been completed and clean up. Schematics waits for the command to complete. After the command is stopped or finished, state and log files are collected and saved.
`force-stop`	Sends a kill signal to the Terraform command running. Use this in the case where you want to kill the Terraform command after seeing that the stop command (interrupts) are not stopping the command. A `force-stop` can be sent as many times as wanted until the command completes and job stops. If it is able to respond to the kill signal, Terraform stops the running command and resource operations immediately and clean up. After the command is stopped or finished, state file and log files are collected and saved.
`terminate`	If the previous operations fail, terminate immediately stops the Schematics job. The job is marked as `STOPPED` and the workspace unlocked. Any previously saved copies of the logs and `statefile` are preserved. When a job is terminated, the job is killed without collecting any files separately at the end. This option may result in data loss of log file and latest `statefile` updates and should be used carefully.

Until the job stops, you can send any number of these stop signals. Typically, you should not send more than three signals. If the Terraform does not respond to stop requests (interrupt signals), you can always use force-stop. If force-stop does not respond due to some issue in the job, you can always terminate the job to block.

Canceling a job

If the job is in a pending state, any type of stop request causes the job to cancel. The Cancel button shows up if the job is in a pending state, when it can be simply cancel. Cancel removes the job from the pending queue. If the plan, apply, or destroy execution is started in the meanwhile, which becomes a stop (interrupt) signal to Terraform.

Stopping a running job using the UI

You can follow these steps to stop a running workspace job by using the console.

From the Workspaces dashboard, select the workspace related to the running job.

You can stop or cancel the running job during a plan, an apply, or a destroy execution.

Click Job tab to view Stop, Force stop, Terminate, and Cancel button.

Stop job options
Button	Description
Stop	Removes the job from the pending queue, if it is in pending state. Otherwise, sends an interrupt signal to the Terraform command.
Force stop	Sends a kill signal to the Terraform command running.
Terminate	Terminates the Schematics job and marks the job as STOPPED and unlocks the workspace. This command should be used carefully as it can result in data loss.
Cancel	The `Cancel` button shows up if the job is in `pending` state, when it can be simply canceled. Cancel removes the job from the pending queue. If the `plan`, `apply`, or `destroy` execution is started in the meanwhile, this end up become an interrupt signal to the Terraform execution.

Type your <option> name in Type option to confirm text box.
Click Confirm option button.

Stopping a running job using the CLI

Stops a running IBM Cloud Schematics workspace job.

Syntax

ibmcloud schematics workspace job stop --id WORKSPACE_ID --job-id JOB_ID [--stop] [--force-stop] [--terminate] [--no-prompt]

Command options

Schematics job stop flags
Flag	Required / Optional	Description
`--id` or `-i`	Required	The workspace ID to update.
`--job-id` or `--jid`	Required	The job ID of the job.
`--stop`	Optional	Removes the job from the pending queue, if it is in pending state. Otherwise, sends an interrupt signal to the Terraform command.
`--force-stop` or `--fs`	Optional	Sends a kill signal to the Terraform execution in the engine attempting to immediately stop the execution.
`--terminate` or `-t`	Optional	Abruptly kills the engine, marks the job as stopped, and unlocks your workspace. Data is not saved using this flag.
`--no-prompt`	Optional	Set this flag to run the command without an interactive mode.

Example

ibmcloud schematics workspace job stop --id <WORKSPACE_ID> --stop --job-id <JOB_ID>

ibmcloud schematics workspace job stop --id <WORKSPACE_ID> --force-stop --job-id <JOB_ID>

ibmcloud schematics workspace job stop --id <WORKSPACE_ID> --terminate --job-id <JOB_ID>

Stopping a running job through API

You can use following cURL commands to stop a running job for IBM Cloud Schematics workspace.

Syntax to stop running jobs

Set up your REST client to execute Schematics API.

Use the syntax and example to stop the running job.

Syntax

curl -X DELETE https://schematics.cloud.ibm.com/v1/workspaces/<wks_id>/actions/{job_id}?signal=interrupt -H "Authorization: <iam_token>"

Example

curl -X DELETE https://schematics.cloud.ibm.com/v2/jobs/{job_id}?signal=interrupt -H "Authorization: <iam_token>"

Use the example to force-stop the running job.

Example

curl -X DELETE https://schematics.cloud.ibm.com/v1/workspaces/<wks_id>/actions/{job_id}?signal=force-stop -H "Authorization: <iam_token>"

Use the example to terminate the running job.

Example
```
curl -X DELETE https://schematics.cloud.ibm.com/v1/workspaces/<wks_id>/actions/{job_id}?signal=terminate -H "Authorization: <iam_token>"
```
For more information about stopping the running job, see Stop and delete the running Job API.

Reviewing the Schematics job details

Use the Schematics job page in the console to find the history of all Schematics activities, such as downloading your template, plan, apply, and to see the logs of the jobs. The jobs are created when you run your templates. You can also see the count of the resources that are in plan, or apply jobs that are in added, modified, or destroyed status. For more information about job queue process, see Execution process of the Schematics job queue.

In the job log you can see a message such as:

Activity triggered. Waiting for the logs. This means the job is in pending status and yet to be processed.
Your job was submitted and is in queue, at position x out of y. Here x is the position of your job in the pending queue and y is a total pending jobs. The available resources in Schematics backend are equally distributed to the pending jobs. In case you are running a huge number of jobs, you can view the position increase along with the total.