Creating and managing projects

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.

Create 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:

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

    Go to Manage Resources

    The remaining steps appear in the Google Cloud console.

  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

  1. 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.

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

Add tags during project creation

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. After 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.

Find the project name, number, and ID

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.

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

    Go to Welcome

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

    The project name, project number, and project ID appear after the Welcome heading.

Get an existing project

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

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

gcloud

  1. 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.

  2. To get the metadata for a project, use the gcloud projects describe command:

    gcloud projects describe PROJECT_ID

    Replace PROJECT_ID with the ID of the project.

API

Request:

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

Replace PROJECT_ID with the ID of the project.

Response:

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

  1. 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.

  2. 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:

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

    Go to IAM & Admin Settings

    The remaining steps appear in the Google Cloud console.

  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 about Using Labels.

gcloud

  1. 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.

  2. 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.

Shut down a project

Console

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

    Go to IAM & Admin Settings

    The remaining steps appear in the Google Cloud console.

  2. 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.

  3. Click Shut down.
  4. Enter the project ID, and then click Shut down anyway.

gcloud

  1. 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.

  2. 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.

Restore 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 (up to 36 hours) 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

  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 your organization resource.

  3. Below the list of organization resources, folders, and projects, click Resources pending deletion.

  4. 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

  1. 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.

  2. To restore a project, use the gcloud projects undelete command:

    gcloud projects undelete PROJECT_ID

    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