> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GCP Resource Hierarchy Project Identification Framework

> Describes GCP project identifiers (name, project ID, project number), their rules, uses, best practices, and gcloud commands for correct identification and automation.

Welcome — in this lesson we'll demystify the Project Identification Framework in Google Cloud Platform (GCP). Think of this framework as a project's passport: a set of identifiers that let both you and Google know exactly which project you're referring to. Clear identifiers prevent confusion when managing resources, billing, APIs, and automation.

This guide breaks the framework down step by step, with practical examples and commands so you can use the correct identifier in the right context.

## The three project identifiers

GCP projects expose three distinct identifiers: the project name, the project ID, and the project number. Each serves a different purpose.

| Identifier     | Description                                                                                                                                                     | Mutability           | Typical uses                                                            |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------- |
| Project name   | Human-readable label shown in the Console and UIs.                                                                                                              | Mutable (renameable) | Console displays, dashboards, documentation                             |
| Project ID     | Globally unique string identifier. Must match naming rules (6–30 chars, lowercase letters, digits, hyphens; begins with a letter; ends with a letter or digit). | Immutable            | Resource paths (e.g. `projects/{PROJECT_ID}`), scripts, URLs, many APIs |
| Project number | Numeric identifier generated by Google Cloud.                                                                                                                   | Immutable            | Internal APIs, billing, quotas, some backend systems                    |

<Callout icon="lightbulb" color="#1CB2FE">
  Use the project name for human-readability; use the project ID for resource paths, scripts, and most automations; and be aware that Google services often reference the project number for billing and internal links.
</Callout>

<Callout icon="warning" color="#FF6B6B">
  Project IDs and project numbers are immutable. Choose project IDs carefully — once created they cannot be changed.
</Callout>

## Identifier details and rules

* Project name
  * Free-text, intended for people. It can contain spaces and punctuation.
  * Changeable at any time without affecting resource references.

* Project ID
  * Globally unique across GCP.
  * Naming rules: 6–30 characters, lowercase letters (`a–z`), digits (`0–9`), and hyphens (`-`); must begin with a letter and end with a letter or digit.
  * Used in resource identifiers such as `projects/{PROJECT_ID}` (wrap the placeholder in backticks when documenting).

* Project number
  * A numeric, Google-assigned identifier (e.g., `123456789012`).
  * Frequently used behind the scenes for billing, quotas, and Google-managed integrations.

## How these identifiers are used

* Resource names and many APIs use the project ID in paths, for example: `projects/{PROJECT_ID}`
* Some APIs, billing connectors, and quota systems prefer or require the project number. A few APIs accept either the project ID or project number.
* IAM and resource-level permissions often reference the project ID in role bindings and policy documents; internal links and system accounts may use the project number.

Because usage varies by API and service, prefer the project ID for automation and scripts, but check the API documentation if you suspect the project number is required.

### Common use-case mapping

| Use case                                   | Prefer         | Reason                          |
| ------------------------------------------ | -------------- | ------------------------------- |
| Automation scripts, CI/CD, IaC             | Project ID     | Globally unique and stable      |
| Billing exports, quotas, some backend APIs | Project number | Internally referenced by Google |
| Console display, human communication       | Project name   | Readable and editable           |

## Examples and gcloud commands

* Create a new project:

```bash theme={null}
gcloud projects create my-project-id --name="My Project"
```

* Retrieve identifiers for a project:

```bash theme={null}
gcloud projects describe my-project-id --format="value(projectNumber,projectId,name)"
```

* List projects with key fields:

```bash theme={null}
gcloud projects list --format="table(projectId, projectNumber, name)"
```

These commands display the human name, immutable project ID, and numeric project number.

## Best practices

* Adopt a standardized naming convention for project names and project IDs. Typical components include organization, environment (dev/stage/prod), team, and application shorthand.
  * Example:
    * name: "Acme Analytics — Prod"
    * project-id: `acme-analytics-prod`
* Keep project IDs short, descriptive, and free of sensitive information (avoid embedding passwords, personal data, or secret keys).
* Use the project ID in scripts, IaC (Terraform, Deployment Manager), and CI/CD pipelines because it is stable and globally unique.
* Avoid personal or ephemeral identifiers in a project ID because it cannot be changed later.

Example naming pattern table:

| Pattern part        | Example               |
| ------------------- | --------------------- |
| Organization        | `acme`                |
| Application         | `analytics`           |
| Environment         | `prod`                |
| Combined project ID | `acme-analytics-prod` |

## When to check API docs

Some APIs accept either the `projectId` or `projectNumber`; others require the numeric project number. If you see an API parameter like `parent` or `name` that references a project, consult that API’s documentation to confirm which identifier is accepted. Always prefer the project ID in automation unless the docs explicitly require the project number.

## Summary

* GCP projects expose three identifiers: a mutable human-readable name, an immutable globally unique project ID (string), and an immutable numeric project number.
* Use the project name for display, the project ID for scripts and resource paths, and be aware that Google services sometimes require the project number.
* Follow consistent naming conventions and avoid embedding sensitive information in project IDs.

## Links and references

* [Google Cloud Projects overview](https://cloud.google.com/resource-manager/docs/creating-managing-projects)
* [gcloud projects](https://cloud.google.com/sdk/gcloud/reference/projects)
* [Identity and Access Management (IAM) overview](https://cloud.google.com/iam/docs)

A recommended follow-up topic: GCP networking concepts — learning how projects and resources connect across Virtual Private Cloud (VPC), Shared VPCs, and inter-project networking will deepen your understanding of resource architectures.

<CardGroup>
  <Card title="Watch Video" icon="video" cta="Learn more" href="https://learn.kodekloud.com/user/courses/google-cloud-professional-data-engineer-certification/module/54d4f17c-56da-41a4-b998-2a2c63f0ee3f/lesson/798ca7db-ca9b-4040-a765-4b31708121ef" />
</CardGroup>