Manage Lakehouse Iceberg REST catalog table ACLs

Lakehouse for Apache Iceberg supports table-level access control for Apache Iceberg tables in Cloud Storage that use the Lakehouse runtime catalog.

The Lakehouse runtime catalog manages the table metadata, while Identity and Access Management (IAM) policies define the permissions. The gcloud CLI provides the commands required to get and set these IAM policies.

Before you begin

  1. Verify that billing is enabled for your Google Cloud project.

  2. Enable the BigLake API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  3. Install and initialize the Google Cloud SDK.
  4. Verify that you have an existing Apache Iceberg REST catalog endpoint and namespace.
  5. Verify that you have an existing Lakehouse Iceberg table within the specified catalog and namespace.

Required roles

To get the permissions that you need to manage Access Control Lists (ACLs) for Iceberg tables, ask your administrator to grant you the following IAM roles:

  • All: BigLake Admin (roles/biglake.admin) on the project

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

How it works

IAM policies define which principals have specific roles and permissions for a resource. You can manage access to your resources by getting and setting these policies.

Relevant IAM roles

You can apply the following common IAM roles to Lakehouse resources:

  • roles/biglake.admin: provides full control over Lakehouse resources.
  • roles/biglake.user: lets principals use Lakehouse resources, including reading and writing table data.
  • roles/biglake.viewer: lets principals view Lakehouse resources and read table data.

Best practices

  • Least Privilege: grant only the necessary permissions to users and service accounts.
  • Use Etags: always include the etag from a recent get-iam-policy call in your policy file when using set-iam-policy to avoid unintended overwrites.
  • Audit Logging: ensure that Cloud Audit Logs are enabled to track changes to IAM policies.
  • Version Control: store your policy files in a version control system.

Apply ACL roles to tables

The following section shows you how to apply ACLs to tables.

Get the IAM policy

To view the current IAM policy on a Lakehouse Iceberg table, use the gcloud alpha biglake iceberg tables get-iam-policy command.

  1. To get the IAM policy, run the following command:

    gcloud alpha biglake iceberg tables get-iam-policy TABLE_NAME \
    --catalog=CATALOG_NAME \
    --namespace=NAMESPACE_NAME \
    --project=PROJECT_ID

    Replace the following:

    • TABLE_NAME: the name of the target Lakehouse Iceberg table.
    • CATALOG_NAME: the name of the Apache Iceberg REST catalog endpoint.
    • NAMESPACE_NAME: the name of the namespace within the catalog.
    • PROJECT_ID: your Google Cloud project ID.

  2. The command outputs the IAM policy in YAML format, which shows the current role bindings and members.

Set the IAM policy

To update the IAM policy on a Lakehouse Iceberg table, use the gcloud alpha biglake iceberg tables set-iam-policy command. This command uses a local JSON or YAML file that contains the policy you want to apply.

  1. Create a local policy file in JSON or YAML format. The policy file must contain the bindings and an etag. The etag value provides optimistic concurrency control to prevent overwriting changes. To get the current etag, run the get-iam-policy command first.

    The following example shows a policy file named policy.json:

    {
  "bindings": [
    {
      "role": "roles/biglake.viewer",
      "members": [
        "user:test-user@example.com"
      ]
    },
    {
      "role": "roles/biglake.user",
      "members": [
        "user:someone@example.com"
      ]
    }
  ],
  "etag": "BwYXa9UuR8w=",
  "version": 3
}

  2. To set the IAM policy, run the following command:

    gcloud alpha biglake iceberg tables set-iam-policy TABLE_NAME POLICY_FILE \
    --catalog=CATALOG_NAME \
    --namespace=NAMESPACE_NAME \
    --project=PROJECT_ID

    Replace the following:

    • TABLE_NAME: the name of the target Lakehouse Iceberg table.
    • POLICY_FILE: the path to your local policy file.
    • CATALOG_NAME: the name of the Apache Iceberg REST catalog endpoint.
    • NAMESPACE_NAME: the name of the namespace within the catalog.
    • PROJECT_ID: your Google Cloud project ID.

What's next