---
name: schematics-remotestate
title: Remote state and cross-workspace access
description: '- Integration of workspace and action operations with Actions. Workspace resource information can be directly passed as an Ansible dynamic inventory without the need for manual host inventory creation or use of inventory scripts.'
last-updated: 2025-04-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.

# Remote state and cross-workspace access
{: #remote-state}

IBM Cloud® provides built in [remote-state](https://developer.hashicorp.com/terraform/language/state/remote){: external} management for Terraform. Terraform state files are automatically preserved between runs and are accessible by IBM Cloud® commands and operations. IBM Cloud® remote-state management enables team work and workspace shared operations, with built in state locking preventing concurrent operations against the same state file.

The built in workspace remote-state management supports a number of Schematics use cases:

- The sharing of resource information between workspaces. This allows your infrastructure to be broken down into smaller components, with read-only resource information passed between environments using Schematics remote-state data sources. Discrete environments linked by data sources allows responsibility for different elements of infrastructure to be delegated to different teams with information shared between workspaces as read-only resources. 
- Integration of workspace and action operations with [Actions](https://cloud.ibm.com/docs/schematics?topic=schematics-action-working&format=markdown). Workspace resource information can be directly passed as an Ansible [dynamic inventory](https://cloud.ibm.com/docs/schematics?topic=schematics-inventories-setup&format=markdown#dynamic-inv) without the need for manual host inventory creation or use of inventory scripts.
{: shortdesc}

## Accessing workspace state and outputs
{: #data-sources}

You can access information about the resources that you manage in a workspace from other workspaces in your account by using the [`ibm_schematics_output`](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/data-sources/schematics_output){: external} and [`ibm_schematics_state`](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/data-sources/schematics_state){: external} data sources.

IBM Cloud® uses the `local` built-in Terraform state support and does not use Terraform [backend](https://developer.hashicorp.com/terraform/language){: external} support. No additional configuration is required within your `Terraform configs` to enable IBM Cloud® remote state management. Schematics does not use the Terraform `remote_state` data source, instead you use the `ibm_schematics_output` data source to access the information.

**How is the `ibm_schematics_state` data source different from the `remote_state` data source?** </br>
When you use the a `remote_state` data source, you must configure a  backend to connect to your workspaces. With the `ibm_schematics_state` data source, you automatically have access to the built-in Schematics backend and can access workspace information directly.

**What do I need to do to access resource information in other workspaces?** </br>
Similar to the `remote_state` data source, you can only access information that you configured as output values in your Terraform template. For example, let's say you have a workspace that you used to provision a VPC. To access the VPC ID, you must define the ID as an output variable in your Terraform configuration file.

**To use the `ibm_schematics_output` data source**:

1. Follow the example in the [getting started tutorial](https://cloud.ibm.com/docs/schematics?topic=schematics-getting-started&format=markdown) to create a Schematics workspaces and provision a virtual server in a VPC. As you follow the instructions, review the output variables that are defined at the end of the `vpc.tf` Terraform configuration file. 

    If you already used a different Terraform configuration file in one of your workspaces, you can use this workspace for the exercise. Make sure to add output values as outlined in this example to your configuration file so that you can access your workspace information later. 
    {: tip}

    ```terraform
    output sshcommand {
        value = "ssh root@ibm_is_floating_ip.fip1.address"
    }

    output vpc_id {
    value = ibm_is_vpc.vpc.id
    }
    ```
    {: screen}

    In this example, two output values are defined, the `sshcommand` to access the virtual server instance in your VPC and the `vpc_id`.

2. Retrieve the ID of the VPC workspace that you created.

    **Through console**:
    - From the [workspace dashboard ![External link icon](../icons/launch-glyph.svg "External link icon")](https://cloud.ibm.com/automation/schematics/terraform), select the VPC workspace.
    - Select the **Settings** tab.
    - Find the workspace ID in the **Summary** section.

    **Through CLI**:
    - List available workspaces in your account.
        ```sh
        ibmcloud schematics workspace list
        ```
        {: pre}

    - Find the workspace ID in the **ID** column of your command-line output.

    The Schematics `ibmcloud terraform` command usage displays warning and deprecation message as **Alias 'terraform' are deprecated. Use 'schematics' or 'sch' in your commands.**
    {: note}

3. Create another Terraform configuration file that is named `remotestate.tf` to access the output parameters of the `vpc.tf` file by using the `ibm_schematics_output` data source. To allow version control of this file, make sure to store this configuration file in a GitHub or GitLab repository.

    ```terraform
    data "ibm_schematics_workspace" "vpc" {
        workspace_id = "<schematics_workspace_ID>"
    }

    data "ibm_schematics_output" "vpc" {
        workspace_id = "<schematics_workspace_ID>"
        template_id = data.ibm_schematics_workspace.vpc.runtime_data.0.id
    }

    output "output_vars" {
        value = data.ibm_schematics_output.vpc.output_values
    }

    output "ssh_command" {
        value = data.ibm_schematics_output.vpc.output_values.sshcommand
    }

    output "vpc_id" {
        value = data.ibm_schematics_output.vpc.output_values.vpc_id
    }
    ```
    {: codeblock}

    | ![Idea icon](images/idea.png) | Understanding the configuration file components |
    | -- | -- |
    | `data.ibm_schematics_workspace.workspace_id` | Enter the ID of the VPC workspace where you defined the output values that you want to access. You need this data source to retrieve the template ID of the workspace in the `ibm_schematics_output` data source. |
    | `data.ibm_schematics_output.workspace_id` | Enter the ID of the VPC workspace where you defined the output values that you want to access. |
    | `data.ibm_schematics_output.template_id` | Enter `data.ibm_schematics_workspace.vpc.runtime_data.0.id` to reference the Terraform template of your workspace. |
    | `output.output_vars.value` | Use Terraform interpolation syntax to access all output values that you defined in the `vpc.tf` file by using the `output_values` output parameter of the `ibm_schematics_output` data source. The `output_values` output parameter returns all output values as a list. |
    | `output.sshcomand.value`  and `output.vpc_id.value` | You can access a specific value in the `output_values` list by adding the ID of the output value to your `ibm_schematics_output` data source. For example, to access the `vpc_id`, simply use `data.ibm_schematics_output.vpc.output_values.vpc_id`. |
    {: caption="Configuration file components" caption-side="bottom"}

4. [Create a workspace](https://cloud.ibm.com/docs/schematics?topic=schematics-sch-create-wks&interface=ui&format=markdown#create-wks-ui) that points to the `remotestate.tf` file in your GitHub or GitLab repository. If you want to upload a tape archive file (`.tar`) from your local machine instead, use the [`ibmcloud schematics workspace upload`](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-cli-reference&format=markdown#schematics-workspace-upload) command.

5. [Run your Terraform code in Schematics](https://cloud.ibm.com/docs/schematics?topic=schematics-manage-lifecycle&format=markdown#deploy-resources). When you review your logs, you can see the output values from your VPC workspace in the **Output** section.

    Example output

    ```text
    ...
    2020/02/21 19:49:30 Terraform show | Outputs:
    2020/02/21 19:49:30 Terraform show | 
    2020/02/21 19:49:30 Terraform show | Output_vars = {
    2020/02/21 19:49:30 Terraform show |   sshcommand = ssh root@169.61.225.111
    2020/02/21 19:49:30 Terraform show |   vpc_id = a1a11aa1-a111-a11a-a111-aa1aa11a1a1a
    2020/02/21 19:49:30 Terraform show | }
    2020/02/21 19:49:30 Terraform show | sshcommand = ssh root@169.61.225.111
    2020/02/21 19:49:30 Terraform show | vpc_id = a1a11aa1-a111-a11a-a111-aa1aa11a1a1a
    ```
    {: screen}