HCP Terraform Foundation

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

Permissions

HCP Terraform 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.

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, secrets, and members.

Authentication

HCP Terraform Authentication

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

There are several ways to provide the required token:

• Set the token argument in the provider configuration. You can set the token argument in the provider configuration. Use an input variable for the token.
• Set the TFE_TOKEN environment variable. The provider can read the TFE_TOKEN environment variable and the token stored there to authenticate.

GitHub Authentication

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

There are several ways to provide the required token:

• Set the token argument in the provider configuration. You can set the token argument in the provider configuration. Use an input variable for the token.
• Set the GITHUB_TOKEN environment variable. The provider can read the GITHUB_TOKEN environment variable and the token stored there to authenticate.

There are several ways to provide the required GitHub App installation:

• Set the app_auth argument in the provider configuration. You can set the app_auth argument with the id, installation_id and pem_file in the provider configuration. The owner parameter is also required in this situation.
• Set the GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID and GITHUB_APP_PEM_FILE environment variables. The provider can read the GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID and GITHUB_APP_PEM_FILE 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 HCP Terraform resources:
  • projects
  • workspaces
  • teams
  • variable sets
  • variables
  • notifications
  • run tasks

Prerequisite

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

To authenticate into HCP Terraform 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.

Documentation

Requirements

The following requirements are needed by this module:

• terraform (>= 1.13.0)

• github (~> 6.8.0)

• tfe (~>0.70)

Modules

The following Modules are called:

agent_pool

Source: ./modules/tfe_agent

Version:

modules_factory_git_teams

Source: ./modules/git_team

Version:

modules_factory_repository

Source: ./modules/git_repository

Version:

modules_factory_team_git

Source: ./modules/tfe_team

Version:

modules_factory_team_hcp

Source: ./modules/tfe_team

Version:

modules_factory_workspace

Source: ./modules/tfe_workspace

Version:

policies_factory_git_teams

Source: ./modules/git_team

Version:

policies_factory_repository

Source: ./modules/git_repository

Version:

policies_factory_team_git

Source: ./modules/tfe_team

Version:

policies_factory_team_hcp

Source: ./modules/tfe_team

Version:

policies_factory_workspace

Source: ./modules/tfe_workspace

Version:

projects_factory_git_teams

Source: ./modules/git_team

Version:

projects_factory_repository

Source: ./modules/git_repository

Version:

projects_factory_team_git

Source: ./modules/tfe_team

Version:

projects_factory_team_hcp

Source: ./modules/tfe_team

Version:

projects_factory_workspace

Source: ./modules/tfe_workspace

Version:

repositories_factory_git_teams

Source: ./modules/git_team

Version:

repositories_factory_repository

Source: ./modules/git_repository

Version:

repositories_factory_team_git

Source: ./modules/tfe_team

Version:

repositories_factory_team_hcp

Source: ./modules/tfe_team

Version:

repositories_factory_workspace

Source: ./modules/tfe_workspace

Version:

teams

Source: ./modules/tfe_team

Version:

workspaces_factory_git_teams

Source: ./modules/git_team

Version:

workspaces_factory_repository

Source: ./modules/git_repository

Version:

workspaces_factory_team_git

Source: ./modules/tfe_team

Version:

workspaces_factory_team_hcp

Source: ./modules/tfe_team

Version:

workspaces_factory_workspace

Source: ./modules/tfe_workspace

Version:

Required Inputs

The following input variables are required:

organization_email

Description: (Required) Admin email address.

Type: string

organization_name

Description: (Required) Name of the organization.

Type: string

Optional Inputs

The following input variables are optional (have default values):

agent_pools

Description: (Optional) A list with the name of all the agent pools available at the organization level.

Type: list(string)

Default: []

aggregated_commit_status_enabled

Description: (Optional) Whether or not to enable Aggregated Status Checks. This can be useful for monorepo repositories with multiple workspaces receiving status checks for events such as a pull request. If enabled, send_passing_statuses_for_untriggered_speculative_plans needs to be false. Default to true.

Type: bool

Default: true

allow_force_delete_workspaces

Description: (Optional) Whether workspace administrators are permitted to delete workspaces with resources under management. If false, only organization owners may delete these workspaces. Defaults to false.

Type: bool

Default: false

assessments_enforced

Description: (Optional) Whether to force health assessments (drift detection) on all eligible workspaces or allow workspaces to set their own preferences. Default to true.

Type: bool

Default: true

collaborator_auth_policy

Description: (Optional) Authentication policy. Valid values are password or two_factor_mandatory. Default to two_factor_mandatory.

Type: string

Default: "two_factor_mandatory"

cost_estimation_enabled

Description: (Optional) Whether or not the cost estimation feature is enabled for all workspaces in the organization. Defaults to true.

Type: bool

Default: true

default_execution_mode

Description: (Optional) Which execution mode to use as the default for all workspaces in the organization. Valid values are remote, local or agent. Default to remote.

Type: string

Default: "remote"

hcp_foundation_project_description

Description: (Optional) A description for the project in HCP Terraform.

Type: string

Default: null

hcp_foundation_project_name

Description: (Optional) Name of the project in HCP Terraform.

Type: string

Default: "HCP Terraform"

hcp_foundation_project_tags

Description: (Optional) A map of key-value tags to add to the project in HCP Terraform.

Type: map(string)

Default: null

modules_factory_agent_pool_id

Description: (Optional) The ID of an agent pool to assign to the workspace for the modules factory. Requires execution_mode to be set to agent. This value must not be provided if execution_mode is set to any other value.

Type: string

Default: null

modules_factory_description

Description: (Optional) A description for the workspacel for the modules factory.

Type: string

Default: "Code to provision and manage HCP Terraform modules using Terraform code (IaC)."

modules_factory_execution_mode

Description: (Optional) Which execution mode to use for the modules factory. Using Terraform Cloud, valid values are remote, local or agent. When set to local, the workspace will be used for state storage only. Important: If you omit this attribute, the resource configures the workspace to use your organization's default execution mode (which in turn defaults to remote), removing any explicit value that might have previously been set for the workspace.

Type: string

Default: null

modules_factory_github_teams

Description: (Optional) The modules_factory_github_teams block supports the following:
name : (Required) The name of the team.
description : (Optional) A description of the team.
permission : (Optional) The permissions of team members regarding the repository. Must be one of pull, triage, push, maintain, admin or the name of an existing custom repository role within the organisation.

Type:

list(object({
    name        = string
    description = optional(string)
    permission  = optional(string, "pull")
  }))

Default:

[
  {
    "description": "This group grant write access to the HCP Terraform modules repository.",
    "name": "HCPTerraform-ModulesFactory-Contributors",
    "permission": "push"
  }
]

modules_factory_tag

Description: (Optional) A map of key value tags for this workspace for the modules factory.

Type: map(string)

Default: null

modules_factory_workspace_name

Description: (Optional) Name of the workspace for the modules factory.

Type: string

Default: "HCPTerraform-ModulesFactory"

owners_team_saml_role_id

Description: (Optional) The name of the "owners" team.

Type: string

Default: null

policies_factory_agent_pool_id

Description: (Optional) The ID of an agent pool to assign to the workspace for the policies factory. Requires execution_mode to be set to agent. This value must not be provided if execution_mode is set to any other value.

Type: string

Default: null

policies_factory_description

Description: (Optional) A description for the workspacel for the policies factory.

Type: string

Default: "Code to provision and manage HCP Terraform policies using Terraform code (IaC)."

policies_factory_execution_mode

Description: (Optional) Which execution mode to use for the policies factory. Using Terraform Cloud, valid values are remote, local or agent. When set to local, the workspace will be used for state storage only. Important: If you omit this attribute, the resource configures the workspace to use your organization's default execution mode (which in turn defaults to remote), removing any explicit value that might have previously been set for the workspace.

Type: string

Default: null

policies_factory_github_teams

Description: (Optional) The policies_factory_github_teams block supports the following:
name : (Required) The name of the team.
description : (Optional) A description of the team.
permission : (Optional) The permissions of team members regarding the repository. Must be one of pull, triage, push, maintain, admin or the name of an existing custom repository role within the organisation.

Type:

list(object({
    name        = string
    description = optional(string)
    permission  = optional(string, "pull")
  }))

Default:

[
  {
    "description": "This group grant write access to the HCP Terraform Policies repository.",
    "name": "HCPTerraform-Policies-Contributors",
    "permission": "push"
  }
]

policies_factory_tag

Description: (Optional) A map of key value tags for this workspace for the policies factory.

Type: map(string)

Default: null

policies_factory_workspace_name

Description: (Optional) Name of the workspace for the policies factory.

Type: string

Default: "HCPTerraform-PoliciesFactory"

projects_factory_agent_pool_id

Description: (Optional) The ID of an agent pool to assign to the workspace for the projects factory. Requires execution_mode to be set to agent. This value must not be provided if execution_mode is set to any other value.

Type: string

Default: null

projects_factory_description

Description: (Optional) A description for the workspace for the projects factory.

Type: string

Default: "Code to provision and manage HCP Terraform projects using Terraform code (IaC)."

projects_factory_execution_mode

Description: (Optional) Which execution mode to use for the projects factory. Using Terraform Cloud, valid values are remote, local or agent. When set to local, the workspace will be used for state storage only. Important: If you omit this attribute, the resource configures the workspace to use your organization's default execution mode (which in turn defaults to remote), removing any explicit value that might have previously been set for the workspace.

Type: string

Default: null

projects_factory_github_teams

Description: (Optional) The projects_factory_github_teams block supports the following:
name : (Required) The name of the team.
description : (Optional) A description of the team.
permission : (Optional) The permissions of team members regarding the repository. Must be one of pull, triage, push, maintain, admin or the name of an existing custom repository role within the organisation.

Type:

list(object({
    name        = string
    description = optional(string)
    permission  = optional(string, "pull")
  }))

Default:

[
  {
    "description": "This group grant write access to the HCP Terraform projects repository.",
    "name": "HCPTerraform-ProjectsFactory-Contributors",
    "permission": "push"
  }
]

projects_factory_tag

Description: (Optional) A map of key value tags for this workspace for the projects factory.

Type: map(string)

Default: null

projects_factory_workspace_name

Description: (Optional) Name of the workspace for the projects factory.

Type: string

Default: "HCPTerraform-ProjectsFactory"

repositories_factory_agent_pool_id

Description: (Optional) The ID of an agent pool to assign to the workspace for the repositories factory. Requires execution_mode to be set to agent. This value must not be provided if execution_mode is set to any other value.

Type: string

Default: null

repositories_factory_description

Description: (Optional) A description for the workspace for the repositories factory.

Type: string

Default: "Code to provision and manage GitHub repositories using Terraform code (IaC)."

repositories_factory_execution_mode

Description: (Optional) Which execution mode to use for the repositories factory. Using Terraform Cloud, valid values are remote, local or agent. When set to local, the workspace will be used for state storage only. Important: If you omit this attribute, the resource configures the workspace to use your organization's default execution mode (which in turn defaults to remote), removing any explicit value that might have previously been set for the workspace.

Type: string

Default: null

repositories_factory_github_teams

Description: (Optional) The repositories_factory_github_teams block supports the following:
name : (Required) The name of the team.
description : (Optional) A description of the team.
permission : (Optional) The permissions of team members regarding the repository. Must be one of pull, triage, push, maintain, admin or the name of an existing custom repository role within the organisation.

Type:

list(object({
    name        = string
    description = optional(string)
    permission  = optional(string, "pull")
  }))

Default:

[
  {
    "description": "This group grant write access to the HCP Terraform repositories repository.",
    "name": "HCPTerraform-repositoriesFactory-Contributors",
    "permission": "push"
  }
]

repositories_factory_tag

Description: (Optional) A map of key value tags for this workspace for the repositories factory.

Type: map(string)

Default: null

repositories_factory_workspace_name

Description: (Optional) Name of the workspace for the repositories factory.

Type: string

Default: "GitHub-RepositoriesFactory"

send_passing_statuses_for_untriggered_speculative_plans

Description: (Optional) Whether or not to send VCS status updates for untriggered speculative plans. This can be useful if large numbers of untriggered workspaces are exhausting request limits for connected version control service providers like GitHub. Defaults to false.

Type: bool

Default: false

session_remember_minutes

Description: (Optional) Session expiration. Defaults to 20160.

Type: number

Default: null

session_timeout_minutes

Description: (Optional) Session timeout after inactivity. Defaults to 20160.

Type: number

Default: null

speculative_plan_management_enabled

Description: (Optional) Whether or not to enable Speculative Plan Management. If true, pending VCS-triggered speculative plans from outdated commits will be cancelled if a newer commit is pushed to the same branch. default to true.

Type: bool

Default: true

teams

Description: (Optional) The teams block supports the following:
name : (Required) Name of the team.
organization_access : (Optional) The organization_access supports the following:
access_secret_teams : (Optional) Allow members access to secret teams up to the level of permissions granted by their team permissions setting.
manage_agent_pools : (Optional) Allow members to create, edit, and delete agent pools within their organization.
manage_membership : (Optional) Allow members to add/remove users from the organization, and to add/remove users from visible teams.
manage_modules : (Optional) Allow members to publish and delete modules in the organization's private registry.
manage_organization_access : (Optional) Allow members to update the organization access settings of teams.
manage_policies : (Optional) Allows members to create, edit, and delete the organization's Sentinel policies.
manage_policy_overrides : (Optional) Allows members to override soft-mandatory policy checks.
manage_projects : (Optional) Allow members to create and administrate all projects within the organization.
manage_providers : (Optional) Allow members to publish and delete providers in the organization's private registry.
manage_run_tasks : (Optional) Allow members to create, edit, and delete the organization's run tasks.
manage_teams : (Optional) Allow members to create, update, and delete teams.
manage_vcs_settings : (Optional) Allows members to manage the organization's VCS Providers and SSH keys.
manage_workspaces : (Optional) Allows members to create and administrate all workspaces within the organization.
read_projects : (Optional) Allow members to view all projects within the organization. Requires read_workspaces to be set to true.
read_workspaces : (Optional) Allow members to view all workspaces in this organization.
sso_team_id : (Optional) Unique Identifier to control team membership via SAML.
token : (Optional) If set to true, a team token will be generated.
token_description : (Optional) The token's description, which must be unique per team. Required if creating multiple tokens for a single team.
token_expired_at : (Optional) The token's expiration date. The expiration date must be a date/time string in RFC3339 format (e.g., '2024-12-31T23:59:59Z'). If no expiration date is supplied, the expiration date will default to null and never expire.
token_force_regenerate : (Optional) If set to true, a new token will be generated even if a token already exists. This will invalidate the existing token!
visibility : (Optional) The visibility of the team (secret or organization).

Type:

list(object({
    name = string
    organization_access = optional(object({
      access_secret_teams        = optional(bool, false)
      manage_agent_pools         = optional(bool, false)
      manage_membership          = optional(bool, false)
      manage_modules             = optional(bool, false)
      manage_organization_access = optional(bool, false)
      manage_policies            = optional(bool, false)
      manage_policy_overrides    = optional(bool, false)
      manage_projects            = optional(bool, false)
      manage_providers           = optional(bool, false)
      manage_run_tasks           = optional(bool, false)
      manage_teams               = optional(bool, false)
      manage_vcs_settings        = optional(bool, false)
      manage_workspaces          = optional(bool, false)
      read_projects              = optional(bool, false)
      read_workspaces            = optional(bool, false)
    }), null)
    sso_team_id            = optional(string)
    token                  = optional(bool, false)
    token_description      = optional(string)
    token_expired_at       = optional(string)
    token_force_regenerate = optional(bool, false)
    visibility             = optional(string, "organization")
  }))

Default: []

workspaces_factory_agent_pool_id

Description: (Optional) The ID of an agent pool to assign to the workspace for the workspaces factory. Requires execution_mode to be set to agent. This value must not be provided if execution_mode is set to any other value.

Type: string

Default: null

workspaces_factory_description

Description: (Optional) A description for the workspace for the workspaces factory.

Type: string

Default: "Code to provision and manage HCP Terraform workspaces using Terraform code (IaC)."

workspaces_factory_execution_mode

Description: (Optional) Which execution mode to use for the workspaces factory. Using Terraform Cloud, valid values are remote, local or agent. When set to local, the workspace will be used for state storage only. Important: If you omit this attribute, the resource configures the workspace to use your organization's default execution mode (which in turn defaults to remote), removing any explicit value that might have previously been set for the workspace.

Type: string

Default: null

workspaces_factory_github_teams

Description: (Optional) The workspaces_factory_github_teams block supports the following:
name : (Required) The name of the team.
description : (Optional) A description of the team.
permission : (Optional) The permissions of team members regarding the repository. Must be one of pull, triage, push, maintain, admin or the name of an existing custom repository role within the organisation.

Type:

list(object({
    name        = string
    description = optional(string)
    permission  = optional(string, "pull")
  }))

Default:

[
  {
    "description": "This group grant write access to the HCP Terraform workspaces repository.",
    "name": "HCPTerraform-workspacesFactory-Contributors",
    "permission": "push"
  }
]

workspaces_factory_tag

Description: (Optional) A map of key value tags for this workspace for the workspaces factory.

Type: map(string)

Default: null

workspaces_factory_workspace_name

Description: (Optional) Name of the workspace for the workspaces factory.

Type: string

Default: "HCPTerraform-WorkspacesFactory"

Resources

The following resources are used by this module:

• github_actions_secret.modules_factory (resource)
• github_actions_secret.policies_factory (resource)
• github_actions_secret.projects_factory (resource)
• github_actions_secret.repositories_factory (resource)
• github_actions_secret.workspaces_factory (resource)
• tfe_organization.this (resource)
• tfe_organization_default_settings.this (resource)
• tfe_project.hcp_foundation (resource)
• tfe_variable.modules_factory (resource)
• tfe_variable.modules_factory_organization_name (resource)
• tfe_variable.policies_factory (resource)
• tfe_variable.projects_factory (resource)
• tfe_variable.projects_factory_organization_name (resource)
• tfe_variable.repositories_factory (resource)
• tfe_variable.repositories_factory_organization_name (resource)
• tfe_variable.workspaces_factory (resource)
• tfe_variable.workspaces_factory_organization_name (resource)

Outputs

The following outputs are exported:

teams

Description: List of Teams created