# Datadog "Engineering" custom role

Governed replacement for the managed **Datadog Standard Role**.

## Why

Today every Datadog user lands on the **Datadog Standard Role**, a managed role
we cannot edit. It grants write access to (almost) everything and automatically
gains permissions for every new product Datadog ships — so we get no chance to
evaluate cost or decide whether we want people using a new product. We also want
to stop blanket create/update of Software Catalog entries through the console
(those should go through our tooling).

This stack creates a custom **Engineering** role we *can* edit, with permissions
managed as an explicit **allowlist** (`permissions.tf`). New products are not
granted until we add them — that is the governance gate.

## How it works

- `data "datadog_permissions"` returns only **grantable** (non-restricted)
  permissions. The baseline **read** permissions are *restricted* — auto-granted
  to every user in the org and impossible to revoke — so this role keeps full
  read/visibility no matter what. We only ever choose which **write/elevated**
  permissions to grant.
- `permissions.tf` lists the permission names to grant, grouped by product with
  rationale. Reads are granted broadly (no friction); writes only for products
  we use; unused products are omitted.
- Unknown/typo'd names are dropped safely and reported via outputs (the apply
  does not break).

### Key decisions baked in

| Topic | Decision |
|-------|----------|
| Model | **Allowlist** — governance over new products. |
| Software Catalog | **Keep `apm_service_catalog_write`.** It's a single permission covering create + update + **delete** — there is no delete-only permission. Delete must keep working until the GitHub-archive→catalog-cleanup tooling exists, so we keep write for now and revisit then. |
| Migration | Terraform **only creates the role**; user reassignment is an operational step (below). |
| Role name | `Engineering` (override via `role_name`). |

## Before you apply

Run `terraform plan` and review two outputs:

- **`unresolved_permissions`** — allowlist names Datadog didn't accept. Check for
  typos or write perms that silently failed to attach (e.g. a Synthetics name
  variant). Anything important here means a missing grant = potential friction.
- **`restricted_by_role`** — every grantable permission the role will *not* have.
  This is the exact list of capabilities we're locking down. Confirm with the
  team that nothing here is used day-to-day before applying.

Adjust `permissions.tf` accordingly, then re-plan until both outputs look right.

## Migrating users (operational, not Terraform)

`datadog_user_role` only *adds* a role; it cannot strip the Standard Role that
users received at first AD login. If a user keeps **both** roles they get the
union of permissions, defeating the restriction. So migration = for each user,
**add Engineering + remove Datadog Standard Role**.

Do this via the Datadog UI (Organization Settings → Users) or the API/`datadog`
CLI in bulk after this role exists. Get the role id from `terraform output
role_id`. Validate on a single user first, confirm their access, then roll out.

## New users

New users still auto-land on the Standard Role at first login (driven by the
single Datadog AD group, not Terraform). Until that default is changed, new
joiners need to be moved to Engineering as part of onboarding — fold this into
the existing Datadog onboarding flow. (Tracking item: find/define the org
default-role mechanism so new users get Engineering automatically.)