Organizations overview

This topic provides overview information about how to create and manage organizations in HCP Terraform and Terraform Enterprise. An organization contains one or more projects.

Requirements

The admin permission preset must be enabled on your profile to create and manage organizations in the HCP Terraform UI. Refer to Permissions for additional information.

API and Terraform Enterprise Provider

In addition to the HCP Terraform UI, you can use the following methods to manage organizations:

• Organizations API
• The tfe provider tfe_organization resource

Selecting organizations

HCP Terraform displays your current organization in the bottom left of the sidebar. To select an organization:

1. Click the current organization name to view a list of all the organizations where you are a member.
2. Click an organization to select it. HCP Terraform displays list of workspaces within that organization.

Joining and leaving organizations

To join an organization, the organization owners or a user with specific team management permissions must invite you, and you must accept the emailed invitation. Learn more.

To leave an organization:

1. Click the Terraform logo in the upper left corner to navigate to the Organizations page.
2. Click the ellipses (...) next to the organization and select Leave organization.

You do not need permission from the owners to leave an organization, but you cannot leave if you are the last member of the owners team. Either add a new owner and then leave, or delete the organization.

Creating organizations

On Terraform Enterprise, administrators can restrict your ability to create organizations. Refer to Administration: General Settings for details.

On HCP Terraform, any user can create a new organization. If you do not belong to any organizations, HCP Terraform prompts you to create one the first time you log in. To create an organization:

1. Click the current organization name and select Create new organization. The Create a new organization page appears.
2. Enter a unique Organization name Organization names can include numbers, letters, underscores (_), and hyphens (-).
3. Provide an Email address to receive notifications about the organization.
4. Click Create organization.

HCP Terraform shows the new organization and prompts you to create a new workspace. You can also invite other users to join the organization.

Managed resources

Your organization’s managed resource count helps you understand the number of infrastructure resources that HCP Terraform manages across all your workspaces.

HCP Terraform reads all the workspaces’ state files to determine the total number of managed resources. Each resource instance in the state equals one managed resource. HCP Terraform includes resources in modules and each resource created with the count or for_each meta-arguments. HCP Terraform does not include data sources in the count. Refer to Managed Resources Count in the workspace state documentation for more details.

You can view your organization's managed resource count on the Usage page.

Create and manage reserved tags

Tags are key-value pairs that you can apply to projects and workspaces. Tags help you organize your projects and resources, as well as track resource consumption. Refer to the following topics for information about creating and managing tags attached to projects and workspaces:

• Create a project
• Create workspace tags

You can define reserved tag keys for your organization so that project and workspace managers can use consistent labels.

1. Click on Tags in the sidebar to view all tags in your organization.
2. Click on the Reserved Keys tab. You can perform the following actions:
   1. Use the search bar to find a specific tag key.
   2. Click on a column header to sort the table.
   3. Click on the ellipses menu to open the management options for each tag key.
   4. Click New tag key to define a new key.

You can also view single-value tags that workspace managers added directly to their workspaces. Refer to Tags in the organization settings reference for additional information.

Managing settings

To view and manage an organization's settings, click Settings.

The contents of the organization settings depends on your permissions within the organization. All users can review the organization's contact email, view the membership of any teams they belong to, and view the organization's authentication policy. Organization owners can view and manage the entire list of organization settings. Refer to Organization Permissions for details.

You may be able to manage the following organization settings.

Organization settings

General

Review the organization name and contact email. Organization owners can choose to change the organization name, contact email, and the default execution mode, or delete the organization. When an organization owner updates the default execution mode, all workspaces configured to inherit this value will be affected.

Organization owners can also choose whether workspace administrators can delete workspaces that are managing resources. Deleting a workspace with resources under management introduces risk because Terraform can no longer track or manage the infrastructure. The workspace's users must manually delete any remaining resources or import them into another Terraform workspace.

Organization owners using HCP Terraform Plus edition can choose whether members with module management permissions can generate module tests.

Renaming an organization

To rename an organization that manages infrastructure:

1. Alert all members of the organization about the name change.
2. Cancel in progress and pending runs or wait for them to finish. HCP Terraform cannot change the name of an organization with runs in progress.
3. Lock all workspaces to ensure that no new runs will start before you change the name.
4. Rename the organization.
5. Update all components using the HCP Terraform API to the new organization name. This includes Terraform's cloud block CLI integration, the tfe Terraform provider, and any external API integrations.
6. Unlock workspaces and resume normal operations.

Plan & Billing

Review the organization's plan and any invoices for previous plan payments. Organization owners can also upgrade to one of HCP Terraform's paid plans, downgrade to a free plan, or begin a free trial of paid features.

Tags

Click the Tags tab in the Tags Management screen to view single-value tags that workspace managers added directly to their workspaces. For information about key-value tag keys, refer to Create and manage reserved tags.

You can perform the following actions in the Tags tab:

1. Search for a tag key or value.
2. Click on a column header to sort tags.

Teams

All users in an organization can access the Teams page, which displays a list of teams within the organization.

Organization owners and users with the include secret teams permission can:

• view all secret teams
• view each team's membership
• manage team API tokens

HCP Terraform restricts team creation, team deletion, and management of team API tokens to organization owners and users with the manage teams permission. Organization owners and users with the manage membership permission can manage team membership. Remember that users must accept their organization invitations before you can add them to a team.

Users

Organization owners and users with manage membership permissions can invite HCP Terraform users into the organization, cancel invitations, and remove existing members.

The list of users is separated into one tab for active users and one tab for invited users who have not yet accepted their invitations. For active users, the list includes usernames, email addresses, avatar icons, two-factor authentication status, and current team memberships. Use the Search by username or email field to filter these lists.

User invitations are always sent by email; you cannot invite someone using their HCP Terraform username. To invite a user to an organization:

1. Click Invite a user. The invite a user box appears.
2. Enter the user's email address and optionally add them to one or more teams. If the user accepts the invitation, HCP Terraform automatically adds them to the specified teams.

All permissions in HCP Terraform are managed through teams. Users can join an organization without belonging to any teams, but they cannot use Terraform Cloud features until they belong to a team. Refer to permissions for details.

Variable Sets

View all of the available variable sets and their variables. Users with read and write variables permissions can also create variable sets and assign them to one or more workspaces.

Variable sets let you reuse the same variables across multiple workspaces in the organization. For example, you could define a variable set of provider credentials and automatically apply it to several workspaces, rather than manually defining credential variables in each. Changes to variable sets instantly apply to all appropriate workspaces, saving time and reducing errors from manual updates.

Refer to the variables overview documentation for details about variable types, scope, and precedence. Refer to managing variables for details about how to create and manage variable sets.

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 determines whether your real-world infrastructure matches your Terraform configuration. Drift detection requires Terraform version 0.15.4+.
• Continuous validation determines whether custom conditions in the workspace’s configuration continue to pass after Terraform provisions the infrastructure. Continuous validation requires Terraform version 1.3.0+.

You can enforce health assessments for all eligible workspaces or let each workspace opt in to health assessments through workspace settings. Refer to Health in the workspaces documentation for more details.

Runs

From the Workspaces page, click Settings in the sidebar, then Runs to view all of the current runs in your organization's workspaces. The Runs page displays:

• The name of the run
• The run's ID
• What triggered the run
• The workspace and project where the run is taking place
• When the latest change in the run occurred
• A button allowing you to cancel that run

You can apply the following filters to limit the runs HCP Terraform displays:

• Click Needs Attention to display runs that require user input to continue, such as approving a plan or overriding a policy.
• Click Running to display runs that are in progress.
• Click On Hold to display paused runs.

For precise filtering, click More filters and check the boxes to filter runs by specific run statuses, run operations, workspaces, or agent pools. Click Apply filters to list the runs that match your criteria.

You can dismiss any of your filtering criteria by clicking the X next to the filter name above the table displaying your runs.

For more details about run states, refer to Run States and Stages.

Integrations

Cost Estimation

Enable and disable the cost estimation feature for all workspaces.

Policies

Policies let you define and enforce rules for Terraform runs. You can write them using either the Sentinel or Open Policy Agent (OPA) policy-as-code frameworks and then group them into policy sets that you can apply to workspaces in your organization. To create policies and policy sets, you must have permission to manage policies.

Policy Sets

Create groups of policies and enforce those policy sets globally or on specific projects and workspaces. You can create policy sets through the Terraform API, by connecting a VCS repository containing policies, or directly in HCP Terraform. To create policies and policy sets, you must have permission to manage policies.

Refer to Managing Policy Sets for details.

Run Tasks

Manage the run tasks that you can add to workspaces within the organization. Run tasks let you integrate third-party tools and services at specific stages in the HCP Terraform run lifecycle.

Security

Agents

Create and manage HCP Terraform agent pools. HCP Terraform agents let HCP Terraform communicate with isolated, private, or on-premises infrastructure. This is useful for on-premises infrastructure types such as vSphere, Nutanix, OpenStack, enterprise networking providers, and infrastructure within a protected enclave.

API Tokens

Organization owners can set up a special Organization API Token that is not associated with a specific user or team.

Authentication

Organization owners can determine when users must reauthenticate and require two-factor authentication for all members of the organization.

SSH Keys

Manage SSH keys for cloning Git-based modules during Terraform runs. This does not include keys to access a connected VCS provider.

SSO

Organization owners can set up an SSO provider for the organization.

Version Control

VCS General

Configure Automatically cancel plan-only runs triggered by outdated commits to manage the setting.

VCS Events

Review the event logs for GitLab.com connections.

VCS Providers

Configure VCS providers to use in the organization. You must have permission to manage VCS settings.

Destruction and Deletion

Data Retention Policies

An organization owner can set or override the following data retention policies:

• Admin default policy
• Do not auto-delete
• Auto-delete data

Setting the data retention policy to Admin default policy disables the other data retention policy settings.

By default, the Do not auto-delete option is enabled for an organization. This option directs Terraform Enterprise to retain data associated with configuration and state versions, but organization owners can define configurable data retention policies that allow Terraform to soft delete the backing data associated with configuration versions and state versions. Soft deleting refers to marking a data object for garbage collection so that Terraform can delete the object after a set number of days.

Once an object is soft deleted, any attempts to read the object will fail. Until the garbage collection process begins, you can restore soft deleted objects using the APIs described in the configuration version documentation and the state version documentation. Terraform permanently deletes the archivist storage after the garbage collection grace period elapses.

The organization policy is the default policy applied to all workspaces, but members of individual workspaces can set overriding policies for their workspaces that take precedence over the organization policy.

Trial Expired Organizations

HCP Terraform paid features are available as a free trial. When a free trial has expired, the organization displays a banner reading TRIAL EXPIRED — Upgrade Required.

Organizations with expired trials return to the feature set of a free organization, but they retain any data created as part of paid features. Specifically, HCP Terraform disables the following features:

• Teams other than owners and locks users who do not belong to the owners team out of the organization. HCP Terraform preserves team membership and permissions and re-enables them after you upgrade the organization.
• Sentinel policy checks. HCP Terraform preserves existing policies and policy sets and re-enables them after you upgrade the organization.
• Cost estimation.