assign-role

Assign Snowflake Role (DataPlatformSnowflakeTerraform)

Encodes how the IL Data Platform team grants a Snowflake role to a user via Terraform. Users are provisioned through Okta SSO, but their Snowflake attributes and role grants are managed declaratively in ImagineLearning/DataPlatformSnowflakeTerraform. Granting a role = a two-file edit + a PR.

This skill is the convention source. The /dp:assign-role command drives the workflow (pull → branch → edit → plan → confirm → push → PR) using these rules.

When NOT to use

• Creating or modifying Snowflake roles themselves (the snowflake_role definitions) — that's a different change, not a grant.
• Revoking access — this skill is grant-only in v1. To revoke, the convention is to comment out the user's line with a ticket note; do that manually for now.
• Non-IL Terraform — this is specific to the DataPlatformSnowflakeTerraform repo layout.

---

⛔ Hard Rules

1. Two files, always. A role grant touches src/role_grants.tf (add the user to the role's users list) and — only if the user isn't already declared — src/user.tf (add a snowflake_user resource).
2. Every change carries a ticket. The DP-XXXX ticket appears in the branch name, the PR title, the commit message, AND the inline # DP-XXXX comment on each added line. No ticket → stop and ask.
3. Validate the role exists against the canonical list (references/valid-roles.md) before editing. Terraform does NOT validate role names — a typo fails at terraform apply in CI, after merge. Catch it here.
4. Never push or open a PR without explicit user confirmation. Show the diff (and terraform plan output if available) first. Role grants are access-control changes.
5. Read-only on Snowflake. This skill edits Terraform HCL and opens a GitHub PR. It never connects to Snowflake.
6. Never auto-merge. The PR requires @edgenuity/DataPlatform CODEOWNERS review. Open it and stop.
7. Windows-safe: ASCII-only terminal output ([OK], [WARN], [FAIL]).

---

Repo facts

• Repo: ImagineLearning/DataPlatformSnowflakeTerraform (remote may be edgenuity/DataPlatformSnowflakeTerraform — use the configured origin).
• Default branch: master.
• Files that matter:
  • src/user.tf — one resource "snowflake_user" "<id>" block per user.
  • src/role_grants.tf — one resource "snowflake_role_grants" "<role>" block per role; the users = [...] list is what grants the role.
• CODEOWNERS: * @edgenuity/DataPlatform — every PR needs their review.
• CI: AWS CodeBuild runs terraform plan on the PR and terraform apply on merge to master. No local apply needed.

The repo path comes from the user (via --repo-path) or is discovered: look for a local clone of DataPlatformSnowflakeTerraform. If none is found, stop and ask the user for the path.

---

The canonical edit

User resource id (derive from email)

first.last@imaginelearning.com → resource id first_last (lowercase, dots → underscores, drop the domain).

• megan.heine@imaginelearning.com → megan_heine
• jacob.dygico@imaginelearning.com → jacob_dygico

If two people would collide on the same id, the repo uses a suffix like _il (e.g. ambily_varghese_il). Check src/user.tf for an existing block before assuming a new id is free.

Step A — Is the user already declared?

Search src/user.tf for resource "snowflake_user" "<id>":

• Found, active (uncommented) — no user.tf change needed. Go to Step C.
• Found, commented out (pre-staged pending users are common — they look like # resource "snowflake_user" "<id>" or appear only as commented lines in role_grants.tf) — uncomment the full block in user.tf. Go to Step C.
• Not found — add a new block (Step B).

Step B — Add the user to src/user.tf (new users only)

Exact format (match the existing file's indentation — 4 spaces, aligned =):

# DP-XXXX: <First Last>
resource "snowflake_user" "<id>" {
    default_role       = snowflake_role.<default_role>.name
    default_warehouse  = snowflake_warehouse.analyst_wh.name
    disabled           = false
    display_name       = "<First Last>"
    email              = "<email>"
    first_name         = "<First>"
    last_name          = "<Last>"
    login_name         = "<EMAIL-UPPERCASE>"
    name               = "<EMAIL-UPPERCASE>"
}

• default_role — for a brand-new user whose first/only role is the one being granted, set it to snowflake_role.<role>.name. If the user is being added a secondary role and already has a default, do not change their default.
• default_warehouse — snowflake_warehouse.analyst_wh.name is the common default for viewer/analyst roles. If unsure, match what similar users in the file use; do not invent a warehouse name.
• login_name / name — the email, uppercased (e.g. MEGAN.HEINE@IMAGINELEARNING.COM).

Step C — Add the user to the role in src/role_grants.tf

Find resource "snowflake_role_grants" "<role>". Inside its users = [ ... ] list, add:

        snowflake_user.<id>.name,  # DP-XXXX: <First Last>

• Place it among the active (uncommented) entries. Match the existing 8-space indentation.
• If the user appears as a commented-out "Pending" line in this list (# snowflake_user.<id>.name, # DP-NNNN: Pending ...), uncomment that line and update its trailing comment to the current ticket rather than adding a duplicate.
• If granting multiple roles, repeat Step C in each role's block.

---

Valid roles

The authoritative list is the set of snowflake_role_grants resource names in src/role_grants.tf. A snapshot is in references/valid-roles.md — read it to validate the requested role. If the requested role isn't in the snapshot, re-derive the live list:

grep -oP 'resource "snowflake_role_grants" "\K[^"]+' src/role_grants.tf | sort

Match case-insensitively (DATA_ENGINEER → data_engineer). If no match, stop with [FAIL] Role '<x>' not found. Valid roles: <closest matches>.

---

PR conventions

• Branch: DP-XXXX-grant-<role>-to-<id> (e.g. DP-3549-grant-core_viewer-to-megan_heine). The repo also has historical feature/DP-XXXX-... branches; the bare DP-XXXX-... form is fine.
• PR title: DP-XXXX: Grant <ROLE> for <First Last> (multiple users: list them).
• Commit message: same as PR title, with the Jira context in the body. End commits with the IL co-author trailer if your environment uses one.
• Reviewers: auto-requested from @edgenuity/DataPlatform via CODEOWNERS — don't add reviewers manually.

---

Edge cases & gotchas

Case	Handling
User already active with the role	No-op. Tell the user the grant already exists; don't open an empty PR.
User commented-out as "Pending"	Uncomment in both files; update the trailing comment to the current ticket.
New user, unknown default warehouse	Use analyst_wh for viewer/analyst roles; otherwise match a peer in user.tf. Never invent a warehouse.
Multiple roles in one request	One branch/PR; add the user to each role's block; set default_role to the primary one only.
Role name typo	Caught by the valid-roles check. Terraform won't catch it until CI apply.
Email not @imaginelearning.com	Service accounts use svc_* ids and may differ. For a human grant, confirm the domain with the user before proceeding.
Working tree dirty	Stop. Don't switch branches over uncommitted work.
terraform not installed locally	Skip the plan step; note it. CI will plan on the PR.

---

Workflow (driven by /dp:assign-role)

1. Validate inputs — role (against valid-roles), email (format + domain), ticket (DP-\d+). Derive the user id.
2. Locate the repo — --repo-path or discover a local DataPlatformSnowflakeTerraform clone. Confirm it's a git repo with a clean working tree.
3. Pull latest — git fetch origin master && git checkout master && git reset --hard origin/master.
4. Branch — git checkout -b DP-XXXX-grant-<role>-to-<id>.
5. Edit — Steps A/B/C above. Only touch user.tf if the user wasn't already active.
6. Plan (best-effort) — if terraform is on PATH and src/ initializes, run terraform plan in src/ and capture output. Skip gracefully if not.
7. Show + confirm — print git diff and the plan summary. AskUserQuestion to confirm before any push.
8. Commit + push — stage only src/user.tf + src/role_grants.tf; commit with the convention message; git push -u origin <branch>.
9. Open PR — gh pr create (or GitHub MCP) with the title convention and a body summarizing the grant + ticket. Print the PR URL. Stop — do not merge.

---

Related Skills

Need	Skill
Understand DataPlatformSnowflake dbt conventions	dp:dbt, dp:dbt-fix-conventions
Publish a fix summary to Confluence	dp:publish-ticket-confluence
Generic code generation from a Jira ticket	il:generate-code (this skill can be loaded by it when paths touch DataPlatformSnowflakeTerraform)