Skip to content

Google Cloud Custom Roles Module#

This module provides a flexible and secure way to create and manage custom IAM roles at both the project and organization levels within Google Cloud Platform. It allows for the composition of permissions from predefined roles and explicit permission lists, while also providing robust mechanisms for excluding unwanted permissions.

Compatibility#

This module is compatible with Terraform version ~> 1.0 and has been tested with the following provider versions:

  • Google Provider: >= 6.28.0, < 7.0.0
  • Google Beta Provider: >= 6.28.0, < 7.0.0

Limitations#

  • Additive IAM Bindings: The module uses google_*_iam_member resources. These create individual, non-authoritative bindings, which is safe for environments where multiple teams or processes manage IAM. It does not provide exclusive control over who has the role. If you need authoritative control, you would need to use a google_*_iam_binding resource, which is not implemented in this module.
  • Single Role per Invocation: Each instance of this module is designed to create and manage a single custom role. To create multiple roles, invoke the module multiple times with different parameters.

Usage#

This module enables you to create custom IAM roles with the following key features:

  • Flexible Permission Composition: Combine one or more predefined GCP roles with a list of additional permissions to create a precise set of effective permissions.
  • Advanced Exclusion Logic: Exclude specific permissions from the composed set using either direct string matches or powerful regex patterns (e.g., iam.serviceAccounts.*).
  • Project & Organization Scope: Create and manage custom roles at either the project or organization level by setting the target_level variable.
  • IAM Member Bindings: Directly assign the newly created custom role to a list of members (users, groups, or service accounts).

Custom Role at Organization Level#

module "custom_roles" {
  source = "github.com/myops-co/gcp-terraform-modules//modules/terraform-google-custom-roles?ref=vX.Y.Z"

  target_level         = "org"
  target_id            = "123456789012"
  role_id              = "CustomRoleId432432"
  title                = "Custom Role That Has Unique Title"
  description          = "Custom Role Description"
  base_roles           = ["roles/iam.serviceAccountKeyAdmin"]
  permissions          = ["storage.objects.list", "storage.objects.get"]
  excluded_permissions = ["iam.serviceAccountKeys.delete"]
  members              = ["group:gcp-admin@example.com", "user:admin@example.com"]
}

Custom Role at Project Level#

module "custom_roles" {
  source = "github.com/myops-co/gcp-terraform-modules//modules/terraform-google-custom-roles?ref=vX.Y.Z"

  target_level         = "project"
  target_id            = "my-project-id"
  role_id              = "custom_role_id"
  title                = "Custom Role Unique Title"
  description          = "Custom Role Description"
  base_roles           = ["roles/iam.serviceAccountAdmin"]
  permissions          = ["iam.roles.list", "iam.roles.create", "iam.roles.delete"]
  excluded_permissions = ["iam.serviceAccounts.setIamPolicy"]
  members              = ["serviceAccount:member01@my-project-id.iam.gserviceaccount.com"]
}

Custom Role with Regex Permission Exclusion#

module "custom_roles" {
  source = "github.com/myops-co/gcp-terraform-modules//modules/terraform-google-custom-roles?ref=vX.Y.Z"

  target_level         = "org"
  target_id            = "123456789012"
  role_id              = "custom_role_id"
  title                = "Custom Role Unique Title"
  description          = "Custom Role Description"
  base_roles           = ["roles/compute.networkAdmin"]
  permissions          = []
  excluded_permissions = ["networkservices.gateways.*"]  # Excludes all networkservices.gateways permissions
  members              = ["user:user01@example.com", "group:group01@example.com"]
}

Software#

This module requires the following software dependencies:

Service Account#

The service account used to run this module must have the following IAM roles:

  • roles/iam.roleAdmin - To create and manage custom IAM roles
  • roles/resourcemanager.organizationAdmin - To manage organization-level roles (when target_level = "org")
  • roles/resourcemanager.projectIamAdmin - To manage project-level roles (when target_level = "project")

APIs#

The following GCP APIs must be enabled in the target project:

  • Cloud Resource Manager API (cloudresourcemanager.googleapis.com)
  • Identity and Access Management (IAM) API (iam.googleapis.com)

License#

This module is covered by a commercial license. Please see LICENSE for details.

Support#

This module is developed and maintained by MyOps Limited. For any support inquiries, please contact us at info@myops.co.il.

Requirements#

Name Version
terraform ~> 1
google >= 6.28.0, < 7.0.0
google-beta >= 6.28.0, < 7.0.0

Providers#

Name Version
google >= 6.28.0, < 7.0.0

Modules#

No modules.

Resources#

Name Type
google_organization_iam_custom_role.org_custom_role resource
google_organization_iam_member.custom_role_member resource
google_project_iam_custom_role.project_custom_role resource
google_project_iam_member.custom_role_member resource
google_iam_role.role_permissions data source
google_iam_testable_permissions.unsupported_permissions data source

Inputs#

Name Description Type Default Required
base_roles List of base predefined roles to use to compose custom role. Either base_roles or permissions must be set with some values list(string) [] no
description Description of Custom role. string "" no
excluded_permissions List of permissions to exclude from custom role. list(string) [] no
members List of members to be added to custom role. list(string) [] no
permissions IAM permissions assigned to Custom Role. Either base_roles or permissions must be set with some values list(string) [] no
role_id ID of the Custom Role. string n/a yes
stage The current launch stage of the role. Defaults to GA. string "GA" no
target_id Variable for project or organization ID. string n/a yes
target_level String variable to denote if custom role being created is at project or organization level. string "project" no
title Human-readable title of the Custom Role, defaults to role_id. string "" no

Outputs#

Name Description
custom_role_id ID of the custom role created.
organization_iam_bindings IAM member bindings created at the organization level.
project_iam_bindings IAM member bindings created at the project level.