Group.yaml

# Copyright 2024 Google Inc.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

---
name: 'Group'
description: |
  A Cloud Identity resource representing a Group.
references:
  guides:
    'Official Documentation': 'https://cloud.google.com/identity/docs/how-to/setup'
  api: 'https://cloud.google.com/identity/docs/reference/rest/v1beta1/groups'
docs:
  warning: |
    If you are using User ADCs (Application Default Credentials) with this resource,
    you must specify a `billing_project` and set `user_project_override` to true
    in the provider configuration. Otherwise the Cloud Identity API will return a 403 error.
    Your account must have the `serviceusage.services.use` permission on the
    `billing_project` you defined.
base_url: 'groups?initialGroupConfig={{initial_group_config}}'
self_link: '{{name}}'
update_url: '{{name}}'
update_verb: 'PATCH'
update_mask: true
import_format:
  - '{{name}}'
timeouts:
  insert_minutes: 20
  update_minutes: 20
  delete_minutes: 20
async:
  type: 'PollAsync'
  check_response_func_existence: 'transport_tpg.PollCheckForExistenceWith403'
  check_response_func_absence: 'transport_tpg.PollCheckForAbsenceWith403'
  suppress_error: false
  target_occurrences: 10
  actions: ['create', 'update', 'delete']
custom_code:
  custom_import: 'templates/terraform/custom_import/cloud_identity_group_import.go.tmpl'
exclude_sweeper: true
examples:
  - name: 'cloud_identity_groups_basic'
    primary_resource_id: 'cloud_identity_group_basic'
    vars:
      id_group: 'my-identity-group'
    test_env_vars:
      org_domain: 'ORG_DOMAIN'
      cust_id: 'CUST_ID'
    # Has a handwritten test due to CloudIdentityGroup-related tests needing to run synchronously
    exclude_test: true
parameters:
  - name: 'initialGroupConfig'
    type: Enum
    description: |
      The initial configuration options for creating a Group.

      See the
      [API reference](https://cloud.google.com/identity/docs/reference/rest/v1beta1/groups/create#initialgroupconfig)
      for possible values.
    url_param_only: true
    immutable: true
    default_value: "EMPTY"
    enum_values:
      - 'INITIAL_GROUP_CONFIG_UNSPECIFIED'
      - 'WITH_INITIAL_OWNER'
      - 'EMPTY'
properties:
  - name: 'name'
    type: String
    description: |
      Resource name of the Group in the format: groups/{group_id}, where group_id
      is the unique ID assigned to the Group.
    output: true
  - name: 'groupKey'
    type: NestedObject
    description: |
      EntityKey of the Group.
    required: true
    immutable: true
    properties:
      - name: 'id'
        type: String
        description: |
          The ID of the entity.

          For Google-managed entities, the id must be the email address of an existing
          group or user.

          For external-identity-mapped entities, the id must be a string conforming
          to the Identity Source's requirements.

          Must be unique within a namespace.
        required: true
        immutable: true
      - name: 'namespace'
        type: String
        description: |
          The namespace in which the entity exists.

          If not specified, the EntityKey represents a Google-managed entity
          such as a Google user or a Google Group.

          If specified, the EntityKey represents an external-identity-mapped group.
          The namespace must correspond to an identity source created in Admin Console
          and must be in the form of `identitysources/{identity_source_id}`.
        immutable: true
  - name: 'parent'
    type: String
    description: |
      The resource name of the entity under which this Group resides in the
      Cloud Identity resource hierarchy.

      Must be of the form identitysources/{identity_source_id} for external-identity-mapped
      groups or customers/{customer_id} for Google Groups.
    required: true
    immutable: true
  - name: 'displayName'
    type: String
    description: |
      The display name of the Group.
  - name: 'description'
    type: String
    description: |
      An extended description to help users determine the purpose of a Group.
      Must not be longer than 4,096 characters.
  - name: 'additionalGroupKeys'
    type: Array
    description: 'Additional group keys associated with the Group'
    output: true
    item_type:
      type: NestedObject
      properties:
        - name: 'id'
          type: String
          description: |
            The ID of the entity.

            For Google-managed entities, the id must be the email address of an existing
            group or user.

            For external-identity-mapped entities, the id must be a string conforming
            to the Identity Source's requirements.

            Must be unique within a namespace.
          output: true
        - name: 'namespace'
          type: String
          description: |
            The namespace in which the entity exists.

            If not specified, the EntityKey represents a Google-managed entity
            such as a Google user or a Google Group.

            If specified, the EntityKey represents an external-identity-mapped group.
            The namespace must correspond to an identity source created in Admin Console
            and must be in the form of `identitysources/{identity_source_id}`.
          output: true
  - name: 'createTime'
    type: String
    description: |
      The time when the Group was created.
    output: true
  - name: 'updateTime'
    type: String
    description: |
      The time when the Group was last updated.
    output: true
  - name: 'labels'
    type: KeyValuePairs
    description: |
      One or more label entries that apply to the Group. Currently supported labels contain a key with an empty value.

      Google Groups are the default type of group and have a label with a key of cloudidentity.googleapis.com/groups.discussion_forum and an empty value.

      Existing Google Groups can have an additional label with a key of cloudidentity.googleapis.com/groups.security and an empty value added to them. This is an immutable change and the security label cannot be removed once added.

      Dynamic groups have a label with a key of cloudidentity.googleapis.com/groups.dynamic.

      Identity-mapped groups for Cloud Search have a label with a key of system/groups/external and an empty value.
    required: true