# Create a group

Create a group of IAM users, add users to it and attach the policies they share.

Every member of a group holds every policy attached to it, so you attach a policy once instead of
to each user. A user in three groups holds the policies of all three. Replace developers
with the group's name, and group-id, user-id and policy-id with ids.

## Prerequisites

- Permission for `iam:CreateGroup`, `iam:AddUserToGroup` and `iam:AttachGroupPolicy`.
- To take a user out or detach a policy, `iam:RemoveUserFromGroup` or `iam:DetachGroupPolicy`; to
  delete the group, `iam:DeleteGroup`.
- In the console, also `iam:ListGroups` to see **Groups**, and `iam:GetGroup` on the group to open
  its page (without it the page is not found).

## Create the group and fill it

**Console**
1. Open **Identity**, then choose **Groups**.
2. Choose **Create group**. Enter the name developers and, optionally, a description.
3. Choose **Create group**. The group's page opens.
4. Choose **Members**, pick a user from the list, then choose **Add**. Repeat for each user.
5. Choose **Permissions**, pick a policy from the list, then choose **Attach**. Repeat for each
   policy.

**CLI**
```sh
dcloud iam groups create --name developers
dcloud iam groups add-member group-id --iam-user-id user-id
dcloud iam groups attach-policy group-id --policy-id policy-id
```

**API**
```http
POST /iam/api/groups
{ "name": "developers", "description": "Everyone who builds the app" }
```

Then `POST /iam/api/groups/{id}/members` with `{"iamUserId": …}` and
`POST /iam/api/groups/{id}/policies` with `{"policyId": …}`.

**Terraform**
```hcl
resource "dcloud_iam_group" "developers" {
  name = "developers"
}

resource "dcloud_iam_group_membership" "alice_developers" {
  group_id = dcloud_iam_group.developers.id
  user_id  = dcloud_iam_user.alice.id
}

resource "dcloud_iam_group_policy_attachment" "developers_read" {
  group_id  = dcloud_iam_group.developers.id
  policy_id = dcloud_iam_policy.s3_read.id
}
```

## Result

Users added to the group hold its policies from their next request on. Removing a user, or
detaching a policy, takes the permissions away at once. A group holds IAM users only, not other
groups.

To delete the group, open it and choose **Danger zone**, then **Delete group**, and type its name
(`dcloud iam groups delete`). Its members lose the permissions it carried.

## If a change is refused

- 404 `Group not found`, `IAM user not found`, or `Group or policy not found` for an id that is not
  in your organization.
- 409 `Quota exceeded: …` when the organization has as many groups as its quota allows; see
  [Quotas](quotas.md).

## Related

- [Create a policy](create-a-policy.md)
- [Map identity provider groups to IAM groups](map-idp-groups-to-iam-groups.md)
- `iam.groups.create` · `dcloud iam groups create` · `dcloud_iam_group` ·
  `dcloud_iam_group_membership` · `dcloud_iam_group_policy_attachment`
