Creating and managing projects  |  Resource Manager Documentation  |  Google Cloud (2023)

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 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. You can use the Google Cloud console to generatea project ID, or you can choose your own. You can only modify the projectID when you're creating the project.

    Project ID 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 and ssl.
  • Project number: An automatically generated unique identifier for yourproject.

Don't include sensitive information in your project name, project ID, orother resource names. The project ID is used in the name of many otherGoogle Cloud resources, and any reference to the project or related resourcesexposes the project ID and resource name.

Creating a project

To create a project, you must have the resourcemanager.projects.createpermission. This permission is included in roles like the Project Creator role(roles/resourcemanager.projectCreator). The Project Creator role is grantedby default to the entire domain of a new organization and to free trial users.For information on how to grant individuals the role and limit organization-wide access, see the Managing Default OrganizationRoles page.

If you do not 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, orthe projects.create()method.

Console

To create a new project, do the following:

  1. Go to the Manage resources page in the Google Cloud console.

    Go to the Manage Resources page

  2. 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.
  3. Click Create Project.
  4. 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.
  5. 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.
  6. When you're finished entering new project details, click Create.

gcloud

To create a new project, use thegcloud 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 onlyASCII letters, digits, and hyphens, and must be between 6 and 30 characters.

To create a project with an organization or a folder as parent, use the--organization or --folder flags. As a resource can only have oneparent, only one of these flags can be used:

gcloud projects create PROJECT_ID --organization=ORGANIZATION_IDgcloud projects create PROJECT_ID --folder=FOLDER_ID

API

You can't use certain words in the project ID when you create a new projectwith the projects.create() method. Some examples include ssl andgoogle. When you use a restricted word, the request returns withan INVALID_ARGUMENT error.

The below request only creates a project, and does not associate itautomatically with a billing account. Use theprojects.updateBillingInfomethod 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.123456789Authorization: *************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" }}

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. Service accounts are not allowed to create projects outside of anorganization 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. Once 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 projectsfully delete after 30 days.

To request additional capacity for projects in your quota, use theRequest Project Quota Increaseform. More information about quotas and why they are used can be foundat theFree Trial Project Quota Requestssupport page. For more information about billing reports, see theBilling Reports support page.

Identifying projects

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.

To get the project ID and the project number, do the following:

  1. Go to the Dashboard pagein the Google Cloud console.

    Go to the Dashboard page

  2. Click the Select from drop-down list at the top of the page. In theSelect from window that appears, select your project.

The project ID and project number are displayed on the project DashboardProject info card:

Creating and managing projects | Resource Manager Documentation | Google Cloud (1)

In the above example, the project name is My Sample Project and theproject ID is my-sample-project-191923.

Get an existing project

You can get an existing project using the Google Cloud console orthe projects.get()method.

Console

To view a project using the Google Cloud console, do the following:

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

    Go to the Dashboard page

  2. Click the Select from drop-down list at the top of the page. In theSelect from window that appears, select your project.

gcloud

To get the metadata for a project, use thegcloud projects describecommand:

gcloud projects describe PROJECT_ID

Where PROJECT_ID is the ID of the project you want to view.

API

Request:

GEThttps://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 thev3 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-managerprojects search, passing the query in the --query flag. The scope of searchis all the projects for which the user has projects.get permission.

gcloud

To get the list of all projects usegcloud alpha projects searchcommand:

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 theprojects.search methodand a query string to return specific project resources that match the filter.The results contain only projects for which you have been granted theresourcemanager.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.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 the resourcemanager.projects.get permission arereturned after remaining filters have been applied.

If no filter is specified, the call returns projects for which the userhas resourcemanager.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 to another, see Migrating projects.

Console

To update a project's name or labels using the Google Cloud console, dothe following:

  1. Open the Settings page in the Google Cloud console.

    Open the Settings page

  2. At the top of the screen, click the project selection drop-down list.
  3. 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.
  4. Select your project from the list that appears.
  5. To change the project name, edit Project name, then click Save.
  6. To change labels, click Labels on the left nav. Learn more aboutUsing Labels.

gcloud

To update a project's name or labels, use thegcloud alpha projects updatecommand:

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 oflabels you want to update. If a label already exists, its value ismodified. If it does not exist, a new label is created.

For more information and additional flags that can be used with thiscommand, see theGoogle Cloud CLI SDK.

API

To update a project, do the following:

  • Get the project object using theprojects.getmethod.

  • Modify the fields you want to update.

  • Call theprojects.patchmethod.

The following example updates the display name of the project tomyproject 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 wantto 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 theprojects.deletemethod in the API. A project must have a lifecycle state of ACTIVE to be shutdown in this way.

This method immediately marks a project to be deleted. A notification email issent to the user who initiated the delete operation and the Technicalcategory contacts that are listed inEssential Contacts ona best effort basis; if the notification fails to send, the project is stillmarked to be deleted. If there's no contact in the Technical category, thefallback contact isn't notified.

A project that is marked for deletion is not 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.

To stop the project delete process during the 30-day period, see thesteps to restore a project. You can verify the numberof days left in the 30-day period by using thegcloud projects describeGoogle Cloud CLI method.

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.

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, see How Google retains data we collect.

To shut down a project:

Console

  1. In the Google Cloud console, go to the IAM & Admin Settings page.

    Open the Settings page

  2. On the IAM & Admin Settings page, click Select a project.
  3. Select the project you want to delete, and click Open.
  4. Click Shut down.
  5. Enter the project ID, then click Shut down.

gcloud

To delete a project, use thegcloud 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:

DELETEhttps://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.

Restoring a project

Project owners can restore a deleted project within the 30-day recovery periodthat starts when the project is shut down. Restoring a project returns it tothe state it was in before it was shut down, with certain exceptions:

  • Billing is disabled on the project when theproject is shut downand billing is not 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. Some services have delays in restoring and you might need to waitsome time for services to be restored.
  • 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 the resourcemanager.projects.undelete permission on the projectyou wish to restore. To restore a project:

Console

To view the project in the Google Cloud console, you need the followingpermissions:

  • resourcemanager.projects.list
  • resourcemanager.folders.list
  • resourcemanager.projects.get

To restore a project using the Google Cloud console:

  1. Go to the Manage resources page in the Google Cloud console.

    Go to the Manage Resources page

  2. In the Project picker at the top of the page, select yourorganization.

  3. Below the list of organizations, folders, and projects, clickResources pending deletion.

  4. Check the box for the project you want to restore, then clickRestore. In the dialog that appears, confirm that you want to restorethe project.

gcloud

To restore a project, use thegcloud projects undeletecommand:

gcloud projects undelete PROJECT_ID

Where PROJECT_ID is the project ID or project number of theproject you want to restore.

API

The following code snippet restores the specified project:

Request:

POSThttps://cloudresourcemanager.googleapis.com/v3/projects/my-project-123:undelete
Top Articles
Latest Posts
Article information

Author: Sen. Emmett Berge

Last Updated: 01/26/2023

Views: 5545

Rating: 5 / 5 (80 voted)

Reviews: 95% of readers found this page helpful

Author information

Name: Sen. Emmett Berge

Birthday: 1993-06-17

Address: 787 Elvis Divide, Port Brice, OH 24507-6802

Phone: +9779049645255

Job: Senior Healthcare Specialist

Hobby: Cycling, Model building, Kitesurfing, Origami, Lapidary, Dance, Basketball

Introduction: My name is Sen. Emmett Berge, I am a funny, vast, charming, courageous, enthusiastic, jolly, famous person who loves writing and wants to share my knowledge and understanding with you.