Manage BigLake Iceberg table ACLs

The BigLake Iceberg REST Catalog lets you manage metadata for Iceberg tables that are stored in Cloud Storage. To control access to these tables, you use Identity and Access Management (IAM) policies. This document shows you how to get and set IAM policies at the table level using the gcloud command-line tool.

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 BigLake Iceberg Catalog and Namespace.
  5. Verify that you have an existing Iceberg table within the specified catalog and namespace.

Required roles

To get the permissions that you need to manage Access Control Lists (ACLs) for BigLake Iceberg tables, ask your administrator to grant you the BigLake Admin (roles/biglake.admin) IAM role 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 BigLake resources:

  • roles/biglake.admin: provides full control over BigLake resources.
  • roles/biglake.user: lets principals use BigLake resources, including reading and writing table data.
  • roles/biglake.viewer: lets principals view BigLake 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 an 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 Iceberg table.
    • CATALOG_NAME: the name of the BigLake Iceberg Catalog.
    • 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 an 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 Iceberg table.
    • POLICY_FILE: the path to your local policy file.
    • CATALOG_NAME: the name of the BigLake Iceberg Catalog.
    • NAMESPACE_NAME: the name of the Namespace within the catalog.
    • PROJECT_ID: your Google Cloud project ID.

What's next