Google Cloud projects form the basis for creating,
enabling, and using all Google Cloud services including managing APIs,
enabling billing, adding and removing collaborators, and managing permissions
for Google Cloud resources.
This page explains how to create and manage Google Cloud projects using
the Cloud Resource Manager API and the Google Cloud console.
Before you begin
Read about the project resource in the
Resource hierarchy overview
.
For guidance on setting up your resource hierarchy, see
Decide a resource hierarchy for your Google Cloud landing zone
.
The following are used to identify your project:
Project name
: A human-readable name for your project.
The project name isn't used by any Google APIs. You can edit the project
name at any time during or after project creation. Project names do not need
to be unique.
Project ID
: A globally unique identifier for your project.
A project ID is a unique string used to differentiate your project from all
others in Google Cloud. After you enter a project name, the
Google Cloud console generates a unique project ID that can be a combination
of letters, numbers, and hyphens. We recommend you use the generated project ID,
but you can edit it during project creation. After the project has been created,
the project ID is permanent.
A project ID has the following requirements:
- Must be 6 to 30 characters in length.
- Can only contain lowercase letters, numbers, and hyphens.
- Must start with a letter.
- Cannot end with a hyphen.
- Cannot be in use or previously used; this includes deleted projects.
- Cannot contain restricted strings, such as
google
,
null
,
undefined
, and
ssl
.
Project number
: An automatically generated unique identifier for your
project.
Don't include sensitive information such as personally identifiable information
(PII) or security data in your project name, project ID, or other resource names.
The project ID is used in the name of many other Google Cloud resources, and any
reference to the project or related resources exposes the project ID and resource name.
Creating a project
To create a project, you must have the
resourcemanager.projects.create
permission. This permission is included in roles like the Project Creator role
(
roles/resourcemanager.projectCreator
). The Project Creator role is granted
by default to the entire domain of a new organization resource and to free trial users.
For information on how to grant individuals the role and limit organization-resource
wide access, see the
Managing Default Organization
Roles
page.
If you don't specify the parent resource, a parent resource is selected
automatically if applicable based on the user account's domain.
You can create a new project using the Google Cloud console, the
Google Cloud CLI, or
the
projects.create()
method.
Console
To create a new project, do the following:
-
Go to the
Manage resources
page in the Google Cloud console.
Go to Manage Resources
school
The remaining steps will appear
automatically in the Google Cloud console.
-
On the
Select organization
drop-down list at the top of the page, select the
organization resource in which you want to create a project. If you are a free trial user, skip this
step, as this list does not appear.
- Click
Create Project
.
-
In the
New Project
window that appears, enter a project name and select a
billing account as applicable. A project name can contain only letters, numbers, single
quotes, hyphens, spaces, or exclamation points, and must be between 4 and 30 characters.
-
Enter the parent organization or folder resource in the
Location
box. That resource
will be the hierarchical parent of the new project. If
No organization
is an option,
you can select it to create your new project as the top level of its own resource hierarchy.
- When you're finished entering new project details, click
Create
.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
Activate Cloud Shell
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
To create a new project, use the
gcloud projects create
command:
gcloud projects create
PROJECT_ID
Where
PROJECT_ID
is the ID for the project you want to create.
A project ID must start with a lowercase letter, and can contain only
ASCII letters, digits, and hyphens, and must be between 6 and 30 characters.
To create a project with an organization resource or a folder as parent, use the
--organization
or
--folder
flags. As a resource can only have one
parent, only one of these flags can be used:
gcloud projects create
PROJECT_ID
--organization=
ORGANIZATION_ID
gcloud projects create
PROJECT_ID
--folder=
FOLDER_ID
API
You can't use certain words in the project ID when you create a new project
with the
projects.create()
method. Some examples include
google
,
null
,
undefined
, and
ssl
.
When you use a restricted word, the request returns with
an
INVALID_ARGUMENT
error.
The below request only creates a project, and does not associate it
automatically with a billing account. Use the
projects.updateBillingInfo
method to set or update the billing account associated with a project.
Create Project Request:
POST https://cloudresourcemanager.googleapis.com/v3/projects/
Authorization: *************
Content-Type: application/json
{
"projectId": "our-project-123",
"name": "my project",
"labels": {
"mylabel": "prod"
}
}
Create Project Response:
{
"name": "operations/pc.123456789",
}
Get Operation Request:
GET https://cloudresourcemanager.googleapis.com/v3/operations/pc.123456789
Authorization: *************
Content-Type: application/json
Get Operation Response:
{
"name": "operations/pc.123456789",
"done": true,
"response": {
"@type": "type.googleapis.com/google.cloudresourcemanager.v3.Project",
"projectNumber": "464036093014",
"projectId": "our-project-123",
"lifecycleState": "ACTIVE",
"name": "my project",
"labels": {
"mylabel": "prod"
},
"createTime": "2016-01-07T21:59:43.314Z"
}
}
Tags provide a way to create annotations for resources. You can add tags at the time of creating projects. You
must assign the
Tag User
role while adding tags. For more information on the permissions assigned
to this role, see
Manage tags on resources
.
You can only add the namespace for the tag key-value pairs in one of the following ways:
gcloud
To add tags during project creation, run the following command:
gcloud projects create
PROJECT_ID
--organization=
ORGANIZATION_ID
--tags=
KEY_VALUE_PAIRS
Replace the following:
- PROJECT_ID
is the unique identifier of the project.
- ORGANIZATION_ID
is the unique identifier of the organization.
- KEY_VALUE_PAIRS
is a comma-separated list of key-value pairs that you can assign to your
resource. An example of comma-separated key-value pairs is
123/environment=production, 456/create=testresource
.
API
The following snippet is a JSON request where you create a project and
add tags to it.
POST https://cloudresourcemanager.googleapis.com/v3/projects/
Authorization: *************
Content-Type: application/json
{
"projectId": "our-project-456",
"name": "my project",
"parent": "organizations/123",
"tags": {
"key": "123/environment"
"value": "production"
},
"tags": {
"key": "123/costCenter"
"value": "marketing"
}
}
Creating a project using a service account
You can use a service account to automate project creation. Like user accounts,
service accounts can be granted permission to create projects within an
organization resource. Service accounts are not allowed to create projects outside of an
organization resource and must specify the parent resource when creating a project.
Service accounts can create a new project using the gcloud CLI or the
projects.create()
method.
Managing project quotas
If you have fewer than 30 projects remaining in your quota, a notification
displays the number of projects remaining in your quota on the
New Project
page. Once you have reached your
project limit, to create more projects you must request a project limit
increase. Alternatively, you can schedule some projects to be deleted after 30
days on the
Manage Resources Page
.
Projects that users have
soft deleted
count against your quota. These projects
fully delete after 30 days.
To request additional capacity for projects in your quota, use the
Request Project Quota Increase
form. More information about quotas and why they are used can be found
at the
Free Trial Project Quota Requests
support page. For more information about billing reports, see the
Billing Reports
support page.
Identifying projects
To interact with Google Cloud resources, you must provide the
identifying project information for every request. A project is identified by
its project ID and project number.
To get the project ID and the project number, do the following:
Go to the
Dashboard
page
in the Google Cloud console.
Go to the Dashboard page
Click the
Select from
drop-down list at the top of the page. In the
Select from
window that appears, select your project.
The project ID and project number are displayed on the project Dashboard
Project info
card:
In the above example, the project name is
My Sample Project
and the
project ID is
my-sample-project-191923
.
Get an existing project
You can get an existing project using the Google Cloud console or
the
projects.get()
method.
If you are not a project owner, you must have the permissions included in the
Browser role (
roles/browser
).
Console
To view a project using the Google Cloud console, do the following:
- Go to the
Dashboard
page in the Google Cloud console.
Go to the Dashboard page
- From the project picker at the top of the page, select your project.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
Activate Cloud Shell
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
To get the metadata for a project, use the
gcloud projects describe
command:
gcloud projects describe
PROJECT_ID
Where
PROJECT_ID
is the ID of the project you want to view.
API
Request:
GET https://cloudresourcemanager.googleapis.com/v3/projects/our-project-123
Response:
{
"projectNumber": "464036093014",
"projectId": "our-project-123",
"lifecycleState": "ACTIVE",
"name": "my project",
"labels": {
"mylabel": "prod"
},
"createTime": "2016-01-07T21:59:43.314Z"
}
Listing projects
List all projects under a resource
To list all projects that are direct children of a resource, use the
v3
projects.list
method,
with the parent resource specified in the query:
Request:
GET https://cloudresourcemanager.googleapis.com/v3/projects
{
"parent": "folders/662951040570"
}
Response:
{
"projects": [
{
"name": "projects/951040570662",
"parent": "folders/662951040570",
"projectId": "tokyo-rain-123",
"state": "ACTIVE",
"displayName": "Tokyo Rain"
"createTime": "2013-11-13T20:31:53.308Z"
"updateTime": "2013-11-13T20:31:53.308Z"
"etag": "BwWUlZ6XEfY="
}
]
}
Search for projects
To search for projects matching the specified query, use
gcloud alpha resource-manager
projects search
, passing the query in the
--query
flag. The scope of search
is all the projects for which the user has projects.get permission.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
Activate Cloud Shell
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
To get the list of all projects use
gcloud alpha projects search
command:
gcloud alpha projects search --query="displayName=rek*"
<table output showing the projects with display names starting from rek eg. rekey-project-2, rekha-project>
gcloud alpha projects search --query="state:DELETE_REQUESTED"
<table output showing the projects for which delete has been requested>
API
You can use the
projects.search
method
and a query string to return specific project resources that match the filter.
The results contain only projects for which you have been granted the
resourcemanager.projects.get
permission.
The following code snippet returns the Project resource with the display name
"Tokyo Rain":
Request:
GET https://cloudresourcemanager.googleapis.com/v3/projects:search?query=displayName%3ATokyo%2BRain
Response:
{
"projects": [
{
"name": "projects/951040570662",
"parent": "folders/662951040570",
"projectId": "tokyo-rain-123",
"state": "ACTIVE",
"displayName": "Tokyo Rain",
"createTime": "2013-11-13T20:31:53.308Z",
"updateTime": "2013-11-13T20:31:53.308Z",
"etag": "BwWUlZ6XEfY="
}
]
}
The following code snippet returns all Project resources with a red label:
Request:
GET https://cloudresourcemanager.googleapis.com/v3/projects:search?query=labels.color%3Ared
Response:
{
"projects": [
{
"name": "projects/951054970012",
"parent": "folders/662951040570",
"projectId": "Osaka-rain-234",
"state": "ACTIVE",
"displayName": "Osaka Rain",
"createTime": "2013-11-13T20:31:53.308Z",
"updateTime": "2013-11-13T20:31:53.308Z",
"etag": "BwWUlZ6XEfY=",
"labels": {
"color": "red"
}
}
]
}
If you specify the
parent.type
and
parent.id
fields in your request body, then the
resourcemanager.projects.list
permission is checked on the
parent. If the user has this permission, all projects under the parent are
returned after the remaining filters have been applied.
If the user lacks this permission, then all projects for which
the user has the
resourcemanager.projects.get
permission are
returned after remaining filters have been applied.
If no filter is specified, the call returns projects for which the user
has
resourcemanager.projects.get
permissions.
Updating projects
You can update projects using the Google Cloud console or the
projects.patch()
method.
The only fields that can be updated are the project name and labels.
For more information about updating projects, see the
project API reference page
.
To move a project within your resource hierarchy, see
Moving a project
. To migrate a project from one
organization resource to another, see
Migrating projects
.
Console
To update a project's name or labels using the Google Cloud console, do
the following:
- In the Google Cloud console, go to the IAM & Admin
Settings
page.
Go to IAM & Admin Settings
school
The remaining steps will appear
automatically in the Google Cloud console.
- At the top of the screen, click the project selection drop-down list.
- On the
Select from
window that appears, click the organization
drop-down list and then select your organization. If you are a free trial
user, skip this step, as the organization list does not appear.
- Select your project from the list that appears.
- To change the project name, edit
Project name
, then click
Save
.
- To change labels, click
Labels
on the left nav.
Learn more about
Using Labels
.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
Activate Cloud Shell
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
To update a project's name or labels, use the
gcloud alpha projects update
command:
gcloud alpha projects update
PROJECT_ID
\
--name=
NAME
\
--update-labels=
KEY
=
VALUE
, ...
Where:
PROJECT_ID
is the ID of the project you want to update.
NAME
is the new name you want to assign to the project.
KEY
=
VALUE
, ... is a list of the key=value pairs of
labels you want to update. If a label already exists, its value is
modified. If it does not exist, a new label is created.
For more information and additional flags that can be used with this
command, see the
Google Cloud CLI SDK
.
API
To update a project, do the following:
The following example updates the display name of the project to
myproject
and sets the
color
label to
red
:
Request:
PATCH https://cloudresourcemanager.googleapis.com/v3/projects/
PROJECT_NUMBER
?updateMask=displayName,labels
Where
PROJECT_NUMBER
is the numeric ID of the project you want
to update.
Request JSON body:
{
"displayName": "myproject",
"labels": {
"color": "red"
}
}
Response:
{
"projects": [
{
"name": "projects/951054970012",
"parent": "folders/662951040570",
"projectId": "Osaka-rain-234",
"state": "ACTIVE",
"displayName": "myproject",
"createTime": "2013-11-13T20:31:53.308Z",
"updateTime": "2013-11-13T20:35:42.308Z",
"etag": "BwWUlZ6XEfY=",
"labels": {
"color": "red"
}
}
]
}
Shutting down (deleting) projects
You can shut down projects using the Google Cloud console or the
projects.delete
method in the API. A project must have a lifecycle state of
ACTIVE
to be shut
down in this way.
This method immediately marks a project to be deleted. A notification email is sent to the user who initiated the delete operation and the Technical
category contacts that are listed in
Essential Contacts
on a best effort basis; if the notification fails to send, the project is still marked to be deleted. If there's no contact in the Technical category, the fallback contact isn't notified.
A project that is marked for deletion isn't usable. If the project
has a billing account associated with it, that association is broken and isn't
reinstated if the project delete operation is canceled. After 30 days, the
project is fully deleted. Until it is fully deleted, the project might still be
visible, although it isn't usable.
To stop the project delete process during the 30-day period, see the
steps to restore a project
.
At the end of the 30-day period, the project and all of its resources
are deleted and cannot be recovered. Until it is deleted, the project counts
towards your project quota.
To help ensure that you don't delete any important projects, you can enable
change risk recommendations
. Change risk
recommendations generate warnings when you try to delete projects that Google Cloud has
identified as important.
If you have set up billing for a project, it might not be completely deleted
until the current billing cycle ends and your account is successfully charged.
The number and types of services in use can also affect when the system
permanently deletes a project. To learn more about data retention and safe
deletion, see
How Google retains data we collect
.
To shut down a project:
Console
-
In the Google Cloud console, go to the IAM & Admin
Settings
page.
Go to IAM & Admin Settings
school
The remaining steps will appear
automatically in the Google Cloud console.
-
On the
IAM & Admin Settings
page, select the project you want to delete, and then
click
Shut down
.
Shut down
only appears for users who have the
resourcemanager.projects.delete
permission in the current project.
- Click
Shut down
.
- Enter the project ID, and then click
Shut down anyway
.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
Activate Cloud Shell
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
To delete a project, use the
gcloud projects delete
command:
gcloud projects delete
PROJECT_ID
Where
PROJECT_ID
is the ID of the project you want to delete.
API
The following code snippet deletes the specified project:
Request:
DELETE https://cloudresourcemanager.googleapis.com/v3/projects/my-project-123
Troubleshooting project deletion
If the process to shut down a project fails, you can find more information at
Troubleshooting project deletion
.
Restoring a project
Project owners can restore a deleted project within the 30-day recovery period
that starts when the project is shut down. Restoring a project returns it to
the state it was in before it was shut down, with certain exceptions:
- Billing is disabled on the project when the
project is shut down
and billing is
not
automatically enabled on restored projects. The
Cloud Billing account must be manually linked
again after the project is restored. You might need to wait a few hours
before you can successfully link a recently restored project to a billing
account.
- You can recover most resources if you restore a project within the 30-day
period. Some services have delays in restoring and you might need to wait
some time for services to be restored.
- Some resources, such as Cloud Storage or Pub/Sub resources, are deleted
much sooner. These resources might not be fully recoverable even if you
restore the project within the 30-day period.
- Some services might need to be restarted manually. For more information, see
Restarting Google Cloud Services
.
You must have the
resourcemanager.projects.undelete
permission on the project
you want to restore. To restore a project:
Console
To view the project in the Google Cloud console, you need the following
permissions:
resourcemanager.projects.list
resourcemanager.folders.list
resourcemanager.projects.get
To restore a project using the Google Cloud console:
Go to the
Manage resources
page in the Google Cloud console.
Go to the Manage Resources page
In the
Project picker
at the top of the page, select your
organization resource.
Below the list of organization resources, folders, and projects, click
Resources pending deletion
.
Check the box for the project you want to restore, then click
Restore
. In the dialog that appears, confirm that you want to restore
the project.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
Activate Cloud Shell
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
To restore a project, use the
gcloud projects undelete
command:
gcloud projects undelete
PROJECT_ID
Where
PROJECT_ID
is the project ID or project number of the
project you want to restore.
API
The following code snippet restores the specified project:
Request:
POST https://cloudresourcemanager.googleapis.com/v3/projects/my-project-123:undelete