> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/engine-guide/athena/permissions-and-grants.md).

# Permissions and grants

Configure required Athena IAM roles, permissions, and DataOS access for Vulcan deployments.

This is the authorize stage. Complete it before configuring a gateway or writing models.

## Athena-side permissions

Three roles are required, each with a distinct scope. Do not collapse them into one. On Athena, access is enforced through **AWS IAM** (and optionally Lake Formation), not SQL `GRANT` statements.

| Role                | Who holds it                            | Purpose                                                                                 |
| ------------------- | --------------------------------------- | --------------------------------------------------------------------------------------- |
| Admin role          | AWS / data platform admin               | Creates S3 buckets, Glue databases, workgroups, IAM policies                            |
| Vulcan service role | IAM user or role whose keys Vulcan uses | Runs Athena queries; creates Glue tables/schemas; reads/writes S3 warehouse and staging |
| Consumer role       | BI users, endpoint consumers            | Read-only Athena + Glue + S3 for Data Product outputs                                   |

### Minimum IAM capabilities for the Vulcan service principal

Tighten ARNs to your account.

| Area         | Actions (illustrative)                                                                                                                                                    |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Athena       | `athena:StartQueryExecution`, `athena:GetQueryExecution`, `athena:GetQueryResults`, `athena:StopQueryExecution`, `athena:GetWorkGroup`                                    |
| Glue         | `glue:GetDatabase`, `glue:GetDatabases`, `glue:CreateDatabase`, `glue:GetTable`, `glue:GetTables`, `glue:CreateTable`, `glue:UpdateTable`, `glue:DeleteTable` (as needed) |
| S3 staging   | `s3:GetObject`, `s3:PutObject`, `s3:ListBucket` on the `ATHENA_S3_STAGING_DIR` bucket/prefix                                                                              |
| S3 warehouse | Same actions on the `ATHENA_S3_WAREHOUSE_LOCATION` prefix (model data, external table locations)                                                                          |

### Consumer role: read-only pattern

* `glue:Get*` on target databases/tables
* `athena:StartQueryExecution` plus results read, optionally on a separate consumer workgroup
* `s3:GetObject` / `ListBucket` on published dataset prefixes only

Verify access from the Athena query editor or CLI, in the same workgroup as your config:

```sql
SELECT current_user AS user;
SHOW DATABASES;
SHOW TABLES IN retail_source;
```

## DataOS permissions

Provision these permissions before you create and deploy an Athena Data Product:

| Permission                                        | What it allows                                                                    | Who grants it                 |
| ------------------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------- |
| Tenant access                                     | Build and manage Data Products in your tenant.                                    | Tenant admin                  |
| `roles:id:data-dev` (or your tenant's equivalent) | Create and apply Vulcan resources. Confirm your role with `dataos-ctl user get`.  | Tenant admin                  |
| Can Use on compute, and Secrets                   | Use the assigned resource. Resource access is deny-by-default.                    | Resource owner or admin       |
| Instance secret                                   | Project AWS credentials and Athena settings into the Vulcan resource.             | Secret owner or admin         |
| `git-sync` Secret                                 | Pull model code from Git. Request a `git-sync` Secret instead of raw credentials. | Tenant, data, or Secret admin |
| `vulcan-athena` stack or approved compute         | Run the Vulcan workflow and API on the Athena image.                              | DataOS operator               |

Production deploys typically project these env vars from an instance secret:

* `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`
* `ATHENA_WORK_GROUP`, `ATHENA_S3_STAGING_DIR`, `ATHENA_SCHEMA_NAME`, `ATHENA_CATALOG_NAME`, `ATHENA_S3_WAREHOUSE_LOCATION`

### Before you connect checklist

* [ ] `AWS_REGION` matches the bucket and workgroup region
* [ ] Athena workgroup exists; `ATHENA_WORK_GROUP` matches the console name (often `primary`)
* [ ] `ATHENA_S3_STAGING_DIR` is a valid `s3://` URI with write access for the service principal
* [ ] `ATHENA_S3_WAREHOUSE_LOCATION` is a valid `s3://.../` base prefix for model and external table data
* [ ] The Glue catalog `ATHENA_CATALOG_NAME` (default `awsdatacatalog`) and database `ATHENA_SCHEMA_NAME` exist, or will be created by Vulcan / `before_all`
* [ ] Source data is reachable (external tables, or Nilus-landed Parquet under known prefixes)
* [ ] IAM keys are rotated on a schedule; prefer IRSA / instance roles in production over long-lived keys where possible

### Next step

After access is ready, configure the gateway in [Connect to Athena](https://v2.dataos.info/references/engine-guide/athena/connect-to-athena.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/references/engine-guide/athena/permissions-and-grants.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
