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 about
Projects
in Google Cloud.
What is a project?
A project organizes all your Google Cloud resources. All data in
Cloud Storage belongs inside a project. 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:
Console
When using Cloud Storage with the Google Cloud console, you're
automatically associated with a project. You can change projects by using
the drop-down menu at the top of the Google 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.
Command line
The following commands use the
project
property
set in your
Google Cloud CLI configuration, unless you use the
global
--project
flag
in the command to specify a different project:
Use the
global
--billing-project
flag
, along with a project
identifier, 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 following 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://storage.googleapis.com/storage/v1/b?project=
PROJECT_IDENTIFIER
To indicate a project to charge for bucket access, use the 'userProject'
query paratemer, along with a project identifier, as in the following
example:
GET https://storage.googleapis.com/storage/v1/b?userProject=
PROJECT_IDENTIFIER
This query parameter is required when accessing a
bucket that has enabled
Requester Pays
and is optional otherwise.
XML API
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:
x-goog-project-id:
PROJECT_ID
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:
x-goog-user-project:
PROJECT_ID
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 user 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
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
:
Service agents
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 Cloud Storage service agent is not initially available when you
make a project. Instead, it is automatically activated the first time it's
accessed, either by one of the features listed above or when you
request the service agent's name
. The service agent must be activated
prior to
assigning permissions
to it.
The following is an example email address for the Cloud Storage service
agent associated with
project number
123456789876
:
service-123456789876@gs-project-accounts.iam.gserviceaccount.com
What's next