Home
Apps

Repository: terraform-govuk-tfe-workspacer

Terraform module to create and configure Workspace(s) in Terraform Cloud/Enterprise.

GitHub: terraform-govuk-tfe-workspacer
Ownership: #govuk-platform-engineering owns the repo. #govuk-platform-support receives automated alerts for this repo.
Category: Utilities
Links: Sentry (error tracking)

README

Terraform module to create, configure, and manage Workspaces in HCP Terraform or Terraform Enterprise.

Usage

module "workspacer" {
  source  = "alexbasista/workspacer/tfe"
  

  organization   = "my-hcptf-or-tfe-org-name"
  workspace_name = "my-new-ws"
  workspace_desc = "Description of my new Workspace."
  workspace_tags = ["tag1", "tag2", "tagz"]
  project_name   = "Default Project"

  tfvars = {
    teststring = "iamstring"
    testlist   = ["1", "2", "3"]
    testmap    = { "a" = "1", "b" = "2", "c" = "3" }
  }
}

📝 Note: Setting a TFE_TOKEN environment variable is the recommended approach for the TFE provider authentication.

See the examples directory for more detailed example scenarios, and see the following section for optional configurations/features.

Configuration Options

Projects

To place the Workspace into an existing Project, set the input variable project_name.

project_name = "my-project"

With VCS

The optional vcs_repo input variable expects a map of key/value pairs with up to six attributes.

Using an OAuth Token

  vcs_repo = {
    identifier     = "<VCS organization>/<VCS repository name>"
    branch         = "main"
    oauth_token_id = "ot-abcdefg123456789"
  }

Using a GitHub App Installation ID

  vcs_repo = {
    identifier                 = "<VCS organization>/<VCS repository name>"
    branch                     = "main"
    github_app_installation_id = "ghain-abcdefg123456789"
  }

Workspace Variables

This module strives to make creating Workspace Variables more streamlined, and closer to the look and feel of using a terraform.tfvars file (key/value pairs) when creating them. There are four different optional input variables available for creating Workspace Variables:

Terraform Variables

tfvars accepts a map of key/value pairs of any type, and tfvars_sensitive is the same except it will also mark the variable(s) as sensitive upon creation.

  tfvars = {
    teststring = "iamstring"
    testlist   = ["1", "2", "3"]
    testmap    = { "a" = "1", "b" = "2", "c" = "3" }
  }

  tfvars_sensitive = {
    secret      = "securestring"
    secret_list = ["sec1", "sec2", "sec3"]
    secret_map  = { "x" = "sec4", "y" = "sec5", "z" = "sec6" }
  }

Environment Variables

envvars accepts a map of strings, and envvars_sensitive is the same except it will also mark the variable(s) as sensitive upon creation.

  envvars = {
    AWS_ACCESS_KEY_ID = "ABCDEFGHIJKLMNOPQRST"
  }

  envvars_sensitive = {
    AWS_SECRET_ACCESS_KEY = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$"
  }

Team Access

To configure RBAC on the Workspace, there are two options:

Built-In Permissions

The team_access input variable accepts a map of strings whereby each key/value pair is the (existing) Team name and built-in permission level.

  team_access = {
    "example-team-1" = "read"
    "example-team-2" = "write"
    "example-team-3" = "admin"
  }

Custom Permissions

The custom_team_access input variable accepts a map of objects whereby each object represents a set of custom team permission levels. The object key is the (existing) Team name. The way the TFE provider and API currently work, all five of the object attributes must be specified together when using.

  custom_team_access = {
    "example-team-1" = {
      runs              = "read"
      variables         = "read"
      state_versions    = "read"
      sentinel_mocks    = "none"
      workspace_locking = false
      run_tasks         = false
    }
    "example-team-2" = {
      runs              = "plan"
      variables         = "write"
      state_versions    = "read-outputs"
      sentinel_mocks    = "read"
      workspace_locking = true
      run_tasks         = true
    }
  }

Notifications

To create Notifications, the notifications input variable accepts a list of objects, whereby each object is a Notification configuration.

  notifications = [
    {
      name             = "test-notification-generic"
      destination_type = "generic"
      url              = "http://example.com/receive-notifications-api"
      token            = "abcdefg123456789"
      triggers         = ["run:needs_attention"]
      enabled          = true
    },
    {
      name             = "test-notification-email"
      destination_type = "email"
      email_user_ids   = ["abasista"]
      triggers         = ["run:completed", "run:errored"]
      enabled          = true
    },
    {
      name             = "test-notification-slack"
      destination_type = "slack"
      url              = "https://hooks.slack.com/example"
      triggers         = ["run:completed", "run:errored"]
      enabled          = true
    }
  ]

Run Triggers

To add Run Triggers, the run_trigger_source_workspaces input variable accepts a list of (existing) Workspace names.

  run_trigger_source_workspaces = [
    "example-src-workspace-1",
    "example-src-workspace-2"
  ]

Variable Sets

To add the Workspace into one or more already existing Variable Sets, the input variable variable_set_names accepts a list of Variable Set names.

  variable_set_names = [
    "example-varset-1",
    "example-varset-2"
  ]

Policy Sets

To add the Workspace into one or more already existing Policy Sets, the input variable policy_set_names accepts a list of Policy Set names.

  policy_set_names = [
    "example-sentinel-global",
    "example-sentinel-prod"
  ]

SSH Key ID

To configure an SSH key on your Workspace, set the SSH key ID via the input ssh_key_id. This value should NOT be the name of the SSH key as it appears in the HCP Terraform or TFE UI. If you do not have the ID of your SSH key, you can extract it using the command below. Note: This key is only used when a workspace needs to access a private git repository to pull in a module from a git-based module URL or git submodule.

$ curl  --header "Authorization: Bearer $TFE_TOKEN \
               https://app.terraform.io/api/v2/organizations/myorg/ssh-keys 

{"data":[{"id":"sshkey-abcdefgh12345678","type":"ssh-keys","attributes":{"name":"my-github-ssh-key"},"links":{"self":"/api/v2/ssh-keys/sshkey-abcdefgh12345678"}}]}⏎

Caveats/Limitations

Due to some current provider-interfacing/API challenges with Workspace Variables, any non-string Workspace Variable value (where the hcl attribute would equal true) will be JSON-encoded and subsequently any : characters will be replaced with =. Therefore, non-string Workspace Variable values that contain a colon character are not currently supported.

<!– raw HTML omitted –>

Requirements

Name	Version
<!– raw HTML omitted –><!– raw HTML omitted –> terraform	>= 1.9
<!– raw HTML omitted –><!– raw HTML omitted –> tfe	~> 0.62

Providers

Name	Version
<!– raw HTML omitted –><!– raw HTML omitted –> tfe	~> 0.62

Resources

Name	Type
tfe_notification_configuration.nc	resource
tfe_run_trigger.rt	resource
tfe_team_access.custom	resource
tfe_team_access.managed	resource
tfe_variable.envvars	resource
tfe_variable.envvars_ignore_changes	resource
tfe_variable.envvars_sensitive	resource
tfe_variable.tfvars	resource
tfe_variable.tfvars_ignore_changes	resource
tfe_variable.tfvars_sensitive	resource
tfe_workspace.ws	resource
tfe_workspace_policy_set.ps	resource
tfe_workspace_settings.ws	resource
tfe_workspace_variable_set.vs	resource
tfe_policy_set.ps	data source
tfe_project.ws	data source
tfe_team.custom	data source
tfe_team.managed	data source
tfe_variable_set.vs	data source
tfe_workspace_ids.run_triggers	data source

Inputs

Name	Description	Type	Default	Required
<!– raw HTML omitted –><!– raw HTML omitted –> organization	Name of Organization to create Workspace in.	`string`	n/a	yes
<!– raw HTML omitted –><!– raw HTML omitted –> workspace_name	Name of Workspace to create.	`string`	n/a	yes
<!– raw HTML omitted –><!– raw HTML omitted –> agent_pool_id	ID of existing Agent Pool to assign to Workspace. Only valid when `execution_mode` is set to `agent`.	`string`	`null`	no
<!– raw HTML omitted –><!– raw HTML omitted –> allow_destroy_plan	Boolean setting to allow destroy plans on Workspace.	`bool`	`true`	no
<!– raw HTML omitted –><!– raw HTML omitted –> assessments_enabled	Boolean to enable Health Assessments such as Drift Detection on Workspace.	`bool`	`false`	no
<!– raw HTML omitted –><!– raw HTML omitted –> auto_apply	Boolean to automatically run a Terraform apply after a successful Terraform plan.	`bool`	`false`	no
<!– raw HTML omitted –><!– raw HTML omitted –> custom_team_access	Map of existing Team(s) and custom permissions to grant on Workspace. If used, all keys in the object must be specified.	<!– raw HTML omitted –>map(<!– raw HTML omitted –> object(<!– raw HTML omitted –> {<!– raw HTML omitted –> runs = string<!– raw HTML omitted –> variables = string<!– raw HTML omitted –> state_versions = string<!– raw HTML omitted –> sentinel_mocks = string<!– raw HTML omitted –> workspace_locking = bool<!– raw HTML omitted –> run_tasks = bool<!– raw HTML omitted –> }<!– raw HTML omitted –> )<!– raw HTML omitted –> )<!– raw HTML omitted –>	`{}`	no
<!– raw HTML omitted –><!– raw HTML omitted –> envvars	Map of Environment variables to add to Workspace.	`map(string)`	`{}`	no
<!– raw HTML omitted –><!– raw HTML omitted –> envvars_ignore_changes	Map of sensitive Environment variables to add to Workspace whereby changes made outside of Terraform will be ignored.	`map(string)`	`{}`	no
<!– raw HTML omitted –><!– raw HTML omitted –> envvars_sensitive	Map of sensitive Environment variables to add to Workspace.	`map(string)`	`{}`	no
<!– raw HTML omitted –><!– raw HTML omitted –> execution_mode	Execution mode of Workspace. Valid values are `remote`, `local`, or `agent`.	`string`	`null`	no
<!– raw HTML omitted –><!– raw HTML omitted –> file_triggers_enabled	Boolean to filter Runs triggered via webhook (VCS push) based on `working_directory` and `trigger_prefixes`.	`bool`	`true`	no
<!– raw HTML omitted –><!– raw HTML omitted –> force_delete	Boolean to allow deletion of the Workspace if there is a Terraform state that contains resources.	`bool`	`null`	no
<!– raw HTML omitted –><!– raw HTML omitted –> global_remote_state	Boolean to allow all Workspaces within the Organization to remotely access the State of this Workspace.	`bool`	`false`	no
<!– raw HTML omitted –><!– raw HTML omitted –> notifications	List of Notification objects to configure on Workspace.	<!– raw HTML omitted –>list(<!– raw HTML omitted –> object(<!– raw HTML omitted –> {<!– raw HTML omitted –> name = string<!– raw HTML omitted –> destination_type = string<!– raw HTML omitted –> url = optional(string)<!– raw HTML omitted –> token = optional(string)<!– raw HTML omitted –> email_addresses = optional(list(string))<!– raw HTML omitted –> email_user_ids = optional(list(string))<!– raw HTML omitted –> triggers = list(string)<!– raw HTML omitted –> enabled = bool<!– raw HTML omitted –> }<!– raw HTML omitted –> )<!– raw HTML omitted –> )<!– raw HTML omitted –>	`[]`	no
<!– raw HTML omitted –><!– raw HTML omitted –> policy_set_names	List of names of existing Policy Sets to add this Workspace into.	`list(string)`	`[]`	no
<!– raw HTML omitted –><!– raw HTML omitted –> project_name	Name of existing Project to create Workspace in.	`string`	`null`	no
<!– raw HTML omitted –><!– raw HTML omitted –> queue_all_runs	Boolean setting for Workspace to automatically queue all Runs after creation.	`bool`	`true`	no
<!– raw HTML omitted –><!– raw HTML omitted –> remote_state_consumer_ids	List of existing Workspace IDs allowed to remotely access the State of Workspace.	`list(string)`	`null`	no
<!– raw HTML omitted –><!– raw HTML omitted –> run_trigger_source_workspaces	List of existing Workspace names that will trigger runs on Workspace.	`list(string)`	`[]`	no
<!– raw HTML omitted –><!– raw HTML omitted –> speculative_enabled	Boolean to allow Speculative Plans on Workspace.	`bool`	`true`	no
<!– raw HTML omitted –><!– raw HTML omitted –> ssh_key_id	SSH private key the Workspace will use for downloading Terraform modules from Git-based module sources. Key must exist in Organization first.	`string`	`null`	no
<!– raw HTML omitted –><!– raw HTML omitted –> structured_run_output_enabled	Boolean to enable the advanced Run UI. Set to `false` for the traditional console-based Run output.	`bool`	`true`	no
<!– raw HTML omitted –><!– raw HTML omitted –> tags_regex	A regular expression used to trigger a Run in Workspace for matching Git tags. This option conflicts with `trigger_patterns` and `trigger_prefixes`. Should only set this value if the former is not being used.	`string`	`null`	no
<!– raw HTML omitted –><!– raw HTML omitted –> team_access	Map of existing Team(s) and built-in permissions to grant on Workspace.	`map(string)`	`{}`	no
<!– raw HTML omitted –><!– raw HTML omitted –> terraform_version	Version of Terraform to use for this Workspace.	`string`	`null`	no
<!– raw HTML omitted –><!– raw HTML omitted –> tfvars	Map of Terraform variables to add to Workspace.	`any`	`{}`	no
<!– raw HTML omitted –><!– raw HTML omitted –> tfvars_ignore_changes	Map of Terraform variables to add to Workspace whereby changes made outside of Terraform will be ignored.	`any`	`{}`	no
<!– raw HTML omitted –><!– raw HTML omitted –> tfvars_sensitive	Map of sensitive Terraform variables to add to Workspace.	`any`	`{}`	no
<!– raw HTML omitted –><!– raw HTML omitted –> trigger_patterns	List of glob patterns that describe the files monitored for changes to trigger Runs in Workspace. Mutually exclusive with `trigger_prefixes`. Only available with TFC.	`list(string)`	`null`	no
<!– raw HTML omitted –><!– raw HTML omitted –> trigger_prefixes	List of paths relative to the root of the VCS repo to filter on when `file_triggers_enabled` is `true`.	`list(string)`	`null`	no
<!– raw HTML omitted –><!– raw HTML omitted –> variable_set_names	List of names of existing Variable Sets to add this Workspace into.	`list(string)`	`[]`	no
<!– raw HTML omitted –><!– raw HTML omitted –> vcs_repo	Object containing settings to connect Workspace to a VCS repository.	<!– raw HTML omitted –>object({<!– raw HTML omitted –> identifier = string<!– raw HTML omitted –> branch = optional(string, null)<!– raw HTML omitted –> oauth_token_id = optional(string, null)<!– raw HTML omitted –> github_app_installation_id = optional(string, null)<!– raw HTML omitted –> ingress_submodules = optional(bool, false)<!– raw HTML omitted –> tags_regex = optional(string, null)<!– raw HTML omitted –> })<!– raw HTML omitted –>	`null`	no
<!– raw HTML omitted –><!– raw HTML omitted –> working_directory	The relative path that Terraform will execute within. Defaults to the root of the repo.	`string`	`null`	no
<!– raw HTML omitted –><!– raw HTML omitted –> workspace_desc	Description of Workspace.	`string`	`"Created by 'workspacer' Terraform module."`	no
<!– raw HTML omitted –><!– raw HTML omitted –> workspace_tags	List of tag names to apply to Workspace. Tags must only contain letters, numbers, or colons.	`list(string)`	`[]`	no

Outputs

Name	Description
<!– raw HTML omitted –><!– raw HTML omitted –> workspace_id	ID of Workspace.

<!– raw HTML omitted –>