fresh-borzoni commented on code in PR #3424: URL: https://github.com/apache/fluss/pull/3424#discussion_r3480177188
########## website/docs/streaming-lakehouse/integrate-data-lakes/catalogs/glue.md: ########## @@ -0,0 +1,411 @@ +--- +title: AWS Glue +sidebar_position: 2 +--- + +# AWS Glue + +## Introduction + +[AWS Glue](https://aws.amazon.com/glue/) is a serverless data integration service that includes a central metadata repository known as the AWS Glue Data Catalog. The Glue Data Catalog is compatible with Apache Iceberg, making it a convenient option for managing Iceberg table metadata on AWS. + +This guide explains how to configure Fluss to use AWS Glue as its Iceberg catalog. For general Iceberg integration details (table mapping, data types, limitations), see [Iceberg](../formats/iceberg.md). + +## How It Works + +When Fluss is configured with AWS Glue as its Iceberg catalog: + +1. **Data ingestion**: Applications write data to Fluss tables using the Fluss client (Java/Python), Flink SQL, or any Kafka-compatible producer. Fluss stores this data in its real-time log (similar to Kafka topics). +2. **Tiering to Iceberg**: A separate Flink job (the [tiering service](maintenance/tiered-storage/lakehouse-storage.md#start-the-datalake-tiering-service)) periodically reads accumulated data from Fluss, converts it to Parquet format, writes the files to S3, and commits an Iceberg snapshot to the Glue Data Catalog. +3. **Query via Athena/Spark/Trino**: Any Iceberg-compatible engine can discover and query the tiered tables through AWS Glue — no additional configuration needed. + +``` +┌─ Data Sources ─────────┐ ┌─ Fluss Cluster ──────┐ ┌─ AWS ────────────────────┐ +│ │ │ │ │ │ +│ App (Fluss client) ─┼────▶│ Coordinator │ │ Glue Data Catalog │ +│ Flink CDC job ─┼────▶│ TabletServer(s) │ │ (table metadata) │ +│ Kafka producer ─┼────▶│ ZooKeeper │ │ │ +│ │ │ │ │ S3 Bucket │ +└─────────────────────────┘ └──────────┬───────────┘ │ (Parquet data files) │ + │ │ │ + ┌──────────▼───────────┐ │ Athena / Spark / Trino │ + │ Flink Tiering Job ├────▶│ (query engine) │ + │ (reads Fluss log, │ │ │ + │ writes Iceberg) │ └──────────────────────────┘ + └──────────────────────┘ +``` + +> **KEY CONCEPT**: Flink is used here for the **tiering service** (Fluss → Iceberg/S3/Glue) and optionally for data ingestion via SQL. But Flink is NOT the only way to write data to Fluss. Applications can write directly using the Fluss client library (Java, Python) or any Kafka-compatible producer. The tiering service is what bridges Fluss's real-time log to the Glue Data Catalog. + +## Prerequisites + +### Java Version + +Fluss 0.9.x requires **Java 17 or later** for the Tablet Server. Java 11 will fail with `NoSuchMethodError: MappedByteBuffer.duplicate()`. + +### AWS IAM Permissions + +The processes running Fluss servers and the Flink tiering service must have IAM permissions for both Glue and S3. Below is a minimal IAM policy: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "glue:CreateDatabase", + "glue:GetDatabase", + "glue:GetDatabases", + "glue:DeleteDatabase", + "glue:CreateTable", + "glue:GetTable", + "glue:GetTables", + "glue:UpdateTable", + "glue:DeleteTable" + ], + "Resource": [ + "arn:aws:glue:<region>:<account-id>:catalog", + "arn:aws:glue:<region>:<account-id>:database/*", + "arn:aws:glue:<region>:<account-id>:table/*" + ] + }, + { + "Effect": "Allow", + "Action": [ + "s3:GetObject", + "s3:PutObject", + "s3:DeleteObject", + "s3:ListBucket" + ], + "Resource": [ + "arn:aws:s3:::<your-bucket>", + "arn:aws:s3:::<your-bucket>/*" + ] + } + ] +} +``` + +> **NOTE**: If your account uses **AWS Lake Formation**, the IAM role must also have Lake Formation permissions (Create Table, Describe, Alter, Insert, Select, Delete, Drop) on the target database. Standard IAM `glue:*` permissions alone are not sufficient when Lake Formation governance is enabled. + +### Prepare Required JARs + +Fluss bundles `iceberg-core` but does **not** bundle the Glue catalog implementation or the AWS SDK. You must supply additional JARs. + +#### For Fluss Servers (Coordinator & Tablet Servers) + +Place the following JARs in the `${FLUSS_HOME}/plugins/iceberg/` directory: + +- **Iceberg AWS Bundle**: [iceberg-aws-bundle-1.10.1.jar](https://repo1.maven.org/maven2/org/apache/iceberg/iceberg-aws-bundle/1.10.1/iceberg-aws-bundle-1.10.1.jar) +- **Iceberg AWS**: [iceberg-aws-1.10.1.jar](https://repo1.maven.org/maven2/org/apache/iceberg/iceberg-aws/1.10.1/iceberg-aws-1.10.1.jar) +- **Failsafe**: [failsafe-3.3.2.jar](https://repo1.maven.org/maven2/dev/failsafe/failsafe/3.3.2/failsafe-3.3.2.jar) — required by `iceberg-aws` for Glue API retry logic + +Both Iceberg JARs are required. The bundle provides AWS SDK v2 dependencies, while `iceberg-aws` provides the `GlueCatalog` class that Iceberg loads via reflection. The plugin classloader cannot find `GlueCatalog` from the bundle alone. The `failsafe` library is a transitive dependency of `iceberg-aws` that is not bundled. + +> **NOTE**: You need **all three** JARs. Using only the bundle will result in `ClassNotFoundException: org.apache.iceberg.aws.glue.GlueCatalog`. Missing `failsafe` will cause `NoClassDefFoundError: dev/failsafe/FailsafeException`. + +Additionally, you need the Fluss S3 filesystem plugin for remote storage access. Place [fluss-fs-s3-$FLUSS_VERSION$.jar]($FLUSS_MAVEN_REPO_URL$/org/apache/fluss/fluss-fs-s3/$FLUSS_VERSION$/fluss-fs-s3-$FLUSS_VERSION$.jar) in `${FLUSS_HOME}/plugins/s3/`. See [S3 Dependencies](../../../maintenance/filesystems/s3.md#dependencies) for details. + +> **TIP**: The Fluss binary distribution already includes `fluss-lake-iceberg-$FLUSS_VERSION$.jar` in `plugins/iceberg/`. You do not need to download it separately — only add the three JARs above (iceberg-aws-bundle, iceberg-aws, failsafe). + +#### For the Flink Tiering Service + +Place the following JARs in `${FLINK_HOME}/lib`: + +1. **Iceberg AWS Bundle**: `iceberg-aws-bundle-1.10.1.jar` (same as above) +2. **Iceberg AWS**: `iceberg-aws-1.10.1.jar` (same as above — provides `GlueCatalog` class) +3. **Failsafe**: `failsafe-3.3.2.jar` (same as above — Glue retry logic) +4. **Fluss Flink Connector**: [fluss-flink-1.20-$FLUSS_VERSION$.jar]($FLUSS_MAVEN_REPO_URL$/org/apache/fluss/fluss-flink-1.20/$FLUSS_VERSION$/fluss-flink-1.20-$FLUSS_VERSION$.jar) (pick the version matching your Flink runtime) +5. **Fluss Lake Iceberg**: [fluss-lake-iceberg-$FLUSS_VERSION$.jar]($FLUSS_MAVEN_REPO_URL$/org/apache/fluss/fluss-lake-iceberg/$FLUSS_VERSION$/fluss-lake-iceberg-$FLUSS_VERSION$.jar) +6. **Fluss Flink Tiering**: [fluss-flink-tiering-$FLUSS_VERSION$.jar]($FLUSS_MAVEN_REPO_URL$/org/apache/fluss/fluss-flink-tiering/$FLUSS_VERSION$/fluss-flink-tiering-$FLUSS_VERSION$.jar) — the tiering job JAR itself +7. **Fluss S3 Filesystem**: [fluss-fs-s3-$FLUSS_VERSION$.jar]($FLUSS_MAVEN_REPO_URL$/org/apache/fluss/fluss-fs-s3/$FLUSS_VERSION$/fluss-fs-s3-$FLUSS_VERSION$.jar) (if S3 is used as Fluss remote storage) +8. **Hadoop Client**: [hadoop-client-api-3.3.6.jar](https://repo1.maven.org/maven2/org/apache/hadoop/hadoop-client-api/3.3.6/hadoop-client-api-3.3.6.jar) and [hadoop-client-runtime-3.3.6.jar](https://repo1.maven.org/maven2/org/apache/hadoop/hadoop-client-runtime/3.3.6/hadoop-client-runtime-3.3.6.jar) — required by the Iceberg Parquet writer + +> **NOTE**: Despite the Glue catalog itself not requiring Hadoop, the **tiering service** needs Hadoop classes (`org.apache.hadoop.conf.Configuration`) for writing Parquet files via Iceberg. Use the `hadoop-client-api` and `hadoop-client-runtime` JARs (not the full Hadoop distribution or `flink-shaded-hadoop-2-uber`) to avoid classpath conflicts with Flink's bundled Avro version. Using the uber JAR causes `NoSuchMethodError: LogicalTypes.timestampNanos()`. + +> **WARNING**: Do **not** add S3 credentials to `flink-conf.yaml` by appending key-value pairs — this can break Flink's memory configuration parser. Instead, use environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION`) or a `HADOOP_CONF_DIR` with a `core-site.xml` file. + +## Configure Fluss with AWS Glue + +### Cluster Configuration + +Add the following to your `server.yaml`: + +```yaml +datalake.format: iceberg +datalake.iceberg.type: glue +datalake.iceberg.warehouse: s3://<your-bucket>/<warehouse-path> +``` + +Fluss strips the `datalake.iceberg.` prefix and passes the remaining properties directly to Iceberg's Glue catalog. The properties above become `type=glue` and `warehouse=s3://...` when initializing the catalog. + +You can pass any [Iceberg AWS catalog property](https://iceberg.apache.org/docs/1.10.1/aws/#glue-catalog) using the same prefix. Common additional properties: + +```yaml +# Specify the AWS region (required if not using default region from credentials chain) +datalake.iceberg.client.region: us-east-1 + +# Use S3FileIO explicitly (Glue catalog defaults to this when warehouse is s3://) +datalake.iceberg.io-impl: org.apache.iceberg.aws.s3.S3FileIO + +# Optional: restrict catalog to a specific Glue database prefix +datalake.iceberg.glue.catalog-id: <aws-account-id> +``` + +#### Authentication + +**IAM Role (Recommended)**: If running on AWS (EKS, ECS, EC2) with an attached IAM role, no credential configuration is needed for the **Glue catalog connection**. The Iceberg AWS SDK uses the [default credentials provider chain](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-chain.html) automatically. + +However, the **Fluss S3 filesystem plugin** (used for `remote.data.dir`) has a known limitation: it uses a custom delegation token mechanism that does not support IMDSv2 or ECS task role credentials. This affects: Review Comment: Thank you for putting this, we should definitely improve error handling here and `table_id`issue. The EKS/IRSA "no credential config needed" note doesn't hold for remote.data.dir/tiering as S3A's default chain has no web-identity provider (intentional decision in Hadoop), so IRSA won't resolve there. Needs:s3.aws.credentials.provider: com.amazonaws.auth.WebIdentityTokenCredentialsProvider,org.apache.hadoop.fs.s3a.auth.IAMInstanceCredentialsProvider or similar Can you try this and share the results? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
