Creating and Managing Projects

Google Cloud Platform (GCP) projects form the basis for creating, enabling, and using all GCP services including managing APIs, enabling billing, adding and removing collaborators, and managing permissions for GCP resources.

This page explains how to create and manage GCP projects using the Resource Manager API and the Google Cloud Platform Console.

Before you begin

Read about the project resource in the Resource Hierarchy overview.

Creating a project

To create a project, you must have the resourcemanager.projects.create permission. When an organization is created, the entire domain has the Project Creator role, which includes that permission. For information on how to grant individuals the Project Creator role and limit organization-wide access, see the Managing Default Organization Roles page.

You can create a new project using the GCP Console or the projects.create() method.

Console

To create a new project:

  1. Go to the Manage resources page in the GCP Console.
    GO TO THE MANAGE RESOURCES PAGE
  2. On the Select organization drop-down list at the top of the page, select the organization in which you want to create a project.
  3. Click Create Project.
  4. In the New Project window that appears, enter a project name and select a billing account as applicable.
  5. If you want to add the project to a folder, enter the folder name in the Location box.
  6. When you're finished entering new project details, click Create.

gcloud

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 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 ssl and google. When you use a restricted word, the request will return 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/v1/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/v1/operations/pc.123456789
Authorization: *************
Content-Type: application/json

Get Operation Response:

{
    "name": "operations/pc.123456789",
    "done": true,
    "response": {
        "@type": "type.googleapis.com/google.cloudresourcemanager.v1.Project",
        "projectNumber": "464036093014",
        "projectId": "our-project-123",
        "lifecycleState": "ACTIVE",
        "name": "my project",
        "labels": {
        "mylabel": "prod"
        },
    "createTime": "2016-01-07T21:59:43.314Z"
    }
}

PYTHON

...
crm = discovery.build(
    'cloudresourcemanager', 'v1', http=creds.authorize(httplib2.Http()))

operation = crm.projects().create(
body={
    'project_id': flags.projectId,
    'name': 'my project'
}).execute()

...

Managing project quotas

If you have fewer than 30 projects remaining in your quota, a notification will display the number of projects remaining in your quota on the New Project page. Projects that users have soft deleted will count against your quota until those projects have been fully deleted after 30 days.

To request additional capacity for projects in your quota, see the Request Billing Quota Increase support page. More information about quotas and why they are used can be found at the Free Trial Project Quota Requests support page.

Identifying projects

To interact with GCP resources, you must provide the identifying project information for every request. A project can be identified in the following ways:

  • Project ID: the customized name you chose when you created the project, or when you activated an API that required you to create a project ID. Note that you can't reuse the project ID of a deleted project.
  • Project number: a number that's automatically generated by the server and assigned to your project.

To get the project ID and the project number:

  1. Go to the Manage resources page in the GCP Console.
  2. Select your project.

Both the project ID and project number are displayed on the project Dashboard Project info card:

A project ID is different from a project name. The project name is a human-readable way to identify your projects, but it isn't used by any Google APIs. In the above example, the project name is My Sample Project and the project ID is my-sample-project-191923.

The project ID is generated from the project name you enter when you create the project in the Google Cloud Platform Console. Certain words are restricted from use in project IDs. If you use restricted words in the project name, such as google or ssl, the generated project ID will not include these words. This will not affect the project name.

The project number and project ID are unique across Google Cloud Platform. If another user owns a project ID for their project, you won't be able to use the same project ID.

When you choose your project ID (or any resource names), don't include any sensitive information in your names.

Get an existing project

You can get an existing project using the GCP Console or the projects.get() method.

Console

To view a project using the Google Cloud Platform Console:

  1. Go to the Manage Resources page in the Google Cloud Platform Console.

    Go to the Manage Resources page

  2. Select the project you want to view.

gcloud

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

PYTHON

...
crm = discovery.build(
    'cloudresourcemanager', 'v1', http=creds.authorize(httplib2.Http()))

project = crm.projects().get(projectId=flags.projectId).execute()

...

Listing projects

You can list all projects you own using the GCP Console or the projects.list() method.

Console

To list projects using the Google Cloud Platform Console:

  • Go to the GCP Console.

    Go to the GCP Console

  • All your projects are listed in the projects drop-down on the top bar. Use the Search projects and folders textbox to filter projects.
  • To list all your projects, click Manage Resources. Use the Filter by name, ID, or label textbox to filter your projects.

gcloud

To list all projects accessible by your currently active account, use the gcloud projects list command:

gcloud projects list

This command will provide the project ID, name, and project number for every project for which you have Owner, Editor, or Viewer permissions.

You can use the --filter flag to narrow the results. This flag searches the project ID, name, and project number, and only returns results where the filtered term exists:

gcloud projects list --filter=test

The above command will return all projects for which you have Owner, Editor, or Viewer permission for, and also include the word "test" in the name, project ID, or project number fields. For more information on filter syntax, see gcloud topic filters.

API

Request:

GET https://cloudresourcemanager.googleapis.com/v1beta1/projects

{
    "name": "project a"
}

Response:

{
    "projects": [
    {
        "projectNumber": "951040570662",
        "projectId": "google.com:api-project-951040570662",
        "lifecycleState": "ACTIVE",
        "name": "project a",
        "createTime": "2013-11-13T20:31:53.308Z"
    }
    ]
}

The following code snippet lists all projects with a red label:

Request:

GET
https://cloudresourcemanager.googleapis.com/v1beta1/projects

{
    "labels": {
    "color": "red"
    }
}

Response:

{
    "projects": [
    {
        "projectNumber": "350831539566",
        "projectId": "my-project-b",
        "lifecycleState": "ACTIVE",
        "name": "project b",
        "labels": {
            "color": "red"
        },
        "createTime": "2012-02-18T23:11:57.831Z"
    }
    ]
}

PYTHON

...
crm = discovery.build(
    'cloudresourcemanager', 'v1', http=creds.authorize(httplib2.Http()))

filter = "name:project a"
projects = crm.projects().list(filter=filter).execute()

...

The following code snippet lists all projects with a red label:

filter = 'labels.color:red'
projects = crm.projects().list(filter=filter).execute()

Updating projects

You can update projects using the GCP Console or the projects.update() method. Currently the only fields that can be updated are the project name and labels. You cannot change the project ID value that you use with the gcloud command-line tool or API requests. For more information about updating projects, see the project API reference page.

Console

To update a project's field using the GCP Console:

  • Open the Settings page in the Google Cloud Platform Console.

    Open the Settings page

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

To update a project's name, use the gcloud projects update command:

gcloud projects update PROJECT_ID --name=NAME

Where PROJECT_ID is the ID of the project you want to update, and NAME is the new name you want to assign to the project.

API

To update a project:

The following code snippet updates the name of the project to "myproject":

Request:

    PUT https://cloudresourcemanager.googleapis.com/v1beta1/projects/my-project-123
    {
        "name": "myproject"
    }

Response:

    {
        "projects": [
        {
            "projectNumber": "951040570662",
            "projectId": "my-project-123",
            "lifecycleState": "ACTIVE",
            "name": "myproject",
            "createTime": "2013-11-13T20:31:53.308Z"
        }
        ]
    }

PYTHON

...
crm = discovery.build(
    'cloudresourcemanager', 'v1', http=creds.authorize(httplib2.Http()))

project = crm.projects().get(projectId=flags.projectId).execute()
project['name'] = 'myproject'
project = crm.projects().update(
projectId=flags.projectId, body=project).execute()

...

Shutting down (deleting) projects

You can shut down projects using the GCP Console or the projects.delete() method.

This method immediately marks a project to be deleted and sends a notification email to the project owner. A project that is marked for deletion is not usable. After approximately 30 days, the project will be fully deleted. To stop this 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 will count towards your project quota.

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:

  • The project must not have a billing account associated with it.
  • The project must have a lifecycle state of ACTIVE.

Console

To shut down a project using the GCP Console:

  • Open the Settings page (found under IAM & admin) in the Google Cloud Platform Console.

    Open the Settings page

  • Click Select a project.

  • Select a project you want to delete, and click Open.

  • Click Shut down.

  • Enter the Project ID, then click Shut down.

gcloud

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/v1beta1/projects/my-project-123

PYTHON

...
crm = discovery.build(
    'cloudresourcemanager', 'v1', http=creds.authorize(httplib2.Http()))

project = crm.projects().delete(projectId=flags.projectId).execute()

...

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. Cloud Storage resources are deleted before the 30-day period ends, and may not be fully recoverable.

Some services might need to be restarted manually. For more information, see Restarting Google Cloud Platform Services.

To restore a project:

  1. Go to the Manage Resources page in the Google Cloud Platform Console.

    Go to the Manage Resources page

  2. In the Organization drop-down in the upper left, select your organization.

  3. Below the list of 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.

Was this page helpful? Let us know how we did:

Send feedback about...

Resource Manager Documentation