terraform Workspaces organize infrastructure into meaningful groups Learn how to create page title Create workspaces Workspaces HCP Terraform This topic describes how to create and manage workspaces in HCP Terraform and Terraform Enterprise UI A workspace is a group of infrastructure resources managed by Terraform Refer to Workspaces overview terraform cloud docs workspaces for additional information and configure workspaces through the UI Create workspaces

Answer:
---
page_title: Create workspaces - Workspaces - HCP Terraform
description: >-
  Workspaces organize infrastructure into meaningful groups. Learn how to create
  and configure workspaces through the UI.
---

# Create workspaces

This topic describes how to create and manage workspaces in HCP Terraform and Terraform Enterprise UI. A workspace is a group of infrastructure resources managed by Terraform. Refer to [Workspaces overview](/terraform/cloud-docs/workspaces) for additional information.

> **Hands-on:** Try the [Get Started - HCP Terraform](/terraform/tutorials/cloud-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials.

## Introduction

Create new workspaces when you need to manage a new collection of infrastructure resources.  You can use the following methods to create workspaces:

- HCP Terraform UI: Refer to [Create a workspace](#create-a-workspace) for instructions.
- Workspaces API: Send a `POST`call to the `/organizations/:organization_name/workspaces` endpoint to create a workspace. Refer to the [API documentation](/terraform/cloud-docs/api-docs/workspaces#create-a-workspace) for instructions.
- Terraform Enterprise provider: Install the `tfe` provider and add the `tfe_workspace` resource to your configuration. Refer to the [`tfe` provider documentation](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/workspace) in the Terraform registry for instructions.
- No-code provisioning: Use a no-code module from the registry to create a new workspace and deploy the module's resources. Refer to [Provisioning No-Code Infrastructure](/terraform/cloud-docs/no-code-provisioning/provisioning) for instructions.

Each workspace belongs to a project. Refer to [Manage projects](/terraform/cloud-docs/projects/manage) for additional information.

## Requirements

You must be a member of a team with one of the following permissions enabled to create and manage workspaces:

- **Manage all projects**
- **Manage all workspaces**
- **Admin** permission group for a project.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

## Workspace naming

We recommend using consistent and informative names for new workspaces. One common approach is combining the workspace's important attributes in a consistent order. Attributes can be any defining characteristic of a workspace, such as the component, the component’s run environment, and the region where the workspace is provisioning infrastructure.

This strategy could produce the following example workspace names:
- networking-prod-us-east
- networking-staging-us-east
- networking-prod-eu-central
- networking-staging-eu-central
- monitoring-prod-us-east
- monitoring-staging-us-east
- monitoring-prod-eu-central
- monitoring-staging-eu-central

You can add additional attributes to your workspace names as needed. For example, you may add the infrastructure provider, datacenter, or line of business.

We recommend using 90 characters or less for the name of your workspace.

## Create a workspace

[workdir]: /terraform/cloud-docs/workspaces/settings#terraform-working-directory

[trigger]: /terraform/cloud-docs/workspaces/settings/vcs#automatic-run-triggering

[branch]: /terraform/cloud-docs/workspaces/settings/vcs#vcs-branch

[submodules]: /terraform/cloud-docs/workspaces/settings/vcs#include-submodules-on-clone

Complete the following steps to use the HCP Terraform or Terraform Enterprise UI to create a workspace:

1. Log in and choose your organization.
1. Click **New** and choose **Workspace** from the drop-down menu.
1. If you have multiple projects, HCP Terraform may prompt you to choose the project to create the workspace in. Only users on teams with permissions for the entire project or the specific workspace can access the workspace. Refer to [Manage projects](/terraform/cloud-docs/projects/manage) for additional information.
1. Choose a workflow type.
1. Complete the following steps if you are creating a workspace that follows the VCS workflow:
   1. Choose an existing version control provider from the list or configure a new system. You must enable the workspace project to connect to your provider. Refer to [Connecting VCS
      Providers](/terraform/cloud-docs/vcs) for more details.
   1. If you choose the **GitHub App** provider, choose an organization and repository when prompted. The list only displays the first 100 repositories from your VCS provider. If your repository is missing from the list, enter the repository ID in the text field .
   1. Refer to the following topics for information about configuring workspaces settings in the **Advanced options** screen:
      - [Terraform Working Directory][workdir]
      - [Automatic Run Triggering][trigger]
      - [VCS branch][branch]
      - [Include submodules on clone][submodules]
1. Specify a name for the workspace. VCS workflow workspaces default to the name of the repository. The name must be unique within the organization and can include letters, numbers, hyphens, and underscores. Refer to [Workspace naming](#workspace-naming) for additional information.
1. Add an optional description for the workspace. The description appears at the top of the workspace in the HCP Terraform UI.
1. Click **Create workspace** to finish.

For CLI or API-driven workflow, the system opens the new workspace overview. For version control workspaces, the **Configure Terraform variables** page appears.

### Configure Terraform variables for VCS workflows

After you create a new workspace from a version control repository, HCP Terraform scans its configuration files for [Terraform variables](/terraform/cloud-docs/workspaces/variables#terraform-variables) and displays variables without default values or variables that are undefined in an existing [global or project-scoped variable set](/terraform/cloud-docs/workspaces/variables/managing-variables#variable-sets). Terraform cannot perform successful runs in the workspace until you set values for these variables.

Choose one of the following actions:

- To skip this step, click **Go to workspace overview**. You can [load these variables from files](/terraform/cloud-docs/workspaces/variables/managing-variables#loading-variables-from-files) or create and set values for them later from within the workspace. HCP Terraform does not automatically scan your configuration again; you can only add variables from within the workspace individually.
- To configure variables, enter a value for each variable on the page. You may want to leave a variable empty if you plan to provide it through another source, like an `auto.tfvars` file. Click **Save variables** to add these variables to the workspace.

## Next steps

If you have already configured all Terraform variables, we recommend [manually starting a run](/terraform/cloud-docs/run/ui#manually-starting-runs) to prepare VCS-driven workspaces. You may also want to do one or more of the following actions:

- [Upload configuration versions](/terraform/cloud-docs/workspaces/configurations#providing-configuration-versions): If you chose the API or CLI-Driven workflow, you must upload configuration versions for the workspace.
- [Edit environment variables](/terraform/cloud-docs/workspaces/variables): Shell environment variables store credentials and customize Terraform's behavior.
- [Edit additional workspace settings](/terraform/cloud-docs/workspaces/settings): This includes notifications, permissions, and run triggers to start runs automatically.
- [Learn more about running Terraform in your workspace](/terraform/cloud-docs/run/remote-operations): This includes how Terraform processes runs within the workspace, run modes, run states, and other operations.
- [Create workspace tags](/terraform/cloud-docs/workspaces/tags): Add tags to your workspaces so that you can organize and track them.
- [Browse workspaces](/terraform/cloud-docs/workspaces/browse): Use the interfaces available in the UI to browse, sort, and filter workspaces so that you can track resource consumption.

### VCS Connection

If you connected a VCS repository to the workspace, HCP Terraform automatically registers a webhook with your VCS provider. A workspace with no runs will not accept new runs from a VCS webhook, so you must [manually start at least one run](/terraform/cloud-docs/run/ui#manually-starting-runs).

After you manually start a run, HCP Terraform automatically queues a plan when new commits appear in the selected branch of the linked repository or someone opens a pull request on that branch. Refer to [Webhooks](/terraform/cloud-docs/vcs#webhooks) for more details.

page title  Create workspaces   Workspaces   HCP Terraform description       Workspaces organize infrastructure into meaningful groups  Learn how to create   and configure workspaces through the UI         Create workspaces  This topic describes how to create and manage workspaces in HCP Terraform and Terraform Enterprise UI  A workspace is a group of infrastructure resources managed by Terraform  Refer to  Workspaces overview   terraform cloud docs workspaces  for additional information       Hands on    Try the  Get Started   HCP Terraform   terraform tutorials cloud get started utm source WEBSITE utm medium WEB IO utm offer ARTICLE PAGE utm content DOCS  tutorials      Introduction  Create new workspaces when you need to manage a new collection of infrastructure resources   You can use the following methods to create workspaces     HCP Terraform UI  Refer to  Create a workspace   create a workspace  for instructions    Workspaces API  Send a  POST call to the   organizations  organization name workspaces  endpoint to create a workspace  Refer to the  API documentation   terraform cloud docs api docs workspaces create a workspace  for instructions    Terraform Enterprise provider  Install the  tfe  provider and add the  tfe workspace  resource to your configuration  Refer to the   tfe  provider documentation  https   registry terraform io providers hashicorp tfe latest docs resources workspace  in the Terraform registry for instructions    No code provisioning  Use a no code module from the registry to create a new workspace and deploy the module s resources  Refer to  Provisioning No Code Infrastructure   terraform cloud docs no code provisioning provisioning  for instructions   Each workspace belongs to a project  Refer to  Manage projects   terraform cloud docs projects manage  for additional information       Requirements  You must be a member of a team with one of the following permissions enabled to create and manage workspaces       Manage all projects       Manage all workspaces       Admin   permission group for a project    permissions citation    intentionally unused   keep for maintainers     Workspace naming  We recommend using consistent and informative names for new workspaces  One common approach is combining the workspace s important attributes in a consistent order  Attributes can be any defining characteristic of a workspace  such as the component  the component s run environment  and the region where the workspace is provisioning infrastructure   This strategy could produce the following example workspace names    networking prod us east   networking staging us east   networking prod eu central   networking staging eu central   monitoring prod us east   monitoring staging us east   monitoring prod eu central   monitoring staging eu central  You can add additional attributes to your workspace names as needed  For example  you may add the infrastructure provider  datacenter  or line of business   We recommend using 90 characters or less for the name of your workspace      Create a workspace   workdir    terraform cloud docs workspaces settings terraform working directory   trigger    terraform cloud docs workspaces settings vcs automatic run triggering   branch    terraform cloud docs workspaces settings vcs vcs branch   submodules    terraform cloud docs workspaces settings vcs include submodules on clone  Complete the following steps to use the HCP Terraform or Terraform Enterprise UI to create a workspace   1  Log in and choose your organization  1  Click   New   and choose   Workspace   from the drop down menu  1  If you have multiple projects  HCP Terraform may prompt you to choose the project to create the workspace in  Only users on teams with permissions for the entire project or the specific workspace can access the workspace  Refer to  Manage projects   terraform cloud docs projects manage  for additional information  1  Choose a workflow type  1  Complete the following steps if you are creating a workspace that follows the VCS workflow      1  Choose an existing version control provider from the list or configure a new system  You must enable the workspace project to connect to your provider  Refer to  Connecting VCS       Providers   terraform cloud docs vcs  for more details     1  If you choose the   GitHub App   provider  choose an organization and repository when prompted  The list only displays the first 100 repositories from your VCS provider  If your repository is missing from the list  enter the repository ID in the text field      1  Refer to the following topics for information about configuring workspaces settings in the   Advanced options   screen           Terraform Working Directory  workdir           Automatic Run Triggering  trigger           VCS branch  branch           Include submodules on clone  submodules  1  Specify a name for the workspace  VCS workflow workspaces default to the name of the repository  The name must be unique within the organization and can include letters  numbers  hyphens  and underscores  Refer to  Workspace naming   workspace naming  for additional information  1  Add an optional description for the workspace  The description appears at the top of the workspace in the HCP Terraform UI  1  Click   Create workspace   to finish   For CLI or API driven workflow  the system opens the new workspace overview  For version control workspaces  the   Configure Terraform variables   page appears       Configure Terraform variables for VCS workflows  After you create a new workspace from a version control repository  HCP Terraform scans its configuration files for  Terraform variables   terraform cloud docs workspaces variables terraform variables  and displays variables without default values or variables that are undefined in an existing  global or project scoped variable set   terraform cloud docs workspaces variables managing variables variable sets   Terraform cannot perform successful runs in the workspace until you set values for these variables   Choose one of the following actions     To skip this step  click   Go to workspace overview    You can  load these variables from files   terraform cloud docs workspaces variables managing variables loading variables from files  or create and set values for them later from within the workspace  HCP Terraform does not automatically scan your configuration again  you can only add variables from within the workspace individually    To configure variables  enter a value for each variable on the page  You may want to leave a variable empty if you plan to provide it through another source  like an  auto tfvars  file  Click   Save variables   to add these variables to the workspace      Next steps  If you have already configured all Terraform variables  we recommend  manually starting a run   terraform cloud docs run ui manually starting runs  to prepare VCS driven workspaces  You may also want to do one or more of the following actions      Upload configuration versions   terraform cloud docs workspaces configurations providing configuration versions   If you chose the API or CLI Driven workflow  you must upload configuration versions for the workspace     Edit environment variables   terraform cloud docs workspaces variables   Shell environment variables store credentials and customize Terraform s behavior     Edit additional workspace settings   terraform cloud docs workspaces settings   This includes notifications  permissions  and run triggers to start runs automatically     Learn more about running Terraform in your workspace   terraform cloud docs run remote operations   This includes how Terraform processes runs within the workspace  run modes  run states  and other operations     Create workspace tags   terraform cloud docs workspaces tags   Add tags to your workspaces so that you can organize and track them      Browse workspaces   terraform cloud docs workspaces browse   Use the interfaces available in the UI to browse  sort  and filter workspaces so that you can track resource consumption        VCS Connection  If you connected a VCS repository to the workspace  HCP Terraform automatically registers a webhook with your VCS provider  A workspace with no runs will not accept new runs from a VCS webhook  so you must  manually start at least one run   terraform cloud docs run ui manually starting runs    After you manually start a run  HCP Terraform automatically queues a plan when new commits appear in the selected branch of the linked repository or someone opens a pull request on that branch  Refer to  Webhooks   terraform cloud docs vcs webhooks  for more details


terraform page title JSON Filtering HCP Terraform viewer terraform cloud docs workspaces state and policy check JSON data About JSON Data Filtering Certain pages where JSON data is displayed such as the state viewer terraform cloud docs policy enforcement sentinel json allow you to filter the results This Learn how to create custom datasets on pages that display JSON data

Answer:
---
page_title: JSON Filtering - HCP Terraform
description: Learn how to create custom datasets on pages that display JSON data.
---

# About JSON Data Filtering

Certain pages where JSON data is displayed, such as the [state
viewer](/terraform/cloud-docs/workspaces/state) and [policy check JSON data
viewer](/terraform/cloud-docs/policy-enforcement/sentinel/json), allow you to filter the results. This
enables you to see just the data you need, and even create entirely new datasets
to see data in the way you want to see it!

![entering a json filter](/img/docs/json-viewer-intro.png)

-> **NOTE:** _Filtering_ the data in the JSON viewer is separate from
_searching_ it. To search, press Control-F (or Command-F on MacOS). You can
search and apply a filter at the same time.

## Entering a Filter

Filters are entered by putting the filter in the aptly named **filter** box in
the JSON viewer. After entering the filter, pressing **Apply** or the enter key
on your keyboard will apply the filter. The filtered results, if any, are
displayed in result box. Clearing the filter will restore the original JSON
data.

![entering a json filter](/img/docs/sentinel-json-enter-filter.png)

## Filter Language

The JSON filter language is a small subset of the
[jq](https://stedolan.github.io/jq/) JSON filtering language. Selectors,
literals, indexes, slices, iterators, and pipes are supported, as are also array
and object construction. At this time, parentheses, and more complex operations
such as mathematical operators, conditionals, and functions are not supported.

Below is a quick reference of some of the more basic functions to get you
started.

### Selectors

Selectors allow you to pick an index out of a JSON object, and are written as
`.KEY.SUBKEY`. So, as an example, given an object of
`{"foo": {"bar": "baz"}}`, and the filter `.foo.bar`, the result would be
displayed as `"baz"`.

A single dot (`.`) without anything else always denotes the current value,
unaltered.

### Indexes

Indexes can be used to fetch array elements, or select non-alphanumeric object
fields. They are written as `[0]` or `["foo-bar"]`, depending on the purpose.

Given an object of `{"foo-bar": ["baz", "qux"]}` and the filter of
`.["foo-bar"][0]`, the result would be displayed as `"baz"`.

### Slices

Arrays can be sliced to get a subset an array. The syntax is `[LOW:HIGH]`.

Given an array of `[0, 1, 2, 3, 4]` and the filter of
`.[1:3]`, the result would be displayed as `[1, 2]`. This also illustrates that
the result of the slice operation is always of length HIGH-LOW.

Slices can also be applied to strings, in which a substring is returned with the
same rules applied, with the first character of the string being index 0.

### Iterators

Iterators can iterate over arrays and objects. The syntax is `[]`.

Iterators iterate over the _values_ of an object only. So given a object of
`{"foo": 1, "bar": 2}`, the filter `.[]` would yield an iteration of `1, 2`.

Note that iteration results are not necessarily always arrays. Iterators are
handled in a special fashion when dealing with pipes and object creators (see
below).

### Array Construction

Wrapping an expression in brackets (`[ ... ]`) creates an array with the
sub-expressions inside the array. The results are always concatenated.

For example, for an object of `{"foo": [1, 2], "bar": [3, 4]}`, the construction
expressions `[.foo[], .bar[]]` and `[.[][]]`, are the same, producing the
resulting array `[1, 2, 3, 4]`.

### Object Construction

Wrapping an expression in curly braces `{KEY: EXPRESSION, ...}` creates an
object.

Iterators work uniquely with object construction in that an object is
constructed for each _iteration_ that the iterator produces.

As a basic example, Consider an array `[1, 2, 3]`. While the expression
`{foo: .}` will produce `{"foo": [1, 2, 3]}`, adding an iterator to the
expression so that it reads `{foo: .[]}` will produce 3 individual objects:
`{"foo": 1}`, `{"foo": 2}`, and `{"foo": 3}`.

### Pipes

Pipes allow the results of one expression to be fed into another. This can be
used to re-write expressions to help reduce complexity.

Iterators work with pipes in a fashion similar to object construction, where the
expression on the right-hand side of the pipe is evaluated once for every
iteration.

As an example, for the object `{"foo": {"a": 1}, "bar": {"a": 2}}`, both the
expression `{z: .[].a}` and `.[] | {z: .a}` produce the same result: `{"z": 1}`
and `{"z": 2}`.

page title  JSON Filtering   HCP Terraform description  Learn how to create custom datasets on pages that display JSON data         About JSON Data Filtering  Certain pages where JSON data is displayed  such as the  state viewer   terraform cloud docs workspaces state  and  policy check JSON data viewer   terraform cloud docs policy enforcement sentinel json   allow you to filter the results  This enables you to see just the data you need  and even create entirely new datasets to see data in the way you want to see it     entering a json filter   img docs json viewer intro png        NOTE     Filtering  the data in the JSON viewer is separate from  searching  it  To search  press Control F  or Command F on MacOS   You can search and apply a filter at the same time      Entering a Filter  Filters are entered by putting the filter in the aptly named   filter   box in the JSON viewer  After entering the filter  pressing   Apply   or the enter key on your keyboard will apply the filter  The filtered results  if any  are displayed in result box  Clearing the filter will restore the original JSON data     entering a json filter   img docs sentinel json enter filter png      Filter Language  The JSON filter language is a small subset of the  jq  https   stedolan github io jq   JSON filtering language  Selectors  literals  indexes  slices  iterators  and pipes are supported  as are also array and object construction  At this time  parentheses  and more complex operations such as mathematical operators  conditionals  and functions are not supported   Below is a quick reference of some of the more basic functions to get you started       Selectors  Selectors allow you to pick an index out of a JSON object  and are written as   KEY SUBKEY   So  as an example  given an object of    foo     bar    baz      and the filter   foo bar   the result would be displayed as   baz     A single dot       without anything else always denotes the current value  unaltered       Indexes  Indexes can be used to fetch array elements  or select non alphanumeric object fields  They are written as   0   or    foo bar     depending on the purpose   Given an object of    foo bar     baz    qux     and the filter of     foo bar   0    the result would be displayed as   baz         Slices  Arrays can be sliced to get a subset an array  The syntax is   LOW HIGH     Given an array of   0  1  2  3  4   and the filter of    1 3    the result would be displayed as   1  2    This also illustrates that the result of the slice operation is always of length HIGH LOW   Slices can also be applied to strings  in which a substring is returned with the same rules applied  with the first character of the string being index 0       Iterators  Iterators can iterate over arrays and objects  The syntax is        Iterators iterate over the  values  of an object only  So given a object of    foo   1   bar   2    the filter       would yield an iteration of  1  2    Note that iteration results are not necessarily always arrays  Iterators are handled in a special fashion when dealing with pipes and object creators  see below        Array Construction  Wrapping an expression in brackets             creates an array with the sub expressions inside the array  The results are always concatenated   For example  for an object of    foo    1  2    bar    3  4     the construction expressions    foo     bar     and            are the same  producing the resulting array   1  2  3  4         Object Construction  Wrapping an expression in curly braces   KEY  EXPRESSION        creates an object   Iterators work uniquely with object construction in that an object is constructed for each  iteration  that the iterator produces   As a basic example  Consider an array   1  2  3    While the expression   foo      will produce    foo    1  2  3     adding an iterator to the expression so that it reads   foo        will produce 3 individual objects     foo   1       foo   2    and    foo   3         Pipes  Pipes allow the results of one expression to be fed into another  This can be used to re write expressions to help reduce complexity   Iterators work with pipes in a fashion similar to object construction  where the expression on the right hand side of the pipe is evaluated once for every iteration   As an example  for the object    foo     a   1    bar     a   2     both the expression   z      a   and         z   a   produce the same result     z   1   and    z   2


terraform Health page title Health HCP Terraform HCP Terraform can perform automatic health assessments in a workspace to assess whether its real infrastructure matches the requirements defined in its Terraform configuration Health assessments include the following types of evaluations HCP Terraform can continuously monitor workspaces to assess whether their real infrastructure matches the requirements defined in their Terraform configuration

Answer:
---
page_title: Health - HCP Terraform
description: |-
 HCP Terraform can continuously monitor workspaces to assess whether their real infrastructure matches the requirements defined in their Terraform configuration.
---

# Health

HCP Terraform can perform automatic health assessments in a workspace to assess whether its real infrastructure matches the requirements defined in its Terraform configuration. Health assessments include the following types of evaluations:

- [Drift detection](#drift-detection) determines whether your real-world infrastructure matches your Terraform configuration.
- [Continuous validation](#continuous-validation) determines whether custom conditions in the workspace’s configuration continue to pass after Terraform provisions the infrastructure.

When you enable health assessments, HCP Terraform periodically runs health assessments for your workspace. Refer to [Health Assessment Scheduling](#health-assessment-scheduling) for details.

<!-- BEGIN: TFC:only name:pnp-callout -->
@include 'tfc-package-callouts/health-assessments.mdx'
<!-- END: TFC:only name:pnp-callout -->

## Permissions

Working with health assessments requires the following permissions:

- To view health status for a workspace, you need read access to that workspace.
- To change organization health settings, you must be an [organization owner](/terraform/cloud-docs/users-teams-organizations/permissions#organization-owners).
- To change a workspace’s health settings, you must be an [administrator for that workspace](/terraform/cloud-docs/users-teams-organizations/permissions#workspace-admins).
<!-- BEGIN: TFC:only name:health-assessments -->
- To trigger [on-demand health assessments](/terraform/cloud-docs/workspaces/health#on-demand-assessments) for a workspace, you must be an [administrator for that workspace](/terraform/cloud-docs/users-teams-organizations/permissions#workspace-admins).
<!-- END: TFC:only name:health-assessments -->

## Workspace requirements

Workspaces require the following settings to receive health assessments:
- Terraform version 0.15.4+ for drift detection only
- Terraform version 1.3.0+ for drift detection and continuous validation
- [Remote execution mode](/terraform/cloud-docs/workspaces/settings#execution-mode) or [Agent execution mode](/terraform/cloud-docs/agents/agent-pools#configure-workspaces-to-use-the-agent) for Terraform runs

The latest Terraform run in the workspace must have been successful. If the most recent run ended in an errored, canceled, or discarded state, HCP Terraform pauses health assessments until there is a successfully applied run.

The workspace must also have at least one run in which Terraform successfully applies a configuration. HCP Terraform does not perform health assessments in workspaces with no real-world infrastructure.

## Enable health assessments

You can enforce health assessments across all eligible workspaces in an organization within the [organization settings](/terraform/cloud-docs/users-teams-organizations/organizations#health). Enforcing health assessments at an organization-level overrides workspace-level settings. You can only enable health assessments within a specific workspace when HCP Terraform is not enforcing health assessments at the organization level.

To enable health assessments within a workspace:

1. Verify that your workspace satisfies the [requirements](#workspace-requirements).
1. Go to the workspace and click **Settings > Health**.
1. Select **Enable** under **Health Assessments**.
1. Click **Save settings**.

## Health assessment scheduling

When you enable health assessments for a workspace, HCP Terraform runs the first health assessment based on whether there are active Terraform runs for the workspace:

- **No active runs:** A few minutes after you enable the feature.
- **Active speculative plan:** A few minutes after that plan is complete.
- **Other active runs:** During the next assessment period.

After the first health assessment, HCP Terraform starts a new health assessment during the next assessment period if there are no active runs in the workspace. Health assessments may take longer to complete when you enable health assessments in many workspaces at once or your workspace contains a complex configuration with many resources.

A health assessment never interrupts or interferes with runs. If you start a new run during a health assessment, HCP Terraform cancels the current assessment and runs the next assessment during the next assessment period. This behavior may prevent HCP Terraform from performing health assessments in workspaces with frequent runs.

HCP Terraform pauses health assessments if the latest run ended in an errored state. This behavior occurs for all run types, including plan-only runs and speculative plans. Once the workspace completes a successful run, HCP Terraform restarts health assessments during the next assessment period.

Terraform Enterprise administrators can modify their installation's [assessment frequency  and number of maximum concurrent assessments](/terraform/enterprise/admin/application/general#health-assessments) from the admin settings console.

<!-- BEGIN: TFC:only name:health-assessments -->

### On-demand assessments

-> **Note:** On-demand assessments are only available in the HCP Terraform user interface.

If you are an administrator for a workspace and it satisfies all [assessment requirements](/terraform/cloud-docs/workspaces/health#workspace-requirements), you can trigger a new assessment by clicking **Start health assessment** on the workspace's **Health** page.

After clicking **Start health assessment**, the workspace displays a message in the bottom lefthand corner of the page to indicate if it successfully triggered a new assessment. The time it takes to complete an assessment can vary based on network latency and the number of resources managed by the workspace.

You cannot trigger another assessment while one is in progress. An on-demand assessment resets the scheduling for automated assessments, so HCP Terraform waits to run the next assessment until the next scheduled period.

<!-- END: TFC:only name:health-assessments -->

### Concurrency

If you enable health assessments on multiple workspaces, assessments may run concurrently. Health assessments do not affect your concurrency limit. HCP Terraform also monitors and controls health assessment concurrency to avoid issues for large-scale deployments with thousands of workspaces. However, HCP Terraform performs health assessments in batches, so health assessments may take longer to complete when you enable them in a large number of workspaces.

### Notifications

HCP Terraform sends [notifications](/terraform/cloud-docs/workspaces/settings/notifications) about health assessment results according to your workspace’s settings.

## Workspace health status

On the organization's **Workspaces** page, HCP Terraform displays a **Health warning** status for workspaces with infrastructure drift or failed continuous validation checks.

On the right of a workspace’s overview page, HCP Terraform displays a **Health** bar that summarizes the results of the last health assessment.
- The **Drift** summary shows the total number of resources in the configuration and the number of resources that have drifted.
- The **Checks** summary shows the number of passed, failed, and unknown statuses for objects with continuous validation checks.

<!-- BEGIN: TFC:only name:health-in-explorer -->

### View workspace health in explorer

The [Explorer page](/terraform/cloud-docs/workspaces/explorer) presents a condensed overview of the health status of the workspaces within your organization. You can see the following information:

- Workspaces that are monitoring workspace health
- Status of any configured continuous validation checks
- Count of drifted resources for each workspace

For additional details on the data available for reporting, refer to the [Explorer](/terraform/cloud-docs/workspaces/explorer) documentation.

![Viewing Workspace Health in Explorer](/img/docs/tfc-explorer-health.png)

<!-- END: TFC:only name:health-in-explorer -->

## Drift detection

Drift detection helps you identify situations where your actual infrastructure no longer matches the configuration defined in Terraform. This deviation is known as _configuration drift_. Configuration drift occurs when changes are made outside Terraform's regular process, leading to inconsistencies between the remote objects and your configured infrastructure.

For example, a teammate could create configuration drift by directly updating a storage bucket's settings with conflicting configuration settings using the cloud provider's console. Drift detection could detect these differences and recommend steps to address and rectify the discrepancies.

Configuration drift differs from state drift. Drift detection does not detect state drift.

Configuration drift happens when external changes affecting remote objects invalidate your infrastructure configuration. State drift occurs when external changes affecting remote objects _do not_ invalidate your infrastructure configuration. Refer to [Refresh-Only Mode](/terraform/cloud-docs/run/modes-and-options#refresh-only-mode)  to learn more about remediating state drift.

### View workspace drift

To view the drift detection results from the latest health assessment, go to the workspace and click **Health > Drift**. If there is configuration drift, HCP Terraform proposes the necessary changes to bring the infrastructure back in sync with its configuration.

### Resolve drift

You can use one of the following approaches to correct configuration drift:
- **Overwrite drift**: If you do not want the drift's changes, queue a new plan and apply the changes to revert your real-world infrastructure to match your Terraform configuration.
- **Update Terraform configuration:** If you want the drift's changes, modify your Terraform configuration to include the changes and push a new configuration version. This prevents Terraform from reverting the drift during the next apply. Refer to the [Manage Resource Drift](/terraform/tutorials/state/resource-drift) tutorial for a detailed example.

## Continuous validation

Continuous validation regularly verifies whether your configuration’s custom assertions continue to pass, validating your infrastructure. For example, you can monitor whether your website returns an expected status code, or whether an API gateway certificate is valid. Identifying failed assertions helps you resolve the failure and prevent errors during your next time Terraform operation.

Continuous validation evaluates preconditions, postconditions, and check blocks as part of an assessment, but we recommend using [check blocks](/terraform/language/checks) for post-apply monitoring. Use check blocks to create custom rules to validate your infrastructure's resources, data sources, and outputs.

### Preventing false positives

Health assessments create a speculative plan to access the current state of your infrastructure. Terraform evaluates any check blocks in your configuration as the last step of creating the speculative plan. If your configuration relies on data sources and the values queried by a data source change between the time of your last run and the assessment, the speculative plan will include those changes. HCP Terraform will not modify your infrastructure as part of an assessment, but it can use those updated values to evaluate checks. This may lead to false positive results for alerts since your infrastructure did not yet change.

To ensure your checks evaluate the current state of your configuration instead of against a possible future change, use nested data sources that query your actual resource configuration, rather than a computed latest value. Refer to the [AMI image scenario](#asserting-up-to-date-amis-for-compute-instances) below for an example.

### Example use cases

Review the provider documentation for `check` block examples with [AWS](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/guides/continuous-validation-examples), [Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/tfc-check-blocks), and [GCP](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/google-continuous-validation).

#### Monitoring the health of a provisioned website

The following example uses the [HTTP](https://registry.terraform.io/providers/hashicorp/http/latest/docs) Terraform provider and a [scoped data source](/terraform/language/checks#scoped-data-sources) within a [`check` block](/terraform/language/checks) to assert the Terraform website returns a `200` status code, indicating it is healthy.

```hcl
check "health_check" {
  data "http" "terraform_io" {
    url = "https://www.terraform.io"
  }

  assert {
    condition = data.http.terraform_io.status_code == 200
    error_message = "${data.http.terraform_io.url} returned an unhealthy status code"
  }
}
```

Continuous Validation alerts you if the website returns any status code besides `200` while Terraform evaluates this assertion. You can also find failures in your workspace's [Continuous Validation Results](#view-continuous-validation-results) page. You can configure continuous validation alerts in your workspace's [notification settings](/terraform/cloud-docs/workspaces/settings/notifications).

#### Monitoring certificate expiration

[Vault](https://www.vaultproject.io/) lets you secure, store, and tightly control access to tokens, passwords, certificates, encryption keys, and other sensitive data. The following example uses a `check` block to monitor for the expiration of a Vault certificate.

```hcl
resource "vault_pki_secret_backend_cert" "app" {
  backend = vault_mount.intermediate.path
  name = vault_pki_secret_backend_role.test.name
  common_name = "app.my.domain"
}

check "certificate_valid" {
  assert {
    condition = !vault_pki_secret_backend_cert.app.renew_pending
    error_message = "Vault cert is ready to renew."
  }
}
```

#### Asserting up-to-date AMIs for compute instances

[HCP Packer](/hcp/docs/packer) stores metadata about your [Packer](https://www.packer.io/) images. The following example check fails when there is a newer AMI version available.

```hcl
data "hcp_packer_artifact" "hashiapp_image" {
  bucket_name  = "hashiapp"
  channel_name = "latest"
  platform     = "aws"
  region       = "us-west-2"
}

resource "aws_instance" "hashiapp" {
  ami                         = data.hcp_packer_artifact.hashiapp_image.external_identifier
  instance_type               = var.instance_type
  associate_public_ip_address = true
  subnet_id                   = aws_subnet.hashiapp.id
  vpc_security_group_ids      = [aws_security_group.hashiapp.id]
  key_name                    = aws_key_pair.generated_key.key_name

  tags = {
    Name = "hashiapp"
  }
}

check "ami_version_check" {
  data "aws_instance" "hashiapp_current" {
    instance_tags = {
      Name = "hashiapp"
    }
  }

  assert {
    condition = aws_instance.hashiapp.ami == data.hcp_packer_artifact.hashiapp_image.external_identifier
    error_message = "Must use the latest available AMI, ${data.hcp_packer_artifact.hashiapp_image.external_identifier}."
  }
}
```

### View continuous validation results

To view the continuous validation results from the latest health assessment, go to the workspace and click **Health > Continuous validation**.

The page shows all of the resources, outputs, and data sources with custom assertions that HCP Terraform evaluated. Next to each object, HCP Terraform reports whether the assertion passed or failed. If one or more assertions fail, HCP Terraform displays the error messages for each assertion.

The health assessment page displays each assertion by its [named value](/terraform/language/expressions/references). A `check` block's named value combines the prefix `check` with its configuration name.

If your configuration contains multiple [preconditions and postconditions](/terraform/language/expressions/custom-conditions#preconditions-and-postconditions) within a single resource, output, or data source, HCP Terraform will not show the results of individual conditions unless they fail. If all custom conditions on the object pass, HCP Terraform reports that the entire check passed. The assessment results will display the results of any precondition and postconditions alongside the results of any assertions from `check` blocks, identified by the named values of their parent block.

page title  Health   HCP Terraform description      HCP Terraform can continuously monitor workspaces to assess whether their real infrastructure matches the requirements defined in their Terraform configuration         Health  HCP Terraform can perform automatic health assessments in a workspace to assess whether its real infrastructure matches the requirements defined in its Terraform configuration  Health assessments include the following types of evaluations      Drift detection   drift detection  determines whether your real world infrastructure matches your Terraform configuration     Continuous validation   continuous validation  determines whether custom conditions in the workspace s configuration continue to pass after Terraform provisions the infrastructure   When you enable health assessments  HCP Terraform periodically runs health assessments for your workspace  Refer to  Health Assessment Scheduling   health assessment scheduling  for details        BEGIN  TFC only name pnp callout      include  tfc package callouts health assessments mdx       END  TFC only name pnp callout         Permissions  Working with health assessments requires the following permissions     To view health status for a workspace  you need read access to that workspace    To change organization health settings  you must be an  organization owner   terraform cloud docs users teams organizations permissions organization owners     To change a workspace s health settings  you must be an  administrator for that workspace   terraform cloud docs users teams organizations permissions workspace admins        BEGIN  TFC only name health assessments       To trigger  on demand health assessments   terraform cloud docs workspaces health on demand assessments  for a workspace  you must be an  administrator for that workspace   terraform cloud docs users teams organizations permissions workspace admins        END  TFC only name health assessments         Workspace requirements  Workspaces require the following settings to receive health assessments    Terraform version 0 15 4  for drift detection only   Terraform version 1 3 0  for drift detection and continuous validation    Remote execution mode   terraform cloud docs workspaces settings execution mode  or  Agent execution mode   terraform cloud docs agents agent pools configure workspaces to use the agent  for Terraform runs  The latest Terraform run in the workspace must have been successful  If the most recent run ended in an errored  canceled  or discarded state  HCP Terraform pauses health assessments until there is a successfully applied run   The workspace must also have at least one run in which Terraform successfully applies a configuration  HCP Terraform does not perform health assessments in workspaces with no real world infrastructure      Enable health assessments  You can enforce health assessments across all eligible workspaces in an organization within the  organization settings   terraform cloud docs users teams organizations organizations health   Enforcing health assessments at an organization level overrides workspace level settings  You can only enable health assessments within a specific workspace when HCP Terraform is not enforcing health assessments at the organization level   To enable health assessments within a workspace   1  Verify that your workspace satisfies the  requirements   workspace requirements   1  Go to the workspace and click   Settings   Health    1  Select   Enable   under   Health Assessments    1  Click   Save settings        Health assessment scheduling  When you enable health assessments for a workspace  HCP Terraform runs the first health assessment based on whether there are active Terraform runs for the workspace       No active runs    A few minutes after you enable the feature      Active speculative plan    A few minutes after that plan is complete      Other active runs    During the next assessment period   After the first health assessment  HCP Terraform starts a new health assessment during the next assessment period if there are no active runs in the workspace  Health assessments may take longer to complete when you enable health assessments in many workspaces at once or your workspace contains a complex configuration with many resources    A health assessment never interrupts or interferes with runs  If you start a new run during a health assessment  HCP Terraform cancels the current assessment and runs the next assessment during the next assessment period  This behavior may prevent HCP Terraform from performing health assessments in workspaces with frequent runs   HCP Terraform pauses health assessments if the latest run ended in an errored state  This behavior occurs for all run types  including plan only runs and speculative plans  Once the workspace completes a successful run  HCP Terraform restarts health assessments during the next assessment period   Terraform Enterprise administrators can modify their installation s  assessment frequency  and number of maximum concurrent assessments   terraform enterprise admin application general health assessments  from the admin settings console        BEGIN  TFC only name health assessments          On demand assessments       Note    On demand assessments are only available in the HCP Terraform user interface   If you are an administrator for a workspace and it satisfies all  assessment requirements   terraform cloud docs workspaces health workspace requirements   you can trigger a new assessment by clicking   Start health assessment   on the workspace s   Health   page   After clicking   Start health assessment    the workspace displays a message in the bottom lefthand corner of the page to indicate if it successfully triggered a new assessment  The time it takes to complete an assessment can vary based on network latency and the number of resources managed by the workspace    You cannot trigger another assessment while one is in progress  An on demand assessment resets the scheduling for automated assessments  so HCP Terraform waits to run the next assessment until the next scheduled period        END  TFC only name health assessments          Concurrency  If you enable health assessments on multiple workspaces  assessments may run concurrently  Health assessments do not affect your concurrency limit  HCP Terraform also monitors and controls health assessment concurrency to avoid issues for large scale deployments with thousands of workspaces  However  HCP Terraform performs health assessments in batches  so health assessments may take longer to complete when you enable them in a large number of workspaces       Notifications  HCP Terraform sends  notifications   terraform cloud docs workspaces settings notifications  about health assessment results according to your workspace s settings      Workspace health status  On the organization s   Workspaces   page  HCP Terraform displays a   Health warning   status for workspaces with infrastructure drift or failed continuous validation checks   On the right of a workspace s overview page  HCP Terraform displays a   Health   bar that summarizes the results of the last health assessment    The   Drift   summary shows the total number of resources in the configuration and the number of resources that have drifted    The   Checks   summary shows the number of passed  failed  and unknown statuses for objects with continuous validation checks        BEGIN  TFC only name health in explorer          View workspace health in explorer  The  Explorer page   terraform cloud docs workspaces explorer  presents a condensed overview of the health status of the workspaces within your organization  You can see the following information     Workspaces that are monitoring workspace health    Status of any configured continuous validation checks    Count of drifted resources for each workspace   For additional details on the data available for reporting  refer to the  Explorer   terraform cloud docs workspaces explorer  documentation     Viewing Workspace Health in Explorer   img docs tfc explorer health png        END  TFC only name health in explorer         Drift detection  Drift detection helps you identify situations where your actual infrastructure no longer matches the configuration defined in Terraform  This deviation is known as  configuration drift   Configuration drift occurs when changes are made outside Terraform s regular process  leading to inconsistencies between the remote objects and your configured infrastructure   For example  a teammate could create configuration drift by directly updating a storage bucket s settings with conflicting configuration settings using the cloud provider s console  Drift detection could detect these differences and recommend steps to address and rectify the discrepancies   Configuration drift differs from state drift  Drift detection does not detect state drift   Configuration drift happens when external changes affecting remote objects invalidate your infrastructure configuration  State drift occurs when external changes affecting remote objects  do not  invalidate your infrastructure configuration  Refer to  Refresh Only Mode   terraform cloud docs run modes and options refresh only mode   to learn more about remediating state drift       View workspace drift  To view the drift detection results from the latest health assessment  go to the workspace and click   Health   Drift    If there is configuration drift  HCP Terraform proposes the necessary changes to bring the infrastructure back in sync with its configuration       Resolve drift  You can use one of the following approaches to correct configuration drift      Overwrite drift    If you do not want the drift s changes  queue a new plan and apply the changes to revert your real world infrastructure to match your Terraform configuration      Update Terraform configuration    If you want the drift s changes  modify your Terraform configuration to include the changes and push a new configuration version  This prevents Terraform from reverting the drift during the next apply  Refer to the  Manage Resource Drift   terraform tutorials state resource drift  tutorial for a detailed example      Continuous validation  Continuous validation regularly verifies whether your configuration s custom assertions continue to pass  validating your infrastructure  For example  you can monitor whether your website returns an expected status code  or whether an API gateway certificate is valid  Identifying failed assertions helps you resolve the failure and prevent errors during your next time Terraform operation   Continuous validation evaluates preconditions  postconditions  and check blocks as part of an assessment  but we recommend using  check blocks   terraform language checks  for post apply monitoring  Use check blocks to create custom rules to validate your infrastructure s resources  data sources  and outputs       Preventing false positives  Health assessments create a speculative plan to access the current state of your infrastructure  Terraform evaluates any check blocks in your configuration as the last step of creating the speculative plan  If your configuration relies on data sources and the values queried by a data source change between the time of your last run and the assessment  the speculative plan will include those changes  HCP Terraform will not modify your infrastructure as part of an assessment  but it can use those updated values to evaluate checks  This may lead to false positive results for alerts since your infrastructure did not yet change   To ensure your checks evaluate the current state of your configuration instead of against a possible future change  use nested data sources that query your actual resource configuration  rather than a computed latest value  Refer to the  AMI image scenario   asserting up to date amis for compute instances  below for an example       Example use cases  Review the provider documentation for  check  block examples with  AWS  https   registry terraform io providers hashicorp aws latest docs guides continuous validation examples    Azure  https   registry terraform io providers hashicorp azurerm latest docs guides tfc check blocks   and  GCP  https   registry terraform io providers hashicorp google latest docs guides google continuous validation         Monitoring the health of a provisioned website  The following example uses the  HTTP  https   registry terraform io providers hashicorp http latest docs  Terraform provider and a  scoped data source   terraform language checks scoped data sources  within a   check  block   terraform language checks  to assert the Terraform website returns a  200  status code  indicating it is healthy      hcl check  health check      data  http   terraform io        url    https   www terraform io         assert       condition   data http terraform io status code    200     error message      data http terraform io url  returned an unhealthy status code             Continuous Validation alerts you if the website returns any status code besides  200  while Terraform evaluates this assertion  You can also find failures in your workspace s  Continuous Validation Results   view continuous validation results  page  You can configure continuous validation alerts in your workspace s  notification settings   terraform cloud docs workspaces settings notifications         Monitoring certificate expiration   Vault  https   www vaultproject io   lets you secure  store  and tightly control access to tokens  passwords  certificates  encryption keys  and other sensitive data  The following example uses a  check  block to monitor for the expiration of a Vault certificate      hcl resource  vault pki secret backend cert   app      backend   vault mount intermediate path   name   vault pki secret backend role test name   common name    app my domain     check  certificate valid      assert       condition    vault pki secret backend cert app renew pending     error message    Vault cert is ready to renew                   Asserting up to date AMIs for compute instances   HCP Packer   hcp docs packer  stores metadata about your  Packer  https   www packer io   images  The following example check fails when there is a newer AMI version available      hcl data  hcp packer artifact   hashiapp image      bucket name     hashiapp    channel name    latest    platform        aws    region          us west 2     resource  aws instance   hashiapp      ami                           data hcp packer artifact hashiapp image external identifier   instance type                 var instance type   associate public ip address   true   subnet id                     aws subnet hashiapp id   vpc security group ids         aws security group hashiapp id    key name                      aws key pair generated key key name    tags         Name    hashiapp         check  ami version check      data  aws instance   hashiapp current        instance tags           Name    hashiapp               assert       condition   aws instance hashiapp ami    data hcp packer artifact hashiapp image external identifier     error message    Must use the latest available AMI    data hcp packer artifact hashiapp image external identifier                   View continuous validation results  To view the continuous validation results from the latest health assessment  go to the workspace and click   Health   Continuous validation     The page shows all of the resources  outputs  and data sources with custom assertions that HCP Terraform evaluated  Next to each object  HCP Terraform reports whether the assertion passed or failed  If one or more assertions fail  HCP Terraform displays the error messages for each assertion   The health assessment page displays each assertion by its  named value   terraform language expressions references   A  check  block s named value combines the prefix  check  with its configuration name   If your configuration contains multiple  preconditions and postconditions   terraform language expressions custom conditions preconditions and postconditions  within a single resource  output  or data source  HCP Terraform will not show the results of individual conditions unless they fail  If all custom conditions on the object pass  HCP Terraform reports that the entire check passed  The assessment results will display the results of any precondition and postconditions alongside the results of any assertions from  check  blocks  identified by the named values of their parent block


terraform Surface information from across workspaces and projects in your organization Explorer for Workspace Visibility As your organization grows keeping track of your sprawling infrastructure estate can get increasingly more complicated The explorer for workspace visibility helps surface a wide range of valuable information from across your organization page title Explorer for Workspace Visibility HCP Terraform tfc only true

Answer:
---
page_title: Explorer for Workspace Visibility - HCP Terraform
description: >-
  Surface information from across workspaces and projects in your organization.
tfc_only: true
---

# Explorer for Workspace Visibility

As your organization grows, keeping track of your sprawling infrastructure estate can get increasingly more complicated. The explorer for workspace visibility helps surface a wide range of valuable information from across your organization.

Open the explorer for workspace visibility by clicking **Explorer** in your organization's top-level side navigation.

The **Explorer** page displays buttons grouped by **Types** and **Use Cases**. Each button offers a new view into your organization or workspace's data. Clicking a button triggers the explorer to perform a query and display the results in a table of data.

![Explorer Landing Page](/img/docs/terraform-cloud-explorer-landing-page.png)

The **Types** buttons present generic use cases. For example, "Workspaces" displays a paginated and unfiltered list of your organization's workspaces and each workspace's accompanying data. The **Use Cases** buttons present sorted and filtered results to give you a focused view of your organizational data.

You can sort each column of the explorer results table. Clicking a hyperlinked field shows increasingly specific views of your data. For example, a workspace's modules count field links to a view of that workspace's associated modules.

Clearing a query takes you back to the explorer landing page. To clear a query, click the back arrow at the top left of your current explorer view page.

## Permissions

The explorer for workspace visibility requires access to a broad range of an organization's data. To use the explorer, you must have either of the following organization permissions:
- [Organization owner](/terraform/cloud-docs/users-teams-organizations/permissions#organization-owners)
- [View all workspaces](/terraform/cloud-docs/users-teams-organizations/permissions#view-all-workspaces) or greater

## Types

The explorer for workspace visibility supports four types:

- [Workspaces](/terraform/cloud-docs/workspaces)
- [Modules](/terraform/language/modules)
- [Providers](/terraform/language/providers)
- [Terraform Versions](/terraform/language/upgrade-guides#upgrading-to-terraform-v1-4)

## Use cases

The explorer for workspace visibility provides the following queries for specific use cases:

- **Top module versions** shows modules sorted by usage frequency.
- **Latest Terraform versions** displays a sorted list of Terraform versions in use.
- **Top provider versions** lists providers sorted by usage frequency.
- **Workspaces without VCS** lists workspaces not backed by VCS.
- **Workspace VCS source** lists VCS-backed workspaces sorted by repository name.
- **Workspaces with failed checks** lists workspaces that failed at least one [continuous validation](/terraform/enterprise/workspaces/health#continuous-validation) check.
- **Drifted workspaces** displays [workspaces with drift](/terraform/enterprise/workspaces/health#drift-detection) and relevant drift information.
- **Workspace VCS source** displays a subset of workspace data sorted by the underlying VCS repository.
- **All workspace versions** is a simplified view of your workspaces with current run and version information.
- **Runs by status** provides a run-focused view by sorting workspaces by their current run status.
- **Top Terraform versions** lists all Terraform versions by usage frequency
- **Latest updated workspaces** displays your most recently updated workspaces.
- **Oldest applied workspaces** sorts workspaces by the date of the current applied run.

## Custom filter conditions

The explorer's query builder allows you to execute queries with custom filter conditions against any of the supported [types](#types).

To use the query builder, select a type or use case from the explorer home page. Expand the **Modify conditions** section to show the filter conditions in use for the current query and to define new filter conditions.

![Explorer Query Builder](/img/docs/query-builder.png)

Each filter condition is represented by a row of inputs, each made up of a target field, operator, and value.

1. Choose a target field from the first dropdown to select field that the explorer will run the query against. The options available will vary based on the target field's data type.

1. Choose an operator from the second dropdown. The options available will vary based on the target field's data type.

1. Provide a value in the third field to compare against the target field's value.

1. Click **Run Query** to evaluate the filter conditions.

-> **Tip:** Inspect the filter conditions used by the various pre-canned [**Use Cases**](#use-cases) to learn how they are constructed.

You can create multiple filter conditions for a query. When you provide multiple conditions, the explorer evaluates them at query time with a logical AND. To add a new condition, use the **Add condition** button below the condition list. To remove a condition, use the trash bin button on the right hand side of the condition.

## Save a view

You can save explorer views to revisit a custom query or use case.

-> **Note**: The ability to save views in the explorer is in public beta. All APIs and workflows are subject to change.

You can save the explorer’s view of your data by performing the following steps:

1. Navigate to the **Explorer** page in the sidebar of your organization.
1. Click on a tile in the **Types** or **Use cases** section.
1. Define a query using the query building interface.
1. By default, the explorer displays all available information, but you can adjust which columns you want your view to include.
1. Open the **Actions** dropdown menu and select **Save view**, saving the last query you performed in the explorer.
1. Specify a new, unique name for your saved view.
1. Click **Save**.

When your explorer saves a view, it saves the last query it performed. If you change a query and do not rerun it, the explorer does not save those changes.

After you have saved a view of your data, you can access it from the explorer’s main page underneath the **Saved views** tab. Saved views keep track of the following attributes:

* The name of the saved view.
* The type of data you are querying, either module, workspace, provider, or Terraform versions.
* The owner of the saved view.
* When the saved view was last updated.

You can rename or delete a saved view from the **Saved views** tab by opening the ellipsis menu next to a view and selecting either **Rename** or **Delete**.

### Manage a saved view

Complete the following steps to update a saved view:

1. Open the view in the explorer and make changes.
1. Open the **Actions** dropdown menu and select **Save view.**

Complete the following steps to save a new view based on an existing saved view:

1. Open a saved view in the explorer and make changes.
1. Open the **Actions** dropdown menu and select **Save as**.
1. Entering a name for this new saved view.
1. Click **Save**.

Complete the following steps to delete a saved view:

1. Open a saved view in the explorer.
1. Choose  **Delete view** from the **Actions** drop-down menu.
1. Click **Delete** when prompted to confirm that you want to permanently delete the view.

page title  Explorer for Workspace Visibility   HCP Terraform description       Surface information from across workspaces and projects in your organization  tfc only  true        Explorer for Workspace Visibility  As your organization grows  keeping track of your sprawling infrastructure estate can get increasingly more complicated  The explorer for workspace visibility helps surface a wide range of valuable information from across your organization   Open the explorer for workspace visibility by clicking   Explorer   in your organization s top level side navigation   The   Explorer   page displays buttons grouped by   Types   and   Use Cases    Each button offers a new view into your organization or workspace s data  Clicking a button triggers the explorer to perform a query and display the results in a table of data      Explorer Landing Page   img docs terraform cloud explorer landing page png   The   Types   buttons present generic use cases  For example   Workspaces  displays a paginated and unfiltered list of your organization s workspaces and each workspace s accompanying data  The   Use Cases   buttons present sorted and filtered results to give you a focused view of your organizational data   You can sort each column of the explorer results table  Clicking a hyperlinked field shows increasingly specific views of your data  For example  a workspace s modules count field links to a view of that workspace s associated modules    Clearing a query takes you back to the explorer landing page  To clear a query  click the back arrow at the top left of your current explorer view page      Permissions  The explorer for workspace visibility requires access to a broad range of an organization s data  To use the explorer  you must have either of the following organization permissions     Organization owner   terraform cloud docs users teams organizations permissions organization owners     View all workspaces   terraform cloud docs users teams organizations permissions view all workspaces  or greater     Types  The explorer for workspace visibility supports four types      Workspaces   terraform cloud docs workspaces     Modules   terraform language modules     Providers   terraform language providers     Terraform Versions   terraform language upgrade guides upgrading to terraform v1 4      Use cases  The explorer for workspace visibility provides the following queries for specific use cases       Top module versions   shows modules sorted by usage frequency      Latest Terraform versions   displays a sorted list of Terraform versions in use      Top provider versions   lists providers sorted by usage frequency      Workspaces without VCS   lists workspaces not backed by VCS      Workspace VCS source   lists VCS backed workspaces sorted by repository name      Workspaces with failed checks   lists workspaces that failed at least one  continuous validation   terraform enterprise workspaces health continuous validation  check      Drifted workspaces   displays  workspaces with drift   terraform enterprise workspaces health drift detection  and relevant drift information      Workspace VCS source   displays a subset of workspace data sorted by the underlying VCS repository      All workspace versions   is a simplified view of your workspaces with current run and version information      Runs by status   provides a run focused view by sorting workspaces by their current run status      Top Terraform versions   lists all Terraform versions by usage frequency     Latest updated workspaces   displays your most recently updated workspaces      Oldest applied workspaces   sorts workspaces by the date of the current applied run      Custom filter conditions  The explorer s query builder allows you to execute queries with custom filter conditions against any of the supported  types   types    To use the query builder  select a type or use case from the explorer home page  Expand the   Modify conditions   section to show the filter conditions in use for the current query and to define new filter conditions     Explorer Query Builder   img docs query builder png   Each filter condition is represented by a row of inputs  each made up of a target field  operator  and value   1  Choose a target field from the first dropdown to select field that the explorer will run the query against  The options available will vary based on the target field s data type   1  Choose an operator from the second dropdown  The options available will vary based on the target field s data type   1  Provide a value in the third field to compare against the target field s value   1  Click   Run Query   to evaluate the filter conditions        Tip    Inspect the filter conditions used by the various pre canned    Use Cases     use cases  to learn how they are constructed   You can create multiple filter conditions for a query  When you provide multiple conditions  the explorer evaluates them at query time with a logical AND  To add a new condition  use the   Add condition   button below the condition list  To remove a condition  use the trash bin button on the right hand side of the condition      Save a view  You can save explorer views to revisit a custom query or use case        Note    The ability to save views in the explorer is in public beta  All APIs and workflows are subject to change   You can save the explorer s view of your data by performing the following steps   1  Navigate to the   Explorer   page in the sidebar of your organization    1  Click on a tile in the   Types   or   Use cases   section  1  Define a query using the query building interface     1  By default  the explorer displays all available information  but you can adjust which columns you want your view to include    1  Open the   Actions   dropdown menu and select   Save view    saving the last query you performed in the explorer    1  Specify a new  unique name for your saved view     1  Click   Save     When your explorer saves a view  it saves the last query it performed  If you change a query and do not rerun it  the explorer does not save those changes   After you have saved a view of your data  you can access it from the explorer s main page underneath the   Saved views   tab  Saved views keep track of the following attributes     The name of the saved view     The type of data you are querying  either module  workspace  provider  or Terraform versions    The owner of the saved view      When the saved view was last updated   You can rename or delete a saved view from the   Saved views   tab by opening the ellipsis menu next to a view and selecting either   Rename   or   Delete         Manage a saved view  Complete the following steps to update a saved view   1  Open the view in the explorer and make changes    1  Open the   Actions   dropdown menu and select   Save view     Complete the following steps to save a new view based on an existing saved view   1  Open a saved view in the explorer and make changes    1  Open the   Actions   dropdown menu and select   Save as      1  Entering a name for this new saved view    1  Click   Save     Complete the following steps to delete a saved view   1  Open a saved view in the explorer  1  Choose    Delete view   from the   Actions   drop down menu  1  Click   Delete   when prompted to confirm that you want to permanently delete the view


terraform Create workspace tags Learn how to create tags for your workspaces so that you can organize workspaces Tagging workspaces also lets you sort and filter workspaces in the UI page title Create workspace tags Overview This topic describes how to attach tags to your workspaces so that you can organize workspaces Tagging workspaces also helps you sort and filter workspaces in the UI and enable you to associate Terraform configurations with several workspaces

Answer:
---
page_title: Create workspace tags
description: Learn how to create tags for your workspaces so that you can organize workspaces. Tagging workspaces also lets you sort and filter workspaces in the UI.
---

# Create workspace tags

This topic describes how to attach tags to your workspaces so that you can organize workspaces. Tagging workspaces also helps you sort and filter workspaces in the UI and enable you to associate Terraform configurations with several workspaces.

## Overview

You can create tags and attach them to your workspaces. Tagging workspaces helps organization administrators organize, sort, and filter workspaces so that they can track resource consumption. For example, you could add a `cost-center` tag so that administrators can sort workspaces according to cost center.

HCP Terraform stores tags as either single-value tags or key-value pairs. You can also migrate existing single-value tags to the key-value scheme. Refer to [Migrating to key-value tags](#migrating-to-key-value-tags) for instructions.

~> **Adding tags stored as key-value pairs is in private beta and unavailable for some users.** Contact your HashiCorp representative for information about participating in the private beta.

Single-value tags enable you to associate a single Terraform configuration file with several workspaces according to tag. Refer to the following topics in the Terraform CLI and configuration language documentation for additional information:

- [`terraform{}.cloud{}.workspaces` reference](/terraform/language/terraform#terraform-cloud-workspaces)
- [Define connection settings](/terraform/cli/cloud/settings#define-connection-settings)

### Reserved tags

You can reserve a set of tag keys for each organization. Reserved tag keys appear as suggestions when people create tags for projects and workspaces so that you can use consistent terms for tags. Refer to [Create and manage reserved tags](/terraform/cloud-docs/users-teams-organizations/organizations#create-and-manage-reserved-tags) for additional information.

~> **Reserved tags and project tags are in private beta and unavailable for some users.** Contact your HashiCorp representative for information about participating in the private beta.

## Requirements

- You must be member of a team with the **Write** permission group enabled for the workspace to create tags for a workspace.
- You must be member of a team with the **Admin** permission group enabled for the workspace to delete tags on a workspace.

You cannot create tags for a workspace using the CLI.

## Define tags

Complete the following steps to define workspace tags:

<Tabs>

<Tab heading="Key-value tags">

1. Open your workspace.
1. Click either the count link for the **Tags** label or **Manage Tags** in the **Tags** card on the right-sidebar to open the **Manage workspace tags** drawer.
1. Click **+Add tag** to define a new key-value pair. Refer to [Tag syntax](#Tag-syntax) for information about supported characters.
1. Tags inherited from the project appear in the **Inherited Tags** section. You can attach new key-value pairs to their projects to override inherited tags. Refer to [Manage projects](/terraform/cloud-docs/projects/manage) for additional information about using tags in projects.

   You cannot override reserved tag keys created by the organization administrator. Refer to [Create and manage reserved tags](/terraform/cloud-docs/users-teams-organizations/organizations#create-and-manage-reserved-tags) for additional information.

   You can also click on tag links in the **Inherited Tags** section to view workspaces that use the same tag.
1. Click **Save**.

</Tab>
<Tab heading="Single-value tags">

1. Open your workspace.
1. Open the **Add a tag** drop-down menu and enter a value. If a tag value already exists, you can attach it to the workspace. Otherwise, HCP Terraform creates a new tag and attaches it to the workspace. Refer to [Tag syntax](#Tag-syntax) for information about supported characters.

</Tab>
</Tabs>

Tags that you create appear in the tags management screen in the organization settings. Refer to [Organizations](/terraform/cloud-docs/users-teams-organizations/organizations) for additional information.

## Update tags

<Tabs>

<Tab heading="Key-value tags">

1. Open your workspace.
1. Click either the count link for the **Tags** label or **Manage Tags** in the **Tags** card on the right-sidebar to open the **Manage workspace tags** drawer.
1. In the **Direct Tags** section, modify either a key, value, or both and click **Save**.

</Tab>
<Tab heading="Single-value tags">

You cannot manage single-value tags in the UI. Instead, use the following workspace API endpoints to manage single-value tags:

- [`POST /workspaces/:workspace_id/relationships/tags`](/terraform/cloud-docs/api-docs/workspaces#add-tags-to-a-workspace): Adds a new single-value workspace tag.
- [`DELETE /workspaces/:workspace_id/relationships/tags`](/terraform/cloud-docs/api-docs/workspaces#remove-tags-from-workspace): Deletes a single-value workspace tag.
- [`PATCH /workspaces/:workspace_id`](/terraform/cloud-docs/api-docs/workspaces#update-a-workspace): Updates an existing single-value workspace tag.

</Tab>
</Tabs>

## Migrating to key-value tags

You can use the API to migrate single-value tags that may already be in your workspace tags to tag stored as key-value pairs. You must have permissions in the workspace to perform the following task. Refer to [Requirements](#requirements) for additional information.

Note that Terraform adds single-value workspace tags that are defined in the associated Terraform cloud block configuration to workspaces selected by the configuration. As result, your workspace may include duplicate tags. Refer to the [Terraform reference documentation](/terraform/language/terraform#terraform-cloud-workspaces) for additional information.

### Re-create existing workspace tags as resource tags

1. Send a `GET` request to the [`/organizations/:organization_name/tags`](/terraform/cloud-docs/api-docs/organization-tags#list-tags) endpoint to request all workspaces for your organization. The response may span several pages.
1. For each workspace, check the `tag-names` attribute for existing tags.
1. Send a `PATCH` request to the [`/workspaces/:workspace_id`](/terraform/cloud-docs/api-docs/workspaces#update-a-workspace) endpoint and include the `tag-binding` relationship in the request body for each workspace tag.

### Delete single-value workspace tags

1. Send a `GET` request to the [`/organizations/:organization_name/tags`](/terraform/cloud-docs/api-docs/organization-tags#list-tags) endpoint to request all workspaces for your organization.
1. Enumerate the external IDs for all tags.
2. Send a `DELETE` request to the [`/organizations/:organization_name/tags`](/terraform/cloud-docs/api-docs/organization-tags#delete-tags) endpoint to delete tags.

## Tag syntax

The following rules apply to tags:

- Tags must be one or more characters.
- Tags have a 255 character limit.
- Tags can include letters, numbers, colons, hyphens, and underscores.
- For tags stored as key-value pairs, tag values are optional

page title  Create workspace tags description  Learn how to create tags for your workspaces so that you can organize workspaces  Tagging workspaces also lets you sort and filter workspaces in the UI           Create workspace tags  This topic describes how to attach tags to your workspaces so that you can organize workspaces  Tagging workspaces also helps you sort and filter workspaces in the UI and enable you to associate Terraform configurations with several workspaces       Overview  You can create tags and attach them to your workspaces  Tagging workspaces helps organization administrators organize  sort  and filter workspaces so that they can track resource consumption  For example  you could add a  cost center  tag so that administrators can sort workspaces according to cost center    HCP Terraform stores tags as either single value tags or key value pairs  You can also migrate existing single value tags to the key value scheme  Refer to  Migrating to key value tags   migrating to key value tags  for instructions        Adding tags stored as key value pairs is in private beta and unavailable for some users    Contact your HashiCorp representative for information about participating in the private beta   Single value tags enable you to associate a single Terraform configuration file with several workspaces according to tag  Refer to the following topics in the Terraform CLI and configuration language documentation for additional information       terraform   cloud   workspaces  reference   terraform language terraform terraform cloud workspaces     Define connection settings   terraform cli cloud settings define connection settings       Reserved tags  You can reserve a set of tag keys for each organization  Reserved tag keys appear as suggestions when people create tags for projects and workspaces so that you can use consistent terms for tags  Refer to  Create and manage reserved tags   terraform cloud docs users teams organizations organizations create and manage reserved tags  for additional information        Reserved tags and project tags are in private beta and unavailable for some users    Contact your HashiCorp representative for information about participating in the private beta      Requirements    You must be member of a team with the   Write   permission group enabled for the workspace to create tags for a workspace    You must be member of a team with the   Admin   permission group enabled for the workspace to delete tags on a workspace   You cannot create tags for a workspace using the CLI      Define tags  Complete the following steps to define workspace tags     Tabs    Tab heading  Key value tags    1  Open your workspace  1  Click either the count link for the   Tags   label or   Manage Tags   in the   Tags   card on the right sidebar to open the   Manage workspace tags   drawer  1  Click    Add tag   to define a new key value pair  Refer to  Tag syntax   Tag syntax  for information about supported characters   1  Tags inherited from the project appear in the   Inherited Tags   section  You can attach new key value pairs to their projects to override inherited tags  Refer to  Manage projects   terraform cloud docs projects manage  for additional information about using tags in projects      You cannot override reserved tag keys created by the organization administrator  Refer to  Create and manage reserved tags   terraform cloud docs users teams organizations organizations create and manage reserved tags  for additional information      You can also click on tag links in the   Inherited Tags   section to view workspaces that use the same tag  1  Click   Save       Tab   Tab heading  Single value tags    1  Open your workspace  1  Open the   Add a tag   drop down menu and enter a value  If a tag value already exists  you can attach it to the workspace  Otherwise  HCP Terraform creates a new tag and attaches it to the workspace  Refer to  Tag syntax   Tag syntax  for information about supported characters     Tab    Tabs   Tags that you create appear in the tags management screen in the organization settings  Refer to  Organizations   terraform cloud docs users teams organizations organizations  for additional information      Update tags   Tabs    Tab heading  Key value tags    1  Open your workspace  1  Click either the count link for the   Tags   label or   Manage Tags   in the   Tags   card on the right sidebar to open the   Manage workspace tags   drawer  1  In the   Direct Tags   section  modify either a key  value  or both and click   Save       Tab   Tab heading  Single value tags    You cannot manage single value tags in the UI  Instead  use the following workspace API endpoints to manage single value tags       POST  workspaces  workspace id relationships tags    terraform cloud docs api docs workspaces add tags to a workspace   Adds a new single value workspace tag      DELETE  workspaces  workspace id relationships tags    terraform cloud docs api docs workspaces remove tags from workspace   Deletes a single value workspace tag      PATCH  workspaces  workspace id    terraform cloud docs api docs workspaces update a workspace   Updates an existing single value workspace tag     Tab    Tabs      Migrating to key value tags  You can use the API to migrate single value tags that may already be in your workspace tags to tag stored as key value pairs  You must have permissions in the workspace to perform the following task  Refer to  Requirements   requirements  for additional information   Note that Terraform adds single value workspace tags that are defined in the associated Terraform cloud block configuration to workspaces selected by the configuration  As result  your workspace may include duplicate tags  Refer to the  Terraform reference documentation   terraform language terraform terraform cloud workspaces  for additional information        Re create existing workspace tags as resource tags  1  Send a  GET  request to the    organizations  organization name tags    terraform cloud docs api docs organization tags list tags  endpoint to request all workspaces for your organization  The response may span several pages  1  For each workspace  check the  tag names  attribute for existing tags  1  Send a  PATCH  request to the    workspaces  workspace id    terraform cloud docs api docs workspaces update a workspace  endpoint and include the  tag binding  relationship in the request body for each workspace tag       Delete single value workspace tags  1  Send a  GET  request to the    organizations  organization name tags    terraform cloud docs api docs organization tags list tags  endpoint to request all workspaces for your organization  1  Enumerate the external IDs for all tags  2  Send a  DELETE  request to the    organizations  organization name tags    terraform cloud docs api docs organization tags delete tags  endpoint to delete tags      Tag syntax  The following rules apply to tags     Tags must be one or more characters    Tags have a 255 character limit    Tags can include letters  numbers  colons  hyphens  and underscores    For tags stored as key value pairs  tag values are optional