Access control

Access control in Terrateam provides a powerful and flexible way to manage who can perform various operations on your Terraform resources. By defining policies based on user roles, GitHub teams, and repository collaborators, you can ensure that only authorized individuals can trigger potentially impactful actions like applying changes to your infrastructure.

Configuration

Access control is configured in the .terrateam/config.yml file under the access_control key. Here’s an example configuration:

access_control:
  enabled: true
  apply_require_all_dirspace_access: true
  plan_require_all_dirspace_access: false
  terrateam_config_update: ['*']
  unlock: ['*']
  policies:
    - tag_query: ''
      apply: ['team:sre']
      apply_autoapprove: []
      apply_force: []
      apply_with_superapproval: []
      plan: ['*']
      superapproval: []

Let’s break down the various options:

enabled: Set to true to enable access control. Default is true.
apply_require_all_dirspace_access: If true, the user must have permission to all targeted dirspace to trigger an apply operation. Default is true.
plan_require_all_dirspace_access: If true, the user must have permission to all targeted dirspaces to trigger a plan operation. Default is false.
terrateam_config_update: Ruleset for which users can trigger a Terrateam operation on a pull request with a Terrateam configuration file change. Default is ['*'].
unlock: Ruleset for which users can trigger an unlock operation on a pull request. Default is ['*'].
policies: A list of policy objects that define access rules for various operations.

Policies

Each policy object in the policies list consists of a tag_query and rulesets for different operations. The tag_query is used to match tags associated with dirspaces. An empty tag_query matches all dirspaces.

The available rulesets are:

apply: Users who can trigger an apply, including autoapply.
apply_autoapprove: Users who can trigger an apply auto-approve operations.
apply_force: Users who can trigger an apply-force operation.
apply_with_superapproval: Allows a user to trigger an apply operation if a user matching the superapproval list has approved the pull request.
plan: Users who can trigger a plan operation, including autoplan.
superapproval: Define a list of users whose approvals are considered super approvals.

Rule syntax

The rulesets use a simple syntax to define who has access:

*: Matches anyone.
user:<username>: Matches a specific user, e.g., user:alice.
team:<teamname>: Matches any user who is a member of the specified GitHub team, e.g., team:sre.
role:<rolename>: Matches users with the specified repository role. Valid roles are read, triage, write, maintain, and admin.

Examples

Here are a few examples of common access control configurations:

Allow only SRE team to apply changes

access_control:
  policies:
    - tag_query: ''
      plan: ['*']
      apply: ['team:sre']

Require super approval for production changes

access_control:
  policies:
    - tag_query: 'dir:production'
      apply: []
      apply_with_superapproval: ['*']
      superapproval: ['team:sre']
    - tag_query: ''
      plan: ['*']
      apply: ['*']

Allow developers to force apply in development environment

access_control:
  policies:
    - tag_query: 'dir:development'
      apply_force: ['team:developers']