This page describes the relationship between Google Cloud Console projects and Cloud Storage resources. To learn more about Google Cloud Console projects in general, read Projects in the Overview of Google Cloud.
What is a project?
A project organizes all your Google Cloud 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 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 resources, including your 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:
When using Cloud Storage with the Cloud Console, you're automatically associated with a project. You can change projects by using the drop-down menu at the top of the Cloud 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.
The following commands require you to specify a project, unless you have have set a default project:
gsutil ls(when listing buckets)
gsutil kms(when using the
If you have not set a default project, or if you would like to use a
different project, use the
-p flag when using these commands.
The Cloud Storage Client Libraries require a project to be specified under the same circumstances as the JSON API.
The following methods require you to specify a project:
- List buckets
- Insert bucket
- Get project service agent
- All methods associated with the HMAC key resource
The project is sent as a parameter in the request URL, as in the following example:
To indicate a project to charge for bucket access, use the 'userProject' query paratemer, along with a project identifier, as in the following example:
This query parameter is required when accessing a bucket that has enabled Requester Pays and is optional otherwise.
The following requests require you to specify a project, unless you have set a default project for interoperable access:
The project associated with these XML API requests is specified in the
x-goog-project-id HTTP header, as in the following example:
The header is optional for other XML API requests.
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:
This header is required when accessing a bucket that has enabled Requester Pays and is optional otherwise.
Projects and permissions
For each project, you use Identity and Access Management (IAM) to grant the ability to manage and work on your project. When you grant an IAM role to a principal, such as a Google Account, that principal obtains certain permissions that allow them to perform actions. When you grant a role at the project level, the access provided by the role applies to every bucket and object within the project. Alternatively, when you grant a role for an individual bucket, the access provided by the role is limited to just that bucket and the objects the bucket contains.
For a list of available roles that apply to Cloud Storage, as well as a discussion about how a special set of roles, called basic roles, apply to Cloud Storage, see Cloud Storage IAM roles.
For instructions for viewing, granting, and revoking a principal's roles at the bucket and project level, see Using IAM with projects.
Service accounts allow applications to authenticate and access Google Cloud resources and services. For example, you can create a service account that your Compute Engine instances use to access objects stored in Cloud Storage buckets. Service accounts are created within a project and have a unique email address that identifies them.
The following are examples of actions related to Cloud Storage that are often taken by service accounts that you create and manage:
- Performing Storage Transfer Service transfers.
- Moving data to/from Cloud SQL instances.
- Creating signed URLs.
A service agent is a special type of service account that acts on behalf of a Google Cloud service. Cloud Storage uses a service agent for the following features:
The service agent for Cloud Storage has an email address with the following format:
PROJECT_NUMBER is the project number of
the project that owns the service account.
- Complete the Cloud Console quickstart and gsutil quickstart.
- Learn how to create a new project and manage existing projects.
- Learn about key terms for working with Cloud Storage.
- Find out how to use the Cloud Console to manage your data.
- Manage your project's service accounts.