Organizations are a shared space for one or more teams to collaborate on workspaces.
API and Terraform Enterprise Provider
In addition to the Terraform Cloud UI, you can use the following methods to manage organizations:
- Organizations API
Terraform Cloud displays your current organization in the bottom left of the sidebar. To select an organization:
- Click the current organization name to view a list of all the organizations where you are a member.
- Click an organization to select it. Terraform Cloud displays list of workspaces within that organization.
Joining and Leaving Organizations
To join an organization, you must be invited by one of its owners and must accept the emailed invitation. Refer to Organization Settings: Users for details.
You can leave an organization from your user account settings. Refer to User Settings: Organizations for details.
On Terraform Enterprise, administrators can restrict your ability to create organizations. Refer to Administration: General Settings for details.
On Terraform Cloud, any user can create a new organization. If you do not belong to any organizations, Terraform Cloud prompts you to create one the first time you log in. To create an organization:
- Click the current organization name and select Create new organization. The Create a new organization page appears.
- Enter a unique Organization name Organization names can include numbers, letters, underscores (
_), and hyphens (
- Provide an Email address to receive notifications about the organization.
- Click Create organization.
Terraform Cloud shows the new organization and prompts you to create a new workspace. You can also invite other users to join the organization.
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 permissions.
Review the organization name and contact email. Organization owners can also change the organization name and contact email or delete the organization.
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.
Renaming an Organization
Warning: Deleting or renaming an organization can be very disruptive. We strongly recommend against deleting or renaming organizations with active members.
To rename an organization that manages infrastructure:
- Alert all members of the organization about the name change.
- Cancel in progress and pending runs or wait for them to finish. Terraform Cloud cannot change the name of an organization with runs in progress.
- Lock all workspaces to ensure that no new runs will start before you change the name.
- Rename the organization.
- Update all components using the Terraform Cloud API to the new organization name. This includes Terraform's
cloudblock CLI integration, the
tfeTerraform provider, and any external API integrations.
- 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 Terraform Cloud's paid plans, downgrade to a free plan, or begin a free trial of paid features.
Review a list of tags for all resources across the organization. When you delete a tag from this page, Terraform Cloud removes it from all resources.
Note: Team management is a paid feature, available as part of the Team upgrade plan. Free plan organizations only include an owners team that can include up to five members. Refer to Terraform Cloud pricing for details.
All users in an organization can access the Teams page, which displays a list of teams within the organiation. This excludes secret teams where you are not a member. You can also view team membership and manage team API tokens.
Organization owners can also create and delete teams, and manage team API tokens. Both owners and users with Manage Membership permissions can manage the membership of teams. Remember that users must accept an invitation to the organization before you can add them to teams.
Organization owners and users with Manage Membership permissions can invite Terraform Cloud 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 Terraform Cloud username. To invite a user to an organization:
- Click Invite a user. The invite a user box appears.
- Enter the user's email address and optionally add them to one or more teams. If the user accepts the invitation, Terraform Cloud will be automatically add them to the specified teams.
All permissions in Terraform Cloud are managed through teams. Users can join an organization without belonging to any teams, but they cannot use Teraform Cloud features until they belong to a team. Refer to permissions for details.
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.
Note: Health assessments are available in the Terraform Cloud Business tier. Continuous validation is in beta and not available in Terraform Enterprise.
Terraform Cloud 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 the configuration in your Terraform state file. 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.
Note: Cost estimation is a paid feature, available as part of the Team & Governance plan. Refer to Terraform pricing for details.
Enable and disable the cost estimation feature for all workspaces.
Note: Policies are available in the Terraform Cloud Team and Governance tier.
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.
Note: Policies are available in the Terraform Cloud Team and Governance tier.
Create groups of policies and assign those policy sets to workspaces. You can create policy sets through the Terraform API, by connecting a VCS repository containing policies, or directly in Terraform Cloud. To create policies and policy sets, you must have permission to manage policies.
Refer to Managing Policy Sets for details.
Note: Run Tasks is a paid feature, available as part of the Team & Governance upgrade package. Refer to Terraform Cloud pricing for details.
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 Terraform Cloud run lifecycle.
Note: Terraform Cloud Agents are a paid feature, available as part of the Business plan. Refer to Terraform pricing for details.
Create and manage Terraform Cloud agent pools. Terraform Cloud Agents let Terraform Cloud 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.
Organization owners can set up a special Organization API Token that is not associated with a specific user or team.
Organization owners can determine when users must reauthenticate and require two-factor authentication for all members of the organization.
Manage SSH keys for cloning Git-based modules during Terraform runs. This does not include keys to access a connected VCS provider.
Note: Single sign-on is a paid feature, available as part of the Business plan. Refer to Terraform pricing for details.
Organization owners can set up an SSO provider for the organization.
Workspaces that use part of a shared repository do not typically run plans for changes that do not affect their files. This includes speculative plans on pull requests. Since pending status checks can block pull requests, workspaces automatically send passing commit statuses for any PRs that do not affect their files.
You can disable this behavior if it creates too many status checks to your VCS provider. You may want to do this if you have a large number of workspaces sharing one VCS repository.
Note: This feature is in beta.
Review the event logs for GitLab.com connections.
Configure VCS providers to use in the organization. You must have permission to manage VCS settings.
Trial Expired Organizations
Terraform Cloud 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, Terraform Cloud disables the following features:
- Teams other than
ownersand locks users who do not belong to the
ownersteam out of the organization. Terraform Cloud preserves team membership and permissions and re-enables them after you upgrade the organization.
- Sentinel policy checks. Terraform Cloud preserves existing policies and policy sets and re-enables them after you upgrade the organization.
- Cost estimation.