Manage Lakehouse Iceberg REST catalog table ACLs

Within Google Cloud Lakehouse, the Lakehouse runtime catalog lets you manage metadata for Lakehouse Iceberg REST catalog tables 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 CLI.

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 Google Cloud 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 Google Cloud Lakehouse 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 Google Cloud Lakehouse resources:

  • roles/biglake.admin: provides full control over Google Cloud Lakehouse resources.
  • roles/biglake.user: lets principals use Google Cloud Lakehouse resources, including reading and writing table data.
  • roles/biglake.viewer: lets principals view Google Cloud 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 Google Cloud 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 Google Cloud 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 Google Cloud 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 Google Cloud 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