> ## Documentation Index
> Fetch the complete documentation index at: https://datum-4926dda5-docs-api-reference-demo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Role

> Role is the Schema for the roles API.

<Note>
  API resource reference for **Role**, part of the [IAM service](/api/iam/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
</Note>

<Warning>
  This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
</Warning>

## Identity

|         |                    |
| ------- | ------------------ |
| Group   | `iam.miloapis.com` |
| Version | `v1alpha1`         |
| Kind    | `Role`             |
| Scope   | Project            |

## Overview

A `Role` is a named collection of permissions that can be granted to users, groups, or machine accounts through an IAM policy. Each permission follows the `{service}.{resource}.{action}` format (for example, `compute.workloads.create`). Use a Role to bundle the permissions a person or system needs, then bind that Role in a policy to grant access within a Project. Roles can also inherit permissions from other roles, so you can compose broader roles from narrower ones.

## Spec fields

| Field                             | Type      | Required | Description                                                                                                                       |
| --------------------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `spec.launchStage`                | string    | Yes      | The launch stage of the role. One of `Early Access`, `Alpha`, `Beta`, `Stable`, or `Deprecated`.                                  |
| `spec.includedPermissions`        | \[]string | No       | The names of the permissions this role grants, each in `{service}.{resource}.{action}` format (e.g., `compute.workloads.create`). |
| `spec.inheritedRoles`             | \[]Object | No       | The list of roles from which this role inherits permissions.                                                                      |
| `spec.inheritedRoles[].name`      | string    | Yes      | Name of the referenced Role.                                                                                                      |
| `spec.inheritedRoles[].namespace` | string    | No       | Namespace of the referenced Role. Defaults to the namespace of the resource containing this reference.                            |

## Status fields (read-only)

| Field                         | Type      | Description                                                                                                                                                       |
| ----------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status.effectivePermissions` | \[]string | The complete flattened list of all permissions granted by this role, including those from `inheritedRoles` and `includedPermissions`. Computed by the controller. |
| `status.parent`               | string    | The resource name of the parent the role was created under.                                                                                                       |
| `status.conditions`           | \[]Object | Conditions representing the current status of the role.                                                                                                           |
| `status.observedGeneration`   | integer   | The most recent generation observed by the controller.                                                                                                            |

## Usage

```yaml theme={null}
apiVersion: iam.miloapis.com/v1alpha1
kind: Role
metadata:
  name: workload-editor
spec:
  launchStage: Alpha
  includedPermissions:
    - compute.workloads.create
    - compute.workloads.update
    - compute.workloads.get
```

```bash theme={null}
datumctl apply -f role.yaml --project my-project
datumctl get roles.iam.miloapis.com --project my-project
datumctl describe roles.iam.miloapis.com workload-editor --project my-project
```

<Tip>
  Run `datumctl explain roles.iam.miloapis.com --recursive` to see the full, live field tree for this resource.
</Tip>