terraform-aws-mcaf-workspace

This module uses the terraform-tfe-mcaf-workspace module to create a Terraform Cloud workspace and extends the features to manage AWS resources. This is done by creating either a IAM user or role and adding those credentials to the workspace.

Usage

Authentication

The module supports three authentication methods for Terraform Cloud to access AWS, configured via the auth_method variable:

Method	Description
iam_role_oidc (default)	Creates an IAM role that Terraform Cloud assumes using OIDC workload identity (recommended)
iam_user	Creates an IAM user with static credentials (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY) stored in Terraform Cloud
iam_role	Creates an IAM role that Terraform Cloud assumes using static credentials and an external ID

Why OIDC is Recommended

• No long-lived credentials are stored or managed
• Native integration with Terraform Cloud workload identity
• Automatic temporary credential issuance for each run

Disabling Authentication

Authentication can be disabled by setting enable_authentication = false. This is useful when authentication is managed at the Terraform Cloud project level or AWS credentials are provided externally via variable sets.

Team access

This module supports assigning an existing team access to the created workspace.

To do this, pass a map to var.team_access using the team name as the key and either access or permissions to assign a team access to the workspace.

Example using a pre-existing role (see this link for allowed values):

team_access = {
  "MyTeamName" = {
    access = "write"
  }
}

Example using a custom role (see this link for a list of keys and their allowed values):

team_access = {
  "MyTeamName" = {
    permissions = {
      run_tasks         = false
      runs              = "apply"
      sentinel_mocks    = "read"
      state_versions    = "read-outputs"
      variables         = "write"
      workspace_locking = true
    }
  }
}

The above custom role is similar to the "write" pre-existing role, but blocks access to the workspace state (which is considered sensitive).

Requirements

Name	Version
terraform	>= 1.9.0
aws	>= 4.0.0
random	>= 3.0.0
tfe	>= 0.67.1

Providers

Name	Version
tfe	>= 0.67.1

Modules

Name	Source	Version
auth	./modules/auth	n/a
tfe-workspace	schubergphilis/mcaf-workspace/tfe	~> 3.0.0

Resources

Name	Type
tfe_team_access.default	resource
tfe_project.default	data source
tfe_team.default	data source

Inputs

Name	Description	Type	Default	Required
name	A name for the Terraform workspace	string	n/a	yes
agent_pool_id	Agent pool ID, requires "execution_mode" to be set to agent	string	null	no
agent_role_arns	IAM role ARNs used by Terraform Cloud Agent to assume role in the created account	list(string)	null	no
allow_destroy_plan	Whether destroy plans can be queued on the workspace	bool	true	no
assessments_enabled	Whether to regularly run health assessments such as drift detection on the workspace	bool	true	no
auth_method	Configures how the workspace authenticates with the AWS account (can be iam_user, iam_role, or iam_role_oidc)	string	"iam_role_oidc"	no
auto_apply	Whether to automatically apply changes when a Terraform plan is successful	bool	false	no
auto_apply_run_trigger	Whether to automatically apply changes for runs that were created by run triggers from another workspace	bool	false	no
auto_destroy_activity_duration	Duration string (e.g. "7d") after last activity when an auto-destroy run should be queued for this workspace	string	null	no
auto_destroy_at	Absolute time (RFC3339, e.g. "2025-12-31T23:59:00Z") at which this workspace's resources should be automatically destroyed	string	null	no
branch	The git branch to trigger the TFE workspace for	string	"main"	no
clear_text_env_variables	An optional map with clear text environment variables	map(string)	{}	no
clear_text_hcl_variables	An optional map with clear text HCL Terraform variables	map(string)	{}	no
clear_text_terraform_variables	An optional map with clear text Terraform variables	map(string)	{}	no
description	A description for the workspace	string	null	no
enable_authentication	Whether to create and configure AWS IAM credentials (user or role) for the workspace to authenticate with AWS using the specified auth_method	bool	true	no
execution_mode	Which execution mode to use	string	"remote"	no
file_triggers_enabled	Whether to filter runs based on the changed files in a VCS push	bool	true	no
force_delete	If true, the workspace will be force deleted even when resources are still under management	bool	false	no
github_app_installation_id	The GitHub App installation ID to use	string	null	no
global_remote_state	Allow all workspaces in the organization to read the state of this workspace	bool	null	no
notification_configuration	Notification configuration, using name as key and config as value	map(object({ destination_type = string enabled = optional(bool, true) url = string triggers = optional(list(string), [ "run:created", "run:planning", "run:needs_attention", "run:applying", "run:completed", "run:errored", ]) }))	{}	no
oauth_token_id	The OAuth token ID of the VCS provider	string	null	no
oidc_settings	OIDC settings to use if "auth_method" is set to "iam_role_oidc"	object({ audience = optional(string, "aws.workload.identity") # Apply OIDC trust to all workspaces in the project instead of just this workspace. # WARNING: Only enable this setting when the project relates to a single AWS Account to avoid unintended access. project_scope = optional(bool, false) provider_arn = string site_address = optional(string, "app.terraform.io") })	null	no
path	Path in which to create the IAM role or user	string	null	no
permissions_boundary_arn	ARN of the policy that is used to set the permissions boundary for the IAM role or IAM user	string	null	no
policy	The policy to attach to the pipeline role or user	string	null	no
policy_arns	A set of policy ARNs to attach to the pipeline user	set(string)	[]	no
project_name	Name of the TFE project where the workspace should be created	string	null	no
queue_all_runs	When set to false no initial run is queued and all runs triggered by a webhook will not be queued, necessary if you need to set variable sets after creation.	bool	true	no
region	The default region of the account	string	null	no
remote_state_consumer_ids	A set of workspace IDs set as explicit remote state consumers for this workspace	set(string)	null	no
repository_identifier	The repository identifier to connect the workspace to	string	null	no
role_name	The IAM role name for a new pipeline role	string	null	no
sensitive_env_variables	An optional map with sensitive environment variables	map(string)	{}	no
sensitive_hcl_variables	An optional map with sensitive HCL Terraform variables	map(object({ sensitive = string }))	{}	no
sensitive_terraform_variables	An optional map with sensitive Terraform variables	map(string)	{}	no
speculative_enabled	Enables or disables speculative plans on PR/MR, enabled by default	bool	true	no
ssh_key_id	The SSH key ID to assign to the workspace	string	null	no
tags	A mapping of tags to assign to resource	map(string)	null	no
team_access	Map of team names and either type of fixed access or custom permissions to assign	map(object({ access = optional(string, null), permissions = optional(object({ run_tasks = bool runs = string sentinel_mocks = string state_versions = string variables = string workspace_locking = bool }), null) }))	{}	no
terraform_organization	The Terraform Enterprise organization to create the workspace in	string	null	no
terraform_version	The version of Terraform to use for this workspace	string	"latest"	no
trigger_patterns	List of glob patterns that describe the files Terraform Cloud monitors for changes. Trigger patterns are always appended to the root directory of the repository. Mutually exclusive with trigger-prefixes	list(string)	[ "modules/**/*" ]	no
trigger_patterns_working_directory_recursive	If true, include all nested files in the working directory; if false, match only its root.	bool	false	no
username	The username for a new pipeline user	string	null	no
variable_set_ids	Map of variable set ids to attach to the workspace	map(string)	{}	no
variable_set_names	Set of variable set names to attach to the workspace	set(string)	[]	no
working_directory	A relative path that Terraform will execute within	string	"terraform"	no
workspace_tags	A map of key value tags for this workspace	map(string)	null	no

Outputs

Name	Description
arn	The workspace IAM user ARN
iam_role_arn	ARN of the IAM role (if auth_method is iam_role)
iam_role_oidc_arn	ARN of the IAM role for OIDC (if auth_method is iam_role_oidc)
iam_user_arn	ARN of the IAM user (if auth_method is iam_user)
workspace_id	The Terraform Cloud workspace ID
workspace_name	The Terraform Cloud workspace name