Terraform Cloud Foundation

Code which manages configuration and life-cycle of all the Terraform Cloud foundation. It is designed to be used from a dedicated VCS-Driven Terraform Cloud workspace that would provision and manage the configuration using Terraform code (IaC). It uses Hashicorp Vault Secrets to manage secrets.

Permissions

Terraform Cloud Permissions

To manage the resources from that code, provide a token from an account with owner permissions. Alternatively, you can use a token from the owner team instead of a user token.

Hashicorp Vault Secrets Permissions

To manage secrets in Hashicorp Vault Secrets, provide a client ID and a key from a service principals with the secret contributor role.

GitHub Permissions

To manage the GitHub resources, provide a token from an account or a GitHub App with appropriate permissions. It should have:

• Read access to metadata
• Read and write access to administration, code, members, and secrets

Authentication

Terraform Cloud Authentication

The Terraform Cloud provider requires a Terraform Cloud/Enterprise API token in order to manage resources.

• Set the TFE_TOKEN environment variable: The provider can read the TFE_TOKEN environment variable and the token stored there to authenticate. Refer to Managing Variables documentation for more details.

Hashicorp Vault Secrets Authentication

The Hashicorp Vault Secrets provider requires a service principal client ID and a key in order to manage resources.

• Set the HCP_CLIENT_ID environment variable: The provider can read the HCP_CLIENT_ID environment variable and the client ID stored there to authenticate. Refer to Managing Variables documentation for more details.

• Set the HCP_CLIENT_SECRET environment variable: The provider can read the HCP_CLIENT_SECRET environment variable and the client ID stored there to authenticate. Refer to Managing Variables documentation for more details.

GitHub Authentication

The GitHub provider requires a GitHub App installation in order to manage resources.

• Set the GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, GITHUB_APP_PEM_FILE, and GITHUB_OWNER environment variables. The provider can read the GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, GITHUB_APP_PEM_FILE, and GITHUB_OWNER environment variables to authenticate.

Because strings with new lines is not support:
use "\\n" within the pem_file argument to replace new line
use "\n" within the GITHUB_APP_PEM_FILE environment variables to replace new line

Features

• Manages configuration and life-cycle of Terraform Cloud resources:
  • projects
  • workspaces
  • teams
  • variable sets
  • variables
  • notifications
  • run tasks
• Manages configuration and life-cycle of GitHub resources:
  • repositories
  • branches protection
  • repositories secrets
  • teams
• Manages configuration and life-cycle of Hashicorp Vault Secrets
  • app
  • secrets

Prerequisite

In order to deploy the configuration from this code, you must first create an organization. You must then manually create a dedicated VCS-driven Terraform Cloud workspace in the UI.

In order to read secrets from Hashicorp Vault Secrets, you must first create an organization in Hashicorp Cloud. You must manually create a project, an application, the secrets, a service principale with read permission and create a key in the UI.

To authenticate into Terraform Cloud during configuration deployment, an API token must be created. This token must come from an account with owner permission or the owner team. An environment variable TFE_TOKEN must be created in the previously created workspace with the value of the generated token.

To authenticate into Hashicorp Vault Secrets during deployment, a service principal with a key must be created. HCP_CLIENT_ID and HCP_CLIENT_SECRET environment variables must be create in the previously created workspace with the value of the generated key.

To authenticate into GitHub during deployment, a GitHub App with the required permission must be created. GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, GITHUB_APP_PEM_FILE, and GITHUB_OWNER environment variables must be create in the previously created workspace with the value of the generated key.

Documentation

Requirements

The following requirements are needed by this module:

• terraform (> 1.6.0)

• github (~>5.44)

• hcp (~>0.76)

• tfe (~>0.51)

Modules

The following Modules are called:

git_repository

Source: ./modules/git_repository

Version:

git_teams

Source: ./modules/git_team

Version:

tfe_agent

Source: ./modules/tfe_agent

Version:

tfe_notifications

Source: ./modules/tfe_notification

Version:

tfe_teams

Source: ./modules/tfe_team

Version:

tfe_workspaces

Source: ./modules/tfe_workspace

Version:

Required Inputs

No required inputs.

Optional Inputs

No optional inputs.

Resources

The following resources are used by this module:

• github_actions_secret.this (resource)
• hcp_vault_secrets_app.this (resource)
• hcp_vault_secrets_secret.this (resource)
• tfe_project.project (resource)
• tfe_project_variable_set.this (resource)
• tfe_variable.variable_set (resource)
• tfe_variable.workspace (resource)
• tfe_variable_set.this (resource)
• tfe_workspace_variable_set.this (resource)
• hcp_vault_secrets_secret.this (data source)
• tfe_oauth_client.client (data source)
• tfe_organization.this (data source)
• tfe_organization_membership.this (data source)
• tfe_organization_run_task.this (data source)
• tfe_workspace.this (data source)

Outputs

The following outputs are exported:

manage_modules_team_token

Description: The token of the team with manage-modules access.

modules_registry_github_contributors_team

Description: The id of the GitHub team who can contribute to the private modules registry.

modules_registry_github_owners_team

Description: The id of the GitHub team who owns the private modules registry.