Getting Started with Terraform Enterprise
Mar 16, 2018
This is a guided tutorial to setup Terraform Enterprise for a team of operators.
Infrastructure as Code: Terraform uses an infrastructure as code approach to provide effective, reusable, and safe infrastructure provisioning automation. This approach enables operators to increase their productivity, move quicker, and reduce human error.
Safe, Efficient Workflow: Terraform provides one consistent workflow for developers and operators to provision resources on any infrastructure provider. One workflow to learn increases user productivity, and also reduces organizational risk as that becomes one workflow to secure, one workflow to audit, and one workflow to govern.
Provision Any Infrastructure: Terraform providers are plug-in components to Terraform and interact with each infrastructure provider. There are currently over 100+ providers— and this number continually increases through the support of over 1100+ contributors.
This guide introduces the Terraform Enterprise setup and workflow for a team of operators to safely and efficiently collaborate on infrastructure. The guide will focus on a smaller team that includes a team lead (or manager) and multiple team members (infrastructure operators). The team lead will begin the guided tutorial by creating the organization in the Terraform Enterprise application. Each team member will then join this organization as you work through the tutorial.
After completing Getting Started with Terraform Enterprise you will have the basic setup complete and able to move to the next tutorial where your team members can work together to create, share, and provision validated and versioned modules of infrastructure.
For planning purposes, we expect the steps in this guide to take no more than 20 minutes. The below video walks through the steps and can be used to help you complete the guided tutorial.
- Basic familiarity with VCS.
- Create or have access to an existing public VCS repo from the supported list. The list is available in our docs: Connecting VCS Providers to Terraform Enterprise
- Request a free trial: To start your trial registration you will need to request to start a Terraform Enterprise Trial. Navigate to Get started with Terraform Enterprise or contact HashiCorp sales to purchase a Terraform Enterprise subscription. The sales contact will review and provide a link to register with Terraform Enterprise.
Create an account
Terraform Enterprise trial is available through the Terraform Enterprise Service, available at https://app.terraform.io/. To register for your trial, navigate to the link provided by your sales account manager, and enter your email, desired username and password, then click “Create an Account”.
You will receive an automated email to the account you registered with asking for you to confirm your email address.
Click the hyperlink in your email to confirm registration and you will be logged into Terraform Enterprise via your browser.
Create an organization
The first thing Terraform Enterprise will prompt you to do is create a new organization. An organization is the unit that each team member will join as they become a user of Terraform Enterprise. Organizations in Terraform are a shared space for teams to create, collaborate, and share infrastructure within workspaces (units for organizing infrastructure). Organization owners set which teams have read, write, and admin privileges on which workspaces.
Enter a name and an admin email address at the prompt.
As you configure your organization name, know that an organization can have many teams, and the owners of the organization set which teams have which privileges (read/write/admin) on which workspaces. This name will need to be unique within the SaaS platform.
As an Organization is set up, additional users would be setup and added to groups for collaboration. For this first step, we’ll assume that there is only one user that is part of the organization.
https://app.terraform.io/app/organizations/new in your browser, and enter an organization name and email address. The organization name can be any name to your liking as long as it wasnt already taken by another trial user.
A “Success” message will be presented with the option to create a new workspace.
Before creating a workspace, we will perform a few other administrative tasks.
Configure Version Control System
You'll need to configure VCS access when first setting up a TFE organization. Version control system integration is a key part of Terraform Enterprise, enabling each team member to contribute their infrastructure as code (Terraform configurations or Terraform modules) to be reviewed, versioned, and shared with other operators within the organization.
If you've never used version control, please reference the following guides. If you need help, please email the SE trial contract at email@example.com
To get started, you will need to enable VCS access by creating a new application configuration on your VCS service, telling TFE how to reach your VCS, exchanging some secret information between them, and requesting access. Each supported VCS service has slightly different instructions for this. Reference the instructions for your primary VCS below:
Navigate to OAuth Configuration under “organization settings” and click “Add an OAuth Client”.
Select your VCS provider in the dropdown, and follow the instructions according to your VCS provider referencing the documentation above.
After following the instructions for your VCS and clicking the “Connect Organization” button you will see a list of OAuth Clients. You may connect to one or more VCS sources from TFE.
Create a Workspace
Workspaces are how TFE organizes infrastructure. A workspace consists of:
- A collection of Terraform configurations (retrieved from a VCS repo).
- Values for any variables those configurations require.
- Persistent stored state for the resources it manages.
A well-designed Terraform workflow uses multiple configurations, so you can manage each logical grouping of infrastructure with its own code. Additionally, it's common to use the same configuration multiple times (with different values for variables) to manage different environments.
Navigate to Terraform Enterprise homepage. If you're still on the VCS settings (or any other page), click the Terraform logo button in the upper left and choose "Terraform Enterprise". This view provides a list of the workspaces you have access to; if you haven't created any, it's empty. To create your first workspace, click the "+ New Workspace" button in the upper right. On the "Create a new Workspace" page, you need to enter at least two items: a workspace name, and a VCS repository. (You can search for a repo by typing part of its name.) When you've finished, click the "Create Workspace" button.
Navigate to the Terraform Enterprise homepage and click the "+ New Workspace" button.
Enter a workspace name, select a VCS repository then click the "Create Workspace" button.
A success message will appear at the bottom of the screen and you will receive a prompt to configure variables which will be discussed in the next section.
Add and edit variables for a Workspace
Workspaces have Terraform variables and environment variables used by the code and you can edit variables as soon as you've created a workspace, by clicking the workspace's "Variables" tab. A variable might be a credentials for a cloud provider (username and key) or a cloud region. These enable simple code reuse by changing the variable to adapt it to an operators requirements.
The variables page has three sections: Terraform variables (as declared in your Terraform configurations), and environment variables. Terraform variables start as basic string values, but you can also enter array or map values if you click the "HCL" checkbox for that variable. You can write these values with the same syntax you'd use in a Terraform configuration. To edit one of these sections, click the "Edit" control. You can then add, modify, or delete variables. Make sure to click "Save" or "Save & Plan" once you've finished editing.
Click the “Configure Variables” button.
Click the “Edit” link next to the radio button corresponding to Terraform Variables or Environment Variables.
Click “Save” to save the contents of your variable and run the plan later. You should receive a success message at the bottom of the screen.
Add team members
Enable team collaboration by adding Other Operators to the Organization. To collaborate with your colleagues in TFE, you will all need access to the same TFE organization. First, each user should self register to TFE as described in Step 1.
You can then add users to an organization by creating a team and adding users to it. First, navigate to the settings page for your organization which can be reached from the organization dropdown menu at the top of every page.
Once there, click the "Teams" link in the sidebar navigation. The list of teams starts with just one team, named "owners." Don't add users to this team yet; instead, enter a new team name (like "core-infrastructure") in the text field and click the "Create team" button.
Once the team is created, click its name and add as many users as you'd like by typing their TFE username in the text field and clicking "Add user." Note, these users should have already signed up to TFE. More in this later. Added users won't receive a notification, but your organization will be available the next time they access TFE.
There are three levels of permissions available:
Read access lets team members view the Workspace's variables and settings, view its run history, and view its StateVersions and ConfigurationVersions. They can't queue run plans, apply existing run plans, or change any variables or settings.
Write access lets team members create and approve runs, and lock or unlock the workspace. It doesn't let them change variables or settings.
Admin access lets team members change variables and settings, add other teams to the workspace, remove other teams from the workspace, and delete the workspace.
Under “organization settings”, click “Teams”.
Enter a team name like “prodaws”,“devazure” or any name of your liking then click “Create team”. You should receive a “success” message and the resulting screen which invites you to add users to the team.
Add users to the team by entering their TFE username and clicking “Add user”.You should receive a “success” message upon adding each user.
If you received a “Error Adding user” message, then you need to ensure that the potential team member has already signed into TFE. You need to send new users the signup link located at https://app.terraform.io/account/new. Ensure that this new user DOES NOT create a new organization when prompted. Once the user has been created you can then return to adding this user as a new member in the team.
Click the “Teams” link on the left hand side of the page to view a summary of the teams and members in your organization.
You have completed the first steps to using Terraform Enterprise and are ready for the next tutorial where your team members can work together to create, share, and provision validated and versioned modules of infrastructure.