# Create a role

Create a role, attach the policies it carries, and assign it to IAM users or let a workload assume it.

A role is a set of policies. Assigned to an IAM user, it gives the user every policy attached to the
role. With a trust policy, a workload such as a GitHub Actions job can assume it with an OIDC token
instead of a stored key. Replace ci-deployer with the role's name, and role-id,
user-id and policy-id with ids.

## Prerequisites

- Permission for `iam:CreateRole` and `iam:AttachRolePolicy`.
- To assign the role to a user, `iam:AssignUserRole` on that user; to take it away,
  `iam:RemoveUserRole`.
- To delete the role, `iam:DeleteRole`.
- In the console, also `iam:ListRoles` to see **Roles** and `iam:GetRole` on the role to open its
  page (without it the page is not found). To assign the role from a user's page, also `iam:GetUser`
  on the user.

## Create the role

**Console**
1. Open **Identity**, then choose **Roles**.
2. Choose **Create role**. Enter the name ci-deployer and, optionally, a description.
3. Choose **Create role**. The role's page opens.
4. Choose **Permissions**, pick a policy from the list, then choose **Attach**. Repeat for each
   policy.
5. To assign the role to a user, open the user, choose **Permissions**, pick the role from the list
   under **Roles**, then choose **Add**.

**CLI**
```sh
dcloud iam roles create --name ci-deployer --description "Deploys from CI"
dcloud iam roles attach-policy role-id --policy-id policy-id
dcloud iam users assign-role user-id --role-id role-id
```

**API**
```http
POST /iam/api/roles
{ "name": "ci-deployer", "description": "Deploys from CI" }
```

Then `POST /iam/api/roles/{id}/policies` with `{"policyId": …}`, and
`POST /iam/api/users/{id}/roles` with `{"roleId": …}`.

**Terraform**
```hcl
resource "dcloud_iam_role" "ci_deployer" {
  name = "ci-deployer"
}

resource "dcloud_iam_role_policy_attachment" "ci_deployer_deploy" {
  role_id   = dcloud_iam_role.ci_deployer.id
  policy_id = dcloud_iam_policy.deploy.id
}

resource "dcloud_iam_user_role_assignment" "alice_ci_deployer" {
  user_id = dcloud_iam_user.alice.id
  role_id = dcloud_iam_role.ci_deployer.id
}
```

## Result

Everyone assigned the role holds every policy attached to it. Detaching a policy, or removing the
role from a user, takes those permissions away at once.

For a workload to assume the role, give it a trust policy; see
[Set a trust policy](set-a-trust-policy.md).

To delete the role, open it and choose **Danger zone**, then **Delete role**, and type its name
(`dcloud iam roles delete`).

A preset role that ships with Deutsche Cloud is shown as managed: in the console its policies cannot be
changed and it cannot be deleted.

## If a change is refused

- 404 `Role not found`, `IAM user not found`, or `Role or policy not found` for an id that is not
  in your organization.
- 400 `Cannot delete a managed role` for a preset role.
- 409 `Quota exceeded: …` when the organization has as many roles as its quota allows; see
  [Quotas](quotas.md).

## Related

- [Principals and policies](principals-and-policies.md)
- [Web identity federation](web-identity-federation.md)
- `iam.roles.create` · `dcloud iam roles create` · `dcloud_iam_role` ·
  `dcloud_iam_role_policy_attachment` · `dcloud_iam_user_role_assignment`
