Manage Lakehouse Iceberg REST catalog table ACLs

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

The Lakehouse runtime catalog manages the metadata, while Identity and Access Management (IAM) policies define the permissions. You can use the Google Cloud console or the gcloud CLI 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 namespaces and tables, ask your administrator to grant you the following IAM roles:

• All: BigLake Admin (roles/biglake.admin) on for 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

The following list shows some of the common IAM roles that you can apply to Lakehouse resources. For a complete list of available roles and their associated permissions, see Lakehouse IAM roles.

• 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 namespaces

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

The Google Cloud console does not display or manage inherited IAM policies.

Console

1. In the Google Cloud console, open the Lakehouse page.

   Go to Lakehouse

2. Select an existing catalog or create one if you don't have one.

3. In the Namespace details table, select a namespace and expand the menu options ().

4. Click Manage permissions.

   The Share permissions dialog appears.

5. Click Add principal.

6. For the New Principals field, enter the principal account that you want to assign roles to.

7. For Select a role, choose a role to assign to the principal account.

8. Click Save.

9. Click Close.

gcloud

Get the IAM policy

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

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

   gcloud alpha biglake iceberg namespaces get-iam-policy NAMESPACE_NAME \
       --catalog=CATALOG_NAME \
       --project=PROJECT_ID
   

   Replace the following:

   • NAMESPACE_NAME: the name of the target namespace within the catalog.
   • CATALOG_NAME: the name of the Apache Iceberg REST catalog endpoint.
   • 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 namespace, use the gcloud alpha biglake iceberg namespaces 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:[e-mail]"
         ]
       },
       {
         "role": "roles/biglake.user",
         "members": [
           "user:[e-mail]"
         ]
       }
     ],
     "etag": "BwYXa9UuR8w=",
     "version": 3
   }
   

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

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

   Replace the following:

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

Apply ACL roles to tables

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

The Google Cloud console does not display or manage inherited IAM policies.

Console

1. In the Google Cloud console, open the Lakehouse page.

   Go to Lakehouse

2. Select an existing catalog or create one if you don't have one.

3. In the Namespace details table, click the name of the namespace that contains your table.

4. On the Table details page, select a table and expand the menu options ().

5. Click Manage permissions.

   The Share permissions dialog appears.

6. Click Add principal.

7. For the New Principals field, enter the principal account that you want to assign roles to.

8. For Select a role, choose a role to assign to the principal account.

9. Click Save.

10. Click Close.

gcloud

Get the IAM policy

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

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

   gcloud 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 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:[e-mail]"
         ]
       },
       {
         "role": "roles/biglake.user",
         "members": [
           "user:[e-mail]"
         ]
       }
     ],
     "etag": "BwYXa9UuR8w=",
     "version": 3
   }
   

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

   gcloud 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

• Learn more about IAM.
• See the full list of Lakehouse IAM roles and permissions.
• Learn about Lakehouse concepts.