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

displayName

string

required

Human-readable name for the project

description

string

Optional description of the project’s purpose

clusterName

string

required

Name of the cluster this project belongs to (immutable)

resourceQuota

ProjectResourceQuota

Total resource quota shared across all namespaces in the project

limit

ResourceQuotaLimit

Resource limits for the project

limitsCpu

string

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

limitsMemory

string

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

requestsCpu

string

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

requestsMemory

string

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

namespaceDefaultResourceQuota

NamespaceResourceQuota

Default quota applied to each namespace in the project

limit

ResourceQuotaLimit

Per-namespace resource limits

containerDefaultResourceLimit

ContainerResourceLimit

Default resource limits for containers in the project

limitsCpu

string

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

limitsMemory

string

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

requestsCpu

string

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

requestsMemory

string

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

Project Status

conditions

array<ProjectCondition>

Current state of the project

backingNamespace

string

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

Project Conditions

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

BackingNamespaceCreated

condition

Backing namespace has been created

CreatorMadeOwner

condition

Project creator has been granted owner permissions

DefaultNetworkPolicyCreated

condition

Default network policy has been applied

InitialRolesPopulated

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

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

project-owner

role

Full administrative access to the project

project-member

role

Standard member access - can manage workloads and most resources

read-only

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

​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