Skip to content

terraform-google-modules/terraform-google-group

Repository files navigation

terraform-google-group

This module manages Cloud Identity Groups and Memberships using the Cloud Identity Group API.

Usage

Basic usage of this module is as follows:

# Required if using User ADCs (Application Default Credentials) for Cloud Identity API.
provider "google-beta" {
  user_project_override = true
  billing_project       = "<PROJECT_ID>"
}

module "group" {
  source  = "terraform-google-modules/group/google"
  version = "~> 0.7"

  id           = "[email protected]"
  display_name = "example-group"
  description  = "Example group"
  domain       = "example.com"
  owners       = ["[email protected]"]
  managers     = ["[email protected]"]
  members      = ["[email protected]"]
}

Functional examples are included in the examples directory.

Inputs

Name Description Type Default Required
customer_id Customer ID of the organization to create the group in. One of domain or customer_id must be specified string "" no
description Description of the group string "" no
display_name Display name of the group string "" no
domain Domain of the organization to create the group in. One of domain or customer_id must be specified string "" no
id ID of the group. For Google-managed entities, the ID must be the email address the group string n/a yes
initial_group_config The initial configuration options for creating a Group. See the API reference for possible values. Possible values are INITIAL_GROUP_CONFIG_UNSPECIFIED, WITH_INITIAL_OWNER, and EMPTY. string "EMPTY" no
managers Managers of the group. Each entry is the ID of an entity. For Google-managed entities, the ID must be the email address of an existing group, user or service account list(string) [] no
members Members of the group. Each entry is the ID of an entity. For Google-managed entities, the ID must be the email address of an existing group, user or service account list(string) [] no
owners Owners of the group. Each entry is the ID of an entity. For Google-managed entities, the ID must be the email address of an existing group, user or service account list(string) [] no
types The type of the group to be created. More info: https://cloud.google.com/identity/docs/groups#group_properties list(string)
[
"default"
]
no

Outputs

Name Description
id ID of the group. For Google-managed entities, the ID is the email address the group
name Name of the group with the domain removed. For Google-managed entities, the ID is the email address the group
resource_name Resource name of the group in the format: groups/{group_id}, where group_id is the unique ID assigned to the group.

Limitations

The provider is still under development, the following are known issues or limitations:

  • Updating a google_cloud_identity_group_membership to remove a role fails with an error (link).

  • Updating a google_cloud_identity_group_membership to change the role of a member fails with the following error due to Terraform trying to create the new role assignment before/at the same time as the old one is removed. Rerunning the same deployment twice might resolve the issue.

    Error: Error creating GroupMembership: googleapi: Error 409: Error(4003): Cannot create membership '[email protected]' in 'groups/xxx' because it already exists.
    Details:
    [
      {
        "@type": "type.googleapis.com/google.rpc.ResourceInfo",
        "description": "Error(4003): Cannot create membership '[email protected]' in 'groups/xxx' because it already exists.",
        "owner": "domain:cloudidentity.googleapis.com",
        "resourceType": "cloudidentity.googleapis.com/Membership"
      },
      {
        "@type": "type.googleapis.com/google.rpc.DebugInfo",
        "detail": "[ORIGINAL ERROR] generic::already_exists: Error(4003): Cannot create membership '[email protected]' in 'groups/xxx' because it already exists.\ncom.google.ccc.hosted.api.oneplatform.cloudidentity.error.exceptions.OpAlreadyExistsException: Error(4003): Cannot create membership '[email protected]' in 'groups/xxx' because it already exists. [google.rpc.error_details_ext] { message: \"Error(4003): Cannot create membership \\'[email protected]\\' in \\'groups/xxx\\' because it already exists.\" details { [type.googleapis.com/google.rpc.ResourceInfo] { resource_type: \"cloudidentity.googleapis.com/Membership\" owner: \"domain:cloudidentity.googleapis.com\" description: \"Error(4003): Cannot create membership \\'[email protected]\\' in \\'groups/xxx\\' because it already exists.\" } } }"
      }
    ]
  • Only Google Groups are supported.

  • Last OWNER cannot be removed from a Google Group.

Requirements

These sections describe requirements for using this module.

Software

The following dependencies must be available:

Permissions

A service account or user account needs the following roles to provision the resources of this module:

Google Cloud IAM roles

  • Service Usage Consumer: roles/serviceusage.serviceUsageConsumer on the billing project
  • Organization Viewer: roles/resourcemanager.organizationViewer if using domain instead of customer_id

The Project Factory module and the IAM module may be used in combination to provision a service account with the necessary roles applied.

Google Workspace (formerly known as G Suite) roles

To make the service account a Group Admin, you must have Google Workspace Super Admin access for your domain. Follow Assigning an admin role to the service account for instructions.

To create groups as an end user, the caller is required to authenticate as a member of the domain, i.e. you cannot use this module to create a group under bar.com with a foo.com user identity.

After the groups have been created, the organization’s Super Admin, Group Admin or any custom role with Groups privilege can always modify and delete the groups and their memberships. In addition, the group’s OWNER and MANAGER can edit membership, and OWNER can delete the group. Documentation around the three group default roles (OWNER, MANAGER and MEMBER) can be found here.

APIs

A project with the following APIs enabled must be used to host the resources of this module:

  • Cloud Identity API: cloudidentity.googleapis.com

The Project Factory module can be used to provision a project with the necessary APIs enabled.

To use the Cloud Identity Groups API, you must have Google Groups for Business enabled for your domain and allow end users to create groups.

Contributing

Refer to the contribution guidelines for information on contributing to this module.