hcp-terraform-admin

An infrastructure as code repository to manage an HCP Terraform organization.

Manual Setup

The following steps must be taken before being able to run the code in this repository.

HashiCorp Cloud Platform

1. Create an HCP account.
2. Create an HCP organization.
3. Create an HCP project.

HCP Terraform

1. Create an HCP Terraform organization.
2. Run terraform login to generate a user API token.
3. Update backend.tf to point to your HCP Terraform organization. You can modify workspace and project as well but not sugggested.
4. Run terraform init to create the backend workspace.
5. Manually generate a team API token for the "owners" team.
6. Manually create a variable set for the purpose of authenticating the TFE provider.
7. Populate the variable set with the TFE_TOKEN environment variable, using the API token as the (sensitive) value.
8. Assign the variable set to the backend workspace.
9. Create a terraform.tfvars file with the values for your HCP Terraform organization.
10. Generate a locals_imports.tf file with the IDs of the resources in your HCP Terraform organization.

Generate locals_imports.tf

To generate a locals block containing the IDs of the resources to bring under management, review and run the script in .local/bin/generate_locals_imports:

export TF_TOKEN_app_terraform_io="{{your token}}"; /bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/craigsloggett-lab/hcp-terraform-admin/refs/heads/main/.local/bin/generate_locals_imports)"

VCS Integration with GitHub

In order to scope the list of repositories shown to users when creating a VCS backed workspace, it is necessary to create and install a custom GitHub App in your GitHub organization using a service account. Using a service account is not strictly required but is recommended in order to ensure only repositories for an organization are listed--not those belonging to a user.

Creating a GitHub Service Account

Create a GitHub service account by navigating to https://github.com/signup and creating a new user with a unique email and username. This user is like any other human user, but will be configured with a private profile and own no repositories.

Add the Service Account to the GitHub Organization

Once created, add the service account as an owner of the GitHub organization being integrated with HCP Terraform.

Create a GitHub App in the GitHub Organization

Navigate to GitHub organization settings -> Developer settings -> GitHub Apps to create a new GitHub App for the organization (not an individual user).

The GitHub App name, Homepage URL, and Callback URL fields will be populated with information generated in HCP Terraform so scroll past these parameters for now.

Uncheck the Webhook -> Active checkbox as this is not needed.

Expand the Repository permissions section and change the following options (from the defaults):

• Commit statuses: Read and write
• Contents: Read-only
• Metadata: Read-only
• Webhooks: Read and write

Ensure the GitHub App can only be installed on this account (which should show the organization as the account).

Pause here and open a new window/tab with the HCP Terraform organization open and logged in as a user with access to add a VCS Provider.

Add a VCS Provider

Navigate to HCP Terraform organization settings -> Version Control -> Providers to Add a VCS provider. Select GitHub -> GitHub.com (Custom) to display the information needed to populate the GitHub App creation form.

Back in the GitHub App creation window/tab, copy the Application name, Homepage URL, and Authorization callback URL into the relevant fields in the GitHub App configuration.

Click Create GitHub App and copy the Client ID into the Add VCS Provider window in HCP Terraform and give the VCS Provider the same name as the GitHub organization being configured.

Finally, in the GitHub App, Generate a new client secret, and copy the secret into the Add VCS Provider window in HCP Terraform.

Click Connect and continue to begin the authorization workflow between HCP Terraform and GitHub. At this point it is important to be logged into GitHub using your service account created earlier, not your user account. It is important to note that the email used for the GitHub service account does not need to be a member of the HCP Terraform organization.

Requirements

Name	Version
terraform	~> 1.6
tfe	0.63.0

Providers

Name	Version
tfe	0.63.0

Modules

No modules.

Resources

Name	Type
tfe_organization.this	resource
tfe_organization_membership.owners	resource
tfe_project.backend	resource
tfe_project.default	resource
tfe_project.modules	resource
tfe_project_variable_set.modules	resource
tfe_registry_module.terraform_aws_tfe_fdo_docker_active_active	resource
tfe_registry_module.terraform_aws_vpc	resource
tfe_registry_provider.hashicorp	resource
tfe_team.admins	resource
tfe_team.owners	resource
tfe_team_organization_members.admins	resource
tfe_team_organization_members.owners	resource
tfe_team_project_access.backend	resource
tfe_team_project_access.default	resource
tfe_team_project_access.modules	resource
tfe_test_variable.tfe_license	resource
tfe_variable_set.aws_provider_authentication	resource
tfe_variable_set.tfe_provider_authentication	resource
tfe_workspace.backend	resource
tfe_workspace_variable_set.backend	resource
tfe_oauth_client.github	data source
tfe_organization_membership.admins	data source

Inputs

Name	Description	Type	Default	Required
admins_team_emails	A list of member email addresses for the admins team.	set(string)	[]	no
aws_provider_authentication_variable_set_name	The name of the variable set used to authenticate the AWS provider.	string	"AWS Provider Authentication"	no
backend_project_name	The name of the project used to manage this HCP Terraform organization.	string	n/a	yes
backend_vcs_repository_name	The name of the GitHub repository backing the backend workspace.	string	n/a	yes
backend_workspace_name	The name of the workspace used to manage this HCP Terraform organization.	string	n/a	yes
github_organization_name	The name of the GitHub organization used as the VCS provider.	string	n/a	yes
hcp_terraform_admins_team_name	The name of the team of users who administer the HCP Terraform organization.	string	"admins"	no
hcp_terraform_organization_email	The notification email address for the HCP Terraform organization being managed.	string	n/a	yes
hcp_terraform_organization_name	The name of the HCP Terraform organization being managed.	string	n/a	yes
owners_team_emails	A list of member email addresses for the owners team.	set(string)	[]	no
terraform_version	The version of Terraform to use in all workspaces.	string	"1.10.3"	no
tfe_provider_authentication_variable_set_name	The name of the variable set used to authenticate the TFE provider.	string	"TFE Provider Authentication"	no

Outputs

No outputs.