Get a bucket's storage layout

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

This page describes how to determine the storage layout of your bucket. Storagelayout refers to how objects are organized within a bucket, either in a flatnamespace or ahierarchical namespace. The layout is important forapplications that interact with the bucket, as object access and manipulationmethods vary depending on the layout. Storage layout also includes informationabout the bucket's location.

By using thegetStorageLayout API, your application can adapt itsbehavior based on whether a bucket uses hierarchical namespace or not, ensuringoptimal compatibility and leveraging the appropriate features based on thebucket configuration.

Roles required

In order to get the required permissions for getting the storage layout of a Cloud Storage bucket , ask your administrator to grant you the Storage Object User (roles/storage.objectUser) role on the bucket.

The role contains thestorage.objects.list permission, which isrequired to get the storage layout of the bucket.

You might also be able to get this permission with othercustom roles orpredefined roles. To see which roles are associated with which permissions, refer toIAM roles for Cloud Storage.

For instructions on granting roles on buckets, seeUse IAM with buckets.

Get a bucket's storage layout

Command line

Use thegcloud alpha storage buckets describe command with the--format flag:

gcloud alpha storage buckets describe gs://BUCKET_NAME --raw --format="default(hierarchicalNamespace)"

Where:

  • BUCKET_NAME is the name of the relevant bucket. Forexample,my-bucket.

If successful and hierarchical namespace is enabled, the response lookssimilar to the following example:

  hierarchicalNamespace:    enabled: true

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call theJSON APIwith agetStorageLayout request:

    curl -X GET \  -H "Authorization: Bearer $(gcloud auth print-access-token)" \  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/storageLayout"

    WhereBUCKET_NAME is the name of the relevant bucket. For example,my-bucket.

    If successful, the response looks like the following example:

    {"kind":"storage#storageLayout","bucket":"my-bucket","location":"us-central1","locationType":"region","hierarchicalNamespace":{enabled:true},}

What's next

Try it for yourself

If you're new to Google Cloud, create an account to evaluate how Cloud Storage performs in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Try Cloud Storage free

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-17 UTC.