Athena Workgroup

Note: This documentation is also available in a rendered format here.

Deploys Athena workgroups with encrypted query results, KMS key management, S3 results buckets, and IAM managed policies for workgroup access. Supports identity federation and configurable query limits. Use this module when you need a standalone Athena workgroup — note that the Data Science Team and DataOps Project modules both provision their own Athena workgroups automatically, so you only need this module for workgroups outside of those contexts.

Deployed Resources

This module deploys and integrates the following resources:

Workgroup KMS Key - Customer-managed KMS key used to encrypt all Workgroup resources which support encryption at rest.

Workgroup Results S3 Bucket - S3 bucket for Athena query results, referenced by the Athena Workgroup configuration and client connection configurations.

Athena Workgroup - The Athena Workgroup with configurable query limits and IAM managed policy for access control.

Workgroup Usage IAM Managed Policy - IAM managed policy granting Athena workgroup access, automatically attached to mutable user roles.

Note: Immutable user roles (e.g., IAM Identity Center/SSO roles) require out-of-band binding to the managed policy via SSO Permission Set.

AthenaWorkgroup

Data Lake — Deploy the data lake buckets and Glue databases that Athena workgroups query against
Data Science Team — Provisions team-specific Athena workgroups automatically as part of a data science team environment
DataOps Project — Provisions project-specific Athena workgroups automatically as part of a DataOps project
Roles — Create IAM roles that can be referenced as data admin or user roles for workgroup access
Glue Catalog Settings — Configure cross-account Glue Catalog access for querying data across accounts

Security/Compliance Details

This module is designed in alignment with MDAA security/compliance principles and CDK nag rulesets. Additional review is recommended prior to production deployment, ensuring organization-specific compliance requirements are met.

Encryption at Rest:
- Query results encrypted with customer-managed KMS key
- Results S3 bucket configured to require KMS encryption
Least Privilege:
- Workgroup access governed by IAM managed policies bound to mutable user roles
- Key admin/usage access granted to data admin roles via key policy
- Key usage access granted to user roles via key policy
- Results bucket read/write access granted to user roles via bucket policy
- Results bucket read/write/super access granted to data admin roles via bucket policy
Separation of Duties:
- Distinct data admin and user role access levels
- Configurable bytes-scanned cutoff per query to prevent runaway costs

Configuration

MDAA Config

Add the following snippet to your mdaa.yaml under the modules: section of a domain/env in order to use this module:

athena-workgroup: # Module Name can be customized
  module_path: '@aws-mdaa/athena-workgroup' # Must match module NPM package name
  module_configs:
    - ./athena-workgroup.yaml # Filename/path can be customized

Module Config Samples and Variants

Copy the contents of the relevant sample config below into the ./athena-workgroup.yaml file referenced in the MDAA config snippet above.

Minimal Configuration

Contains only the required admin and user role references. All other properties (workgroup configuration, verbatim policy name prefix) are optional. Start here for a quick Athena workgroup deployment before adding query cost controls or SSO role bindings.

sample-config-minimal.yaml

# Contents available via above link
# Minimal Athena Workgroup module configuration.
# Contains only the required admin and user role references. All
# other properties (workgroup configuration, verbatim policy name
# prefix) are optional.

# See CONFIGURATION.md for role reference options (name, arn, id).
# Admin roles granted full access to Athena workgroup resources
dataAdminRoles:
  - name: Admin

# User roles granted query execution access to the workgroup
athenaUserRoles:
  - arn: arn:{{partition}}:iam::{{account}}:role/sample-org-dev-instance1-roles-data-scientist

Comprehensive Configuration

Deploys an Athena workgroup with KMS-encrypted results bucket, admin and user role access (including SSO and immutable roles), query cost controls, and a verbatim policy name prefix. Use this as a reference when you need full control over encryption, role bindings, and query cost guardrails.

sample-config-comprehensive.yaml

# Contents available via above link
# Comprehensive Athena Workgroup module configuration.
# Deploys an Athena workgroup with KMS-encrypted results bucket,
# admin and user role access (including SSO and immutable roles),
# query cost controls, and a verbatim policy name prefix.
# Exercises every non-excluded property at full depth.

# See CONFIGURATION.md for role reference options (name, arn, id).
# Admin roles granted full access to Athena workgroup resources
# including KMS key, results bucket, and workgroup management.
# Roles can be referenced by name (auto-expanded to ARN) or by explicit ARN.
dataAdminRoles:
  # Role by ARN
  - arn: arn:{{partition}}:iam::{{account}}:role/AthenaAdmin

# User roles granted query execution access to the workgroup and
# read/write access to the results bucket
athenaUserRoles:
  # Role by ARN via SSM parameter
  - arn: ssm:/sample-org/instance2/generated-role/data-scientist/arn
  # Role by ARN
  - arn: arn:{{partition}}:iam::{{account}}:role/sample-org-dev-instance1-roles-data-scientist
  # Role by MDAA-generated role ID
  - id: generated-role-id:data-scientist
  # Immutable SSO role — receives bucket/KMS access only
  - arn: arn:{{partition}}:iam::{{account}}:role/aws-reserved/sso.amazonaws.com/{{region}}/AWSReservedSSO_data_scientist12321421
    # Flag indicating the role is immutable and not modified by MDAA
    immutable: true
  # SSO-managed role (resolved from IAM Identity Center)
  - name: data_scientist
    sso: true

# Workgroup configuration settings for query cost controls
workgroupConfiguration:
  # Upper limit in bytes for data scanned per query.
  # Queries exceeding this limit are cancelled.
  bytesScannedCutoffPerQuery: 10000000000

# Verbatim policy name prefix bypassing MDAA naming conventions.
# Useful for cross-account policy portability and SSO permission set integration.
verbatimPolicyNamePrefix: 'some-prefix'

Config Schema Docs