Organizations overview

An organization is collection of one or more projects. This topic provides an overview of creating and managing organizations in HCP Terraform and Terraform Enterprise. Refer to Organization settings for information about available organization settings.

Requirements

You must have Admin level-permissions to manage organizations in the HCP Terraform UI. Refer to Permissions to learn more.

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

Select an organization

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

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

Join an organization

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.

Leave an organization

1. Sign in to HCP Terraform or Terraform Enterprise and click the Terraform logo in the page header to navigate to the Organizations page.
2. Open the ... ellipses menu 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.

Create an organization

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 sign 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 and Stacks.

HCP Terraform reads all the workspace and Stack deployment 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 tag keys

You can define reserved tag keys that appear as suggested labels when managers want to add tags to their projects and workspaces in the organization. Refer to Create and manage reserved tag keys for instructions.

You can also view single-value tags that may already be attached to projects and workspaces. Refer to Tags in the organization settings reference for additional information.

Manage organization 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 view the organization's contact email, the membership of any teams they belong to, and the organization's authentication policy. Refer to Organization settings for information about organization settings.

Rename an organization

To rename an organization that manages infrastructure:

1. Alert all members of the organization about the name change.
2. Sign in to HCP Terraform or Terraform Enterprise and navigate to the organization you want to rename.
3. 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.
4. Lock all workspaces to ensure that no new runs will start before you change the name.
5. Rename the organization.
6. 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.
7. Unlock workspaces and resume normal operations.

Manage tags

Click the Tags tab in the Tags Management screen to view tags attached to platform resources.

Click the Reserved Keys tab to view and manage reserved keys, which you can use to standardize metadata about projects and workspaces in your organization. Refer to Create and manage reserved tag keys for more information.

Click on the Workspace-only Tags tab to view single-value tags that may have already been created in your system. The table on lists the tags in the system, the number of times a tag appears in a project or workspace, and the date the tag was created.

The only action you can perform in the UI is deleting single-value tags from the system. You can use the following methods to delete single-value tags:

1. Select one or more tags and click Delete tags.
2. Select the Name header to select all tags, then click Delete tags.
3. Click the trash icon for a tag and confirm that you want to permanently delete it when prompted.

Invite users to the organization

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 HCP Terraform features until they belong to a team. Refer to permissions for details.

View organization 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 workspace run states, refer to Run States and Stages.

To learn how to view Stack deployment runs, refer to Review deployment runs.

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.