Skip to main content

Connect Amazon Athena to Lakehouse

This guide walks you through how to connect Amazon Athena to your Lakehouse using AWS Glue Catalog Federation, so you can start querying your Atlan metadata with Athena.

The setup registers Atlan's Iceberg REST Catalog (Polaris) as a federated catalog in AWS Lake Formation, making Lakehouse tables available to any query engine that reads from the AWS Glue Data Catalog, including Athena.

Prerequisites​

Before you begin, make sure that:

  • You have enabled Lakehouse for your Atlan tenant. See Enable Lakehouse.
  • Your AWS environment can reach your Atlan tenant over HTTPS. If your tenant uses private networking (IP allowlists), see Private networking to allowlist your egress IPs first.
  • You have access to AWS Lake Formation, Glue, IAM, and Secrets Manager in your AWS account.
  • You have the OAuth Client ID and Client Secret provided by Atlan during Lakehouse setup.
  • You have your Atlan domain (for example, https://mycompany.atlan.com).

Store OAuth secret in secrets manager​

If you don't already have the Client Secret stored in AWS Secrets Manager:

  1. Go to Secrets Manager > Store a new secret.

  2. Store the Client Secret provided by Atlan. The secret key name must be:

    USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET

  3. Note the Secret ARN; you need it when configuring IAM permissions.

Create IAM role for Glue and Lake formation​

Create an IAM role that lets Glue and Lake Formation access the federated catalog.

Create role with custom trust policy​

  1. Go to IAM > Roles > Create role.

  2. Select Custom trust policy and use the following:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "Service": "glue.amazonaws.com"
          },
          "Action": "sts:AssumeRole"
        },
        {
          "Effect": "Allow",
          "Principal": {
            "Service": "lakeformation.amazonaws.com"
          },
          "Action": "sts:AssumeRole"
        }
      ]
    }

Attach inline policies​

Add the following two inline policies to the role.

Secrets Manager access: lets Glue read the OAuth credentials:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret",
        "secretsmanager:PutSecretValue"
      ],
      "Resource": [
        "<secret-arn>"
      ]
    }
  ]
}

Replace <secret-arn> with the ARN of the secret you created earlier.

S3 access (context store): provides read access to the Atlan context store bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadCrossAccountContextStore",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": "arn:aws:s3:::<bucket-name>/context_store/*"
    },
    {
      "Sid": "ListCrossAccountBucket",
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": "arn:aws:s3:::<bucket-name>"
    }
  ]
}

Replace <bucket-name> with the S3 bucket name provided by Atlan.

Share IAM Role ARN with Atlan​

Open a support ticket with Atlan and share the IAM Role ARN. Atlan grants this role read access to the S3 bucket that stores your Lakehouse data.

Create Iceberg REST catalog in Lake formation​

  1. In the AWS console, go to Lake Formation > Catalogs > Create catalog.

  2. Select Custom Iceberg REST Catalog as the data source.

  3. Configure the catalog:

    • Catalog name: Choose a meaningful name (for example, atlan_context_store)
    • Remote catalog name: context_store (provided by Atlan)
    • Casing type: Lowercase

  4. Under Connection, select an existing connection for Atlan Polaris, or create a new one with the following details:

    • Workspace URL: https://<atlan-domain>/api/polaris/api/catalog
    • Casing type: Lowercase only
    • Authentication type: OAuth2
    • Token URL: https://<atlan-domain>/api/polaris/api/catalog/v1/oauth/tokens
    • OAuth Client ID: Use the value provided by Atlan
    • OAuth Secret: Select the secret you stored in AWS Secrets Manager
    • Token URL parameter map scope: PRINCIPAL_ROLE:ALL

    Replace <atlan-domain> with your Atlan domain (for example, mycompany.atlan.com).

  5. Select the IAM role you created in the previous step, then click Run test to verify the connection to the Atlan catalog.

tip

The validation test works even before S3 access is granted, so you can complete this step while waiting for the S3 bucket permissions.

  1. If the test succeeds, click Create catalog.

Verify connection​

Once the catalog is created, open it in the Lake Formation console. The entity_metadata database appears in the list.

You can now query Lakehouse tables from Amazon Athena or any other service that reads from the Glue Data Catalog.

Update credentials after rotation​

If your Lakehouse credentials have been rotated, you need to update the OAuth secret stored in AWS Secrets Manager.

  1. In Atlan, go to the Lakehouse setup page and copy the updated OAuth Client ID and Client Secret.

  2. In AWS Secrets Manager, find the secret you created during setup (the one with key USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET) and update its value with the new Client Secret.

  3. If the OAuth Client ID has also changed, update it in your Lake Formation catalog connection settings:

    • Go to Lake Formation > Catalogs > select your Atlan catalog.
    • Edit the connection and update the OAuth Client ID.

  4. Run a test query in Athena to verify the updated credentials work.

Next steps​

After Lakehouse is enabled for your workspace, connect an Iceberg REST-compatible client to start querying your metadata.

  • Get connection details: In the Marketplace, open the Atlan Lakehouse tile and select View connection details. Note the catalog URI, catalog name, and OAuth credentials to configure your client.
  • Connect your query engine: Follow the guide for your specific engine to connect to the Lakehouse catalog: