Project API Resource

Projects are a Rancher construct that provides multi-tenancy within a Kubernetes cluster by grouping namespaces and applying consistent policies, quotas, and access controls.

Project Resource

From pkg/apis/management.cattle.io/v3/authz_types.go:30

Project Spec

string

required

Human-readable name for the project

string

Optional description of the project’s purpose

string

required

Name of the cluster this project belongs to (immutable)

ProjectResourceQuota

Total resource quota shared across all namespaces in the project

ResourceQuotaLimit

Resource limits for the project

string

Total CPU limit (e.g., “4000m”)

string

Total memory limit (e.g., “8Gi”)

string

Total CPU requests (e.g., “2000m”)

string

Total memory requests (e.g., “4Gi”)

NamespaceResourceQuota

Default quota applied to each namespace in the project

ResourceQuotaLimit

Per-namespace resource limits

ContainerResourceLimit

Default resource limits for containers in the project

string

Default CPU limit per container (e.g., “200m”)

string

Default memory limit per container (e.g., “256Mi”)

string

Default CPU request per container (e.g., “100m”)

string

Default memory request per container (e.g., “128Mi”)

Project Status

array<ProjectCondition>

Current state of the project

string

Namespace used to store project-scoped resources (PRTBs, secrets)

Project Conditions

From pkg/apis/management.cattle.io/v3/authz_types.go:14

condition

Backing namespace has been created

condition

Project creator has been granted owner permissions

condition

Default network policy has been applied

condition

Initial RBAC roles have been created

Create Project

Create a new project within a cluster.

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "project",
    "name": "production",
    "displayName": "Production",
    "description": "Production workloads",
    "clusterName": "c-m-abc123",
    "resourceQuota": {
      "limit": {
        "limitsCpu": "4000m",
        "limitsMemory": "8Gi",
        "requestsCpu": "2000m",
        "requestsMemory": "4Gi"
      }
    },
    "namespaceDefaultResourceQuota": {
      "limit": {
        "limitsCpu": "1000m",
        "limitsMemory": "2Gi"
      }
    },
    "containerDefaultResourceLimit": {
      "limitsCpu": "200m",
      "limitsMemory": "256Mi",
      "requestsCpu": "100m",
      "requestsMemory": "128Mi"
    }
  }' \
  https://rancher-server/v3/projects

import requests

response = requests.post(
    'https://rancher-server/v3/projects',
    headers={
        'Authorization': f'Bearer {RANCHER_TOKEN}',
        'Content-Type': 'application/json'
    },
    json={
        'type': 'project',
        'name': 'production',
        'displayName': 'Production',
        'description': 'Production workloads',
        'clusterName': 'c-m-abc123',
        'resourceQuota': {
            'limit': {
                'limitsCpu': '4000m',
                'limitsMemory': '8Gi',
                'requestsCpu': '2000m',
                'requestsMemory': '4Gi'
            }
        },
        'containerDefaultResourceLimit': {
            'limitsCpu': '200m',
            'limitsMemory': '256Mi',
            'requestsCpu': '100m',
            'requestsMemory': '128Mi'
        }
    }
)

project = response.json()
print(f"Project ID: {project['id']}")

Response

{
  "id": "c-m-abc123:p-xyz789",
  "type": "project",
  "links": {
    "self": "https://rancher-server/v3/projects/c-m-abc123:p-xyz789",
    "namespaces": "https://rancher-server/v3/projects/c-m-abc123:p-xyz789/namespaces"
  },
  "metadata": {
    "name": "production",
    "namespace": "c-m-abc123",
    "creationTimestamp": "2024-01-01T00:00:00Z"
  },
  "spec": {
    "displayName": "Production",
    "description": "Production workloads",
    "clusterName": "c-m-abc123",
    "resourceQuota": { ... },
    "containerDefaultResourceLimit": { ... }
  },
  "status": {
    "backingNamespace": "p-xyz789",
    "conditions": [
      {
        "type": "InitialRolesPopulated",
        "status": "True"
      }
    ]
  }
}

List Projects

Retrieve all projects:

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/projects

Filter by Cluster

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  "https://rancher-server/v3/projects?clusterId=c-m-abc123"

Get Project

Retrieve a specific project:

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789

Update Project

Update project configuration:

curl -X PUT \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Production - Updated",
    "description": "Updated production environment",
    "resourceQuota": {
      "limit": {
        "limitsCpu": "6000m",
        "limitsMemory": "12Gi"
      }
    }
  }' \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789

Delete Project

Delete a project:

curl -X DELETE \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789

Deleting a project will also delete all namespaces and resources within it.

Multi-Tenancy with Projects

Project Role Template Bindings (PRTB)

Grant users or groups access to a project:

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "projectRoleTemplateBinding",
    "projectName": "c-m-abc123:p-xyz789",
    "userName": "user-abcde",
    "roleTemplateName": "project-member"
  }' \
  https://rancher-server/v3/projectroletemplatebindings

Available Project Roles

role

Full administrative access to the project

role

Standard member access - can manage workloads and most resources

role

Read-only access to project resources

Namespace Management

List Project Namespaces

Get all namespaces in a project:

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/clusters/c-m-abc123/namespaces?projectId=p-xyz789

Move Namespace to Project

Assign a namespace to a project:

curl -X PUT \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "c-m-abc123:p-xyz789"
  }' \
  https://rancher-server/v3/clusters/c-m-abc123/namespaces/my-namespace

Create Namespace in Project

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "namespace",
    "name": "my-app",
    "projectId": "c-m-abc123:p-xyz789"
  }' \
  https://rancher-server/v3/clusters/c-m-abc123/namespaces

Resource Quotas

Understanding Resource Quotas

Projects support two levels of resource quotas:

Project-level quota: Total resources across all namespaces
Namespace-level quota: Default quota for each namespace

Example: Setting Quotas

{
  "resourceQuota": {
    "limit": {
      "limitsCpu": "10000m",
      "limitsMemory": "20Gi",
      "requestsCpu": "5000m",
      "requestsMemory": "10Gi",
      "pods": "100",
      "services": "20",
      "persistentVolumeClaims": "10"
    }
  },
  "namespaceDefaultResourceQuota": {
    "limit": {
      "limitsCpu": "2000m",
      "limitsMemory": "4Gi",
      "requestsCpu": "1000m",
      "requestsMemory": "2Gi"
    }
  }
}

Container Default Limits

Set default resource limits for all containers:

{
  "containerDefaultResourceLimit": {
    "limitsCpu": "500m",
    "limitsMemory": "512Mi",
    "requestsCpu": "100m",
    "requestsMemory": "128Mi"
  }
}

Container defaults apply when workloads don’t specify resource requests/limits.

Project Isolation

Network Policies

Enable network isolation between projects:

curl -X PUT \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "enableNetworkPolicy": true
  }' \
  https://rancher-server/v3/clusters/c-m-abc123

When enabled:

Pods in different projects cannot communicate by default
Intra-project communication is allowed
Explicit NetworkPolicies can override defaults

Best Practices

Organize by Environment

Create separate projects for different environments:

production
staging
development

Set Resource Quotas

Always define resource quotas to prevent resource exhaustion:

Project-level quotas for overall limits
Namespace defaults for consistent allocation
Container defaults to ensure all workloads have limits

Use Meaningful Names

Choose descriptive names that indicate:

Environment (prod, staging, dev)
Team or application (team-frontend, app-backend)
Purpose (ci-cd, monitoring)

Implement RBAC Early

Grant least-privilege access:

Use project-member for developers
Reserve project-owner for leads
Use read-only for monitoring tools

Enable Network Policies

Enable network isolation for production projects to:

Prevent unauthorized access
Comply with security requirements
Isolate sensitive workloads

Monitoring Projects

Check Resource Usage

Get current resource usage for a project:

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789?include=usage

Watch Project Events

Monitor project-level events:

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/events

Next Steps

Workloads

Deploy applications in projects

RBAC

Configure role-based access control

Namespaces

Manage namespaces within projects

APIs

Resources

Cloud Providers

Project API Resource

Project Resource

Project Spec

Project Status

Project Conditions

Create Project

Response

List Projects

Filter by Cluster

Get Project

Update Project

Delete Project

Multi-Tenancy with Projects

Project Role Template Bindings (PRTB)

Available Project Roles

Namespace Management

List Project Namespaces

Move Namespace to Project

Create Namespace in Project

Resource Quotas

Understanding Resource Quotas

Example: Setting Quotas

Container Default Limits

Project Isolation

Network Policies

Best Practices

Monitoring Projects

Check Resource Usage

Watch Project Events

Next Steps

Workloads

RBAC

Namespaces

​Project Resource

​Project Spec

​Project Status

​Project Conditions

​Create Project

​Response

​List Projects

​Filter by Cluster

​Get Project

​Update Project

​Delete Project

​Multi-Tenancy with Projects

​Project Role Template Bindings (PRTB)

​Available Project Roles

​Namespace Management

​List Project Namespaces

​Move Namespace to Project

​Create Namespace in Project

​Resource Quotas

​Understanding Resource Quotas

​Example: Setting Quotas

​Container Default Limits

​Project Isolation

​Network Policies

​Best Practices

​Monitoring Projects

​Check Resource Usage

​Watch Project Events

​Next Steps

Workloads

RBAC

Namespaces

Project Resource

Project Spec

Project Status

Project Conditions

Create Project

Response

List Projects

Filter by Cluster

Get Project

Update Project

Delete Project

Multi-Tenancy with Projects

Project Role Template Bindings (PRTB)

Available Project Roles

Namespace Management

List Project Namespaces

Move Namespace to Project

Create Namespace in Project

Resource Quotas

Understanding Resource Quotas

Example: Setting Quotas

Container Default Limits

Project Isolation

Network Policies

Best Practices

Monitoring Projects

Check Resource Usage

Watch Project Events

Next Steps