Projects

This page describes the relationship between Google Cloud Platform Console projects and Cloud Storage resources. To learn more about Google Cloud Platform Console projects in general, read Projects in the Overview of Google Cloud Platform.

What is a project?

A project organizes all your Google Cloud Platform resources. A project consists of a set of users; a set of APIs; and billing, authentication, and monitoring settings for those APIs. So, for example, all of your Google Cloud Storage buckets and objects, along with user permissions for accessing them, reside in a project. You can have one project, or you can create multiple projects and use them to organize your Google Cloud Platform resources, including your Google Cloud Storage data, into logical groups.

When to specify a project

Most of the time, you do not need to specify a project when performing actions in Cloud Storage; however you should include either the project ID or the project number in the following cases:

Console

  • When using Cloud Storage with the Cloud Platform Console, you're automatically associated with a project. You can change projects by using the drop-down menu at the top of the Cloud Platform Console window.

  • When first accessing a bucket that has enabled Requester Pays, you're prompted to select a project to bill requests to. You can subsequently change the billing project by using the Change project button located above the list of objects in the bucket.

gsutil

  • The gsutil mb and gsutil ls commands require you to specify a project, unless you have set a default project. If you have not set a default project, or if you would like to use a different project, use the -p flag to specify a project. No other gsutil commands require you to specify a project.

  • Use the -u flag, along with a project ID, to indicate the project to charge for bucket access. This is required when accessing a bucket that has enabled Requester Pays and is optional otherwise.

JSON API

  • The list buckets and insert bucket methods require you to specify a project. The project is sent as a parameter in the request URL, as in the following example:

    GET https://www.googleapis.com/storage/v1/b?project=[PROJECT_ID]

  • To indicate a project to charge for bucket access, use the 'userProject' query paratemer, along with a project ID, as in the following example:

    GET https://www.googleapis.com/storage/v1/b?userProject=[PROJECT_ID]

    This query parameter is required when accessing a bucket that has enabled Requester Pays and is optional otherwise.

XML API

  • Specify a project when listing buckets and inserting buckets. The project associated with these XML API requests is specified in the x-goog-project-id HTTP header, as in the following example:

    x-goog-project-id: [PROJECT_ID]

    The header is optional for other XML API requests or if you have set a default project for interoperable access.

  • To indicate a project to charge for bucket access, use the 'x-goog-user-project' header, along with a project ID, as in the following example:

    x-goog-user-project: [PROJECT_ID]

    This header is required when accessing a bucket that has enabled Requester Pays and is optional otherwise.

Project members and permissions

For each project, you can use Identity and Access Management (IAM) to add team members who can manage and work on your project. IAM allows you to specify each team member's role or roles: different roles have permissions that allow a member to do different things within your project.

While many IAM roles can be set at both the project-level (thus applying to all buckets in the project) or the bucket-level (thus applying only to an individual bucket), there are several roles that you can only apply to a project. These roles are primitive roles. Primitive roles have the following properities for Cloud Storage and the Cloud Storage Transfer Service:

Cloud Storage

RoleIntrinsic BehaviorModifiable Behavior
roles/viewerMembers with this role can list buckets in the project.Members with this role have, as a group, the roles/storage.legacyBucketViewer role for buckets in the project and READER in the default object Access Control List associated with each bucket in the project.
roles/editorMembers with this role can list, create and delete buckets in the project.Members with this role have, as a group, the roles/storage.legacyBucketOwner role for buckets in the project and OWNER in the default object Access Control List associated with each bucket in the project.
roles/ownerMembers with this role can list, create and delete buckets in the project. Within Google Cloud Platform more generally, members with roles/owner can perform administrative tasks such as changing members' roles for the project or changing billing.Members with this role have, as a group, the roles/storage.legacyBucketOwner role for buckets in the project and OWNER in the default object Access Control List associated with each bucket in the project.

Transfer Service

RoleIntrinsic Behavior
roles/viewerMembers with this role can get and list transfer jobs and transfer operations in the project.
roles/editorMembers with this role can perform all Storage Transfer Service operations.
roles/ownerMembers with this role can perform all Storage Transfer Service operations.

For a list of available roles that apply to Cloud Storage, see Cloud Storage IAM roles.

For instructions for adding, viewing, and removing members from roles at the project level, see Using IAM with projects.

As illustrated in the Modifiable Behavior column above, project team members may have additional access beyond that granted intrinsically by the primitive IAM roles. This additional access comes from two sources:

  • IAM roles applied to buckets: When a user creates a bucket, IAM roles are applied to it by default. You can edit this access once the bucket is created.

  • Access Control Lists (ACLs) applied to objects: When a user creates an object, an ACL is applied to it. The ACL can either be specified explicitly or applied by default. In either case, the ACL grants access specifically to the created object.

Note that in both cases, you can grant access to both individual users and all holders of a primitive role. Moreover, the access granted may be greater than the access that a user has in general for project, but not more restricted.

What's next?

Send feedback about...

Cloud Storage Documentation