Workspacer

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

Usage

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

  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 = [
    "base-networking-ws",
    "base-iam-ws"
  ]

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 = [
    "my-aws-creds",
    "tfe-api-token"
  ]

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

ssh_key_id parameter expects id of ssh key. Not name in terraform cloud console. But Terraform cloud console display only the ssh key name. This key is used to download modules from private terraform repo. The following command can be used to get ssh key id.

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

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

---

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.

---

Requirements

Name	Version
terraform	>= 1.9
tfe	~> 0.58

Providers

Name	Version
tfe	~> 0.58

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
organization	Name of Organization to create Workspace in.	string	n/a	yes
workspace_name	Name of Workspace to create.	string	n/a	yes
agent_pool_id	ID of existing Agent Pool to assign to Workspace. Only valid when execution_mode is set to agent.	string	null	no
allow_destroy_plan	Boolean setting to allow destroy plans on Workspace.	bool	true	no
assessments_enabled	Boolean to enable Health Assessments such as Drift Detection on Workspace.	bool	false	no
auto_apply	Boolean to automatically run a Terraform apply after a successful Terraform plan.	bool	false	no
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.	map( object( { runs = string variables = string state_versions = string sentinel_mocks = string workspace_locking = bool run_tasks = bool } ) )	{}	no
envvars	Map of Environment variables to add to Workspace.	map(string)	{}	no
envvars_ignore_changes	Map of sensitive Environment variables to add to Workspace whereby changes made outside of Terraform will be ignored.	map(string)	{}	no
envvars_sensitive	Map of sensitive Environment variables to add to Workspace.	map(string)	{}	no
execution_mode	Execution mode of Workspace. Valid values are remote, local, or agent.	string	null	no
file_triggers_enabled	Boolean to filter Runs triggered via webhook (VCS push) based on working_directory and trigger_prefixes.	bool	true	no
force_delete	Boolean to allow deletion of the Workspace if there is a Terraform state that contains resources.	bool	null	no
global_remote_state	Boolean to allow all Workspaces within the Organization to remotely access the State of this Workspace.	bool	false	no
notifications	List of Notification objects to configure on Workspace.	list( object( { name = string destination_type = string url = optional(string) token = optional(string) email_addresses = optional(list(string)) email_user_ids = optional(list(string)) triggers = list(string) enabled = bool } ) )	[]	no
policy_set_names	List of names of existing Policy Sets to add this Workspace into.	list(string)	[]	no
project_name	Name of existing Project to create Workspace in.	string	null	no
queue_all_runs	Boolean setting for Workspace to automatically queue all Runs after creation.	bool	true	no
remote_state_consumer_ids	List of existing Workspace IDs allowed to remotely access the State of Workspace.	list(string)	null	no
run_trigger_source_workspaces	List of existing Workspace names that will trigger runs on Workspace.	list(string)	[]	no
speculative_enabled	Boolean to allow Speculative Plans on Workspace.	bool	true	no
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
structured_run_output_enabled	Boolean to enable the advanced Run UI. Set to false for the traditional console-based Run output.	bool	true	no
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
team_access	Map of existing Team(s) and built-in permissions to grant on Workspace.	map(string)	{}	no
terraform_version	Version of Terraform to use for this Workspace.	string	null	no
tfvars	Map of Terraform variables to add to Workspace.	any	{}	no
tfvars_ignore_changes	Map of Terraform variables to add to Workspace whereby changes made outside of Terraform will be ignored.	any	{}	no
tfvars_sensitive	Map of sensitive Terraform variables to add to Workspace.	any	{}	no
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
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
variable_set_names	List of names of existing Variable Sets to add this Workspace into.	list(string)	[]	no
vcs_repo	Object containing settings to connect Workspace to a VCS repository.	object({ identifier = string branch = optional(string, null) oauth_token_id = optional(string, null) github_app_installation_id = optional(string, null) ingress_submodules = optional(bool, false) tags_regex = optional(string, null) })	null	no
working_directory	The relative path that Terraform will execute within. Defaults to the root of the repo.	string	null	no
workspace_desc	Description of Workspace.	string	"Created by 'workspacer' Terraform module."	no
workspace_tags	List of tag names to apply to Workspace. Tags must only contain letters, numbers, or colons.	list(string)	[]	no

Outputs

Name	Description
workspace_id	ID of Workspace.