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 permissionsfor Google Cloud resources.

This page explains how to create and manage Google Cloud projects usingthe Cloud Resource Manager API and the Google Cloud console.

Before you begin

Read about the project resource in theResource hierarchy overview.For guidance on setting up your resource hierarchy, seeDecide 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 projectname at any time during or after project creation. Project names do not needto be unique.

• Project ID: A globally unique identifier for your project.

  A project ID is a unique string used to differentiate your project from allothers in Google Cloud. After you enter a project name, theGoogle Cloud console generates a unique project ID that can be a combinationof 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 asgoogle andssl. Werecommend not using stringsundefined andnull in a project ID.

• Project number: An automatically generated unique identifier for yourproject.

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 anyreference to the project or related resources exposes the project ID and resource name.

Create a project

To create a project, you must have theresourcemanager.projects.createpermission. 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 neworganization resource and to free trial users.

For information on how to grant individuals the role and limit organization-resourcewide access, see theManaging Default OrganizationRoles page.

If you don't specify the parent resource, a parent resource is selectedautomatically if applicable based on the user account's domain.

You can create a new project using the Google Cloud console, theGoogle Cloud CLI, ortheprojects.create()method.

POST https://cloudresourcemanager.googleapis.com/v3/projects/Authorization: *************Content-Type: application/json{    "projectId": "our-project-123",    "name": "my project",    "labels": {      "mylabel": "prod"    }}

{    "name": "operations/pc.123456789",}

GET https://cloudresourcemanager.googleapis.com/v3/operations/pc.123456789Authorization: *************Content-Type: application/json

{"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"}}

Add tags during project creation

Preview

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

Tags provide a way to create annotations for resources. You can add tags at the time of creating projects. You must assign theTag User role while adding tags. For more information on the permissions assigned to this role, seeManage tags on resources. You can only add the namespace for the tag key-value pairs in one of the following ways:

gcloud projects createPROJECT_ID --organization=ORGANIZATION_ID --tags=KEY_VALUE_PAIRS

  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"  }}

Designate project environments with tags

You can use tags to visually distinguish projects based on their environment,such as production, staging, or development. This helps prevent errors andimproves awareness when you are working in sensitive environments. Google adds avisual indicator to the project in the Google Cloud console project pickerwhen a project with a specific tag key-value pair is selected. This indicatorreminds you that any changes could affect your associated production or non-productionapplications. Tags can either be inherited by the project or set directly on theproject.

1. Create a tag key namedenvironment.
2. Create tag values for the environment categories you use. The following valuesare supported and are mapped to a corresponding badge in the console's project picker:
   • Prod: Prod, prod, Production, production
   • Dev: Dev, dev, Development, development
   • Test: Test, test, Testing, testing, QA, qa, Quality assurance, quality assurance
   • Staging: Staging, staging, Stage, stage
3. Attach the appropriate tag to your project bycreating a tag binding.

If a project has multiple environment tags (for example, one inherited from afolder and one directly on the project), the most specific tag is used todetermine the badge.

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 anorganization resource. Service accounts are not allowed to create projects outside of anorganization resource and must specify the parent resource when creating a project.Service accounts can create a new project using the gcloud CLI or theprojects.create() method.

Managing project quotas

If you have fewer than 30 projects remaining in your quota, a notificationdisplays the number of projects remaining in your quota on theNew Project page. After you have reached yourproject limit, to create more projects you must request a project limitincrease. Alternatively, you can schedule some projects to be deleted after 30days on theManage Resources page.Projects that users havesoft-deleted count against your quota. These projectsare fully deleted after 30 days.

To request additional capacity for projects in your organization quota,do the following:

1. Go to theQuotas & System Limits page.

   Go to Quotas & System Limits

2. From the resource selector, select the organization for which you want toincrease the project quota.

3. In theFilter option, selectMetric and entercloudresourcemanager.googleapis.com/projects_count.

4. SelectCloud Resource Manager API, clickmore_vertMore actions,and then selecteditEdit quota.

5. In theQuota changes dialog, enter a new quota value and a description,and then clickNext.

6. Enter your contact details and clickSubmit request.

You receive an email acknowledging receiptof your request. If you need further assistance, respond to the email. Afterthe review, you receive an email notification indicating whetheryour request was approved.

If you don't have an organization and want to request additional capacity forprojects in your quota, then use theRequest Project Quota Increaseform.

For more information about quotas and why they are used, see theFree Trial Project Quota Requestssupport page. For more information about billing reports, see theBilling Reports support page.

Find the project name, number, and ID

To interact with Google Cloud resources, you must provide theidentifying project information for every request. A project is identified byits project ID and project number.

1. Go to theWelcome page in the Google Cloud console.

   Go to Welcome

2. From the project picker at the top of the page, select your project.

   Note: Up to 4000 resources can be displayed in the project picker. If you don't see a resource that should appear, go to theManage resources page and filter the list using the name of that resource.

   The project name, project number, and project ID appear after theWelcome heading.

Get an existing project

You can get an existing project using the Google Cloud CLI ortheprojects.get()method.

If you are not a project owner, you must have the permissions included in theBrowser role (roles/browser).

GEThttps://cloudresourcemanager.googleapis.com/v3/projects/<var>PROJECT_ID</var>

{    "projectNumber": "464036093014",    "projectId": "our-project-123",    "lifecycleState": "ACTIVE",    "name": "my project",    "labels": {        "mylabel": "prod"    },    "createTime": "2016-01-07T21:59:43.314Z"}

List all projects under a resource

To list all projects that are direct children of a resource, use one of thefollowing methods:

GET https://cloudresourcemanager.googleapis.com/v3/projects{    "parent": "folders/662951040570"}

{  "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, usegcloud alpha resource-managerprojects search, passing the query in the--query flag. The scope of searchis all the projects for which the user has projects.get permission.

GET https://cloudresourcemanager.googleapis.com/v3/projects:search?query=displayName%3ATokyo%2BRain

{"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="}]}

GET https://cloudresourcemanager.googleapis.com/v3/projects:search?query=labels.color%3Ared

{"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 theparent.type andparent.idfields in your request body, then theresourcemanager.projects.list permission is checked on theparent. If the user has this permission, all projects under the parent arereturned after the remaining filters have been applied.

If the user lacks this permission, then all projects for whichthe user has theresourcemanager.projects.get permission arereturned after remaining filters have been applied.

If no filter is specified, the call returns projects for which the userhasresourcemanager.projects.get permissions.

Updating projects

You can update projects using the Google Cloud console or theprojects.patch()method.

The only fields that can be updated are the project name and labels.For more information about updating projects, see theproject API reference page.

To move a project within your resource hierarchy, seeMoving a project. To migrate a project from oneorganization resource to another, seeMigrating projects.

PATCH https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_NUMBER?updateMask=displayName,labels

{"displayName":"myproject","labels":{"color":"red"}}

{  "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 theprojects.deletemethod in the API. A project must have a lifecycle state ofACTIVE to be shutdown 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 Technicalcategory contacts that are listed inEssential 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 projecthas a billing account associated with it, that association is broken and isn'treinstated if the project delete operation is canceled. After 30 days, theproject is fully deleted. Until it is fully deleted, the project might still bevisible, although it isn't usable.

To stop the project delete process during the 30-day period, see thesteps to restore a project.

At the end of the 30-day period, the project and all of its resourcesare deleted and cannot be recovered. Until it is deleted, the project countstowards your project quota.

To help ensure that you don't delete any important projects, you can enablechange risk recommendations. Change riskrecommendations generate warnings when you try to delete projects that Google Cloud hasidentified as important.

If you have set up billing for a project, it might not be completely deleteduntil the current billing cycle ends and your account is successfully charged.The number and types of services in use can also affect when the systempermanently deletes a project. To learn more about data retention and safedeletion, seeHow Google retains data we collect.

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 atTroubleshooting project deletion.

Restore a project

Project owners can restore a deleted project within the 30-day recovery periodthat starts when the project is shut down.

Considerations

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 theproject is shut downand billing isnot automatically enabled on restored projects. TheCloud Billing account must be manually linkedagain after the project is restored. You might need to wait a few hoursbefore you can successfully link a recently restored project to a billingaccount.

• You can recover most resources if you restore a project within the 30-dayperiod.

• It can take up to 36 hours for some services to be restored. If yourresources aren't restored after this period, reach out toGoogle support.

• Some resources, such as Cloud Storage or Pub/Sub resources, are deletedmuch sooner. These resources might not be fully recoverable even if yourestore the project within the 30-day period.

• Some services might need to be restarted manually. For more information, seeRestarting Google Cloud Services.

You must have theresourcemanager.projects.undelete permission on the projectyou want to restore. To restore a project:

POST https://cloudresourcemanager.googleapis.com/v3/projects/my-project-123:undelete