6.4 Projects and namespaces

Understanding Projects and Namespaces in OpenShift

OpenShift builds on top of Kubernetes namespaces, but adds extra opinionated behavior and features. In practice, you almost never create “raw” namespaces in OpenShift; you work with Projects, which are an OpenShift extension around namespaces.

This chapter focuses on how Projects and namespaces behave in OpenShift, how they are used to organize and isolate workloads, and what is unique compared to plain Kubernetes.

Conceptual model: Project vs Namespace

In OpenShift:

• A Namespace is the Kubernetes primitive used for logical isolation of resources.
• A Project is an OpenShift resource that:
• wraps a Namespace,
• adds metadata and defaults (like Security Context Constraints, quotas, and roles),
• is the main user-facing unit for working with applications.

You can think of it as:

• Every Project corresponds to exactly one Namespace.
• When you create a Project, OpenShift:
• creates a Namespace with the same name,
• sets up RBAC roles and bindings,
• may assign default ResourceQuotas and LimitRanges,
• labels/annotates it for OpenShift-specific behavior.

You generally interact with Projects via:

• Web console “Projects” view
• CLI oc new-project, oc project, oc get projects

The underlying Namespace is visible with oc get ns, but usually you don’t manipulate it directly.

Why Projects matter in daily work

Projects are the primary unit for:

• Multi-tenancy and isolation
  Each team, app, or environment (dev/test/prod) typically gets its own Project.
• Access control
  All RBAC rules are mostly scoped to a Project:
• “Developers can manage resources in team-a”
• “Ops can view but not modify in prod-app”
• Resource governance
  Quotas, limits, and security constraints are attached per Project.
• Organization
  Logical grouping of resources (Deployments, Services, Routes, PVCs, etc.) that belong to one application or team.

---

Basic operations with Projects (CLI)

Listing and switching Projects

Use oc to view and switch your current working Project:

# List all Projects you can see
oc get projects
# Show the current Project
oc project
# Switch to another Project
oc project my-app-dev

The current Project is stored in your kubeconfig context, so subsequent oc commands (like oc get pods) run against that Project unless you override it with -n or --namespace.

Creating a Project

Creating a Project automatically creates the underlying Namespace and applies default policies:

# Create a new Project
oc new-project my-app-dev \
  --display-name="My App - Development" \
  --description="Development environment for My App team"

Key aspects:

• my-app-dev is both the Project name and the Namespace name.
• display-name and description are user-friendly metadata shown in the web console.
• OpenShift may apply default:
• roles (e.g., making you an admin of the Project),
• quotas/limits (if configured cluster-wide),
• annotations/labels for policy.

Deleting a Project

Deleting a Project cascades and deletes everything in that Namespace:

oc delete project my-app-dev

This:

• removes Deployments, Pods, Services, Routes, PVCs, and most other namespaced resources,
• marks the Namespace for deletion; it might remain in Terminating state if some resources block it.

Deletion is irreversible, so it’s typically restricted to users with sufficient permissions.

Projects in the web console

From the OpenShift web console:

• Project selection: The project selector at the top allows switching context. All views (Workloads, Networking, Storage) are filtered by the currently selected Project.
• Creating Projects:
• Use “Create Project” or “Create” → “Project”.
• Provide name, display name, and description.
• Viewing Project details:
• See quotas, limits, role bindings, labels, and annotations.
• Some settings may be read-only for non-admins.

For everyday application work, you typically:

1. Select the Project.
2. Deploy applications, create Services, Routes, PVCs, etc., all scoped to that Project.
3. Rarely think about the underlying Namespace directly.

---

Namespaces behind the scenes

Though you work with Projects, the underlying Kubernetes Namespace is what actually provides resource scoping:

• Most Kubernetes/OpenShift resources are namespaced:
• Deployment, Pod, Service, Route, ConfigMap, Secret, PVC, etc.
• Some resources are cluster-scoped (not tied to a Namespace):
• Node, ClusterRole, ClusterOperator, StorageClass, etc.

You can see the underlying Namespace with:

oc get ns

You’ll notice that:

• User-facing Projects appear as namespaces.
• Many system namespaces exist, for example:
• openshift-* (OpenShift platform components),
• kube-* (core Kubernetes components).

You generally should not modify system namespaces unless explicitly performing cluster administration tasks.

Access control within Projects

Role-Based Access Control (RBAC) in OpenShift is commonly applied per Project:

• Users and groups are granted roles within a Project:
• e.g., edit, view, admin.
• These determine what operations a user can perform on namespaced resources in that Project.

Examples (from an admin perspective):

# See who has access to a Project (roles and bindings)
oc get rolebindings -n my-app-dev
# Add a user as "edit" in a Project
oc adm policy add-role-to-user edit alice -n my-app-dev
# Add a group as "view" in a Project
oc adm policy add-role-to-group view dev-team -n my-app-dev

From a regular user view, the important part is:

• If you can’t see or modify a resource, you may not have appropriate role in that Project.
• Permissions are per Project, so you might be an admin in my-app-dev but read-only in my-app-prod.

---

Organizing Projects: patterns and conventions

How you structure Projects has a big impact on clarity, isolation, and governance.

Typical patterns:

Environment-based separation

• my-app-dev
• my-app-test
• my-app-prod

Benefits:

• Clear separation of environments.
• Different teams or permissions per environment.
• Different quotas/limits and policies per environment.

Team- or domain-based separation

• team-a
• team-b
• data-platform
• analytics

Each team might then organize their workloads within their team Project using naming conventions for resources.

Multi-tenant clusters

In larger organizations:

• Projects map to tenants (teams, business units, customers).
• Per-Project quotas and network policies help enforce strong isolation.
• Central platform team manages policy; app teams work inside their Projects.

Naming conventions

Common recommendations:

• Use lowercase alphanumeric and -.
• Prefer meaningful, consistent patterns:
• team-app-env (e.g., payments-api-dev)
• org-domain-env (e.g., acme-billing-prod)

Consistent naming makes it easier to:

• Filter in the UI/CLI.
• Apply policies or automation that match on naming or labels.

---

Resource governance in Projects (high-level)

Projects are the unit where cluster administrators typically attach:

• ResourceQuotas (overall caps on CPU, memory, number of objects, etc.).
• LimitRanges (default and maximum container resource requests/limits).
• Security Context Constraints (SCCs) usage (what security settings pods can use).

From a user’s perspective, this means:

• If you exceed quota in a Project, new Pods or PVCs may fail to create.
• If you don’t specify CPU/memory for Pods, defaults from LimitRanges may be applied.
• Some security-sensitive configurations (e.g., running as root) might be blocked depending on Project policies.

You can inspect these:

# Show quotas in a Project
oc get resourcequota -n my-app-dev
# Show limit ranges in a Project
oc get limitrange -n my-app-dev

Details of configuring and tuning these are covered in other chapters; here, understand that they are scoped to and enforced per Project.

Cross-project interactions and isolation

By default:

• Resources in one Project are logically isolated from another.
• Pods in one Project can’t directly reference objects in another Project.
• Network communication between Projects may be allowed or restricted depending on cluster network policies.

Common scenarios:

• Shared services (e.g., a central logging or database Project):
• Access via Routes, external Services, or (with proper permissions) by referencing cluster-scoped constructs like StorageClass.
• CI/CD:
• Pipelines may deploy to multiple Projects (e.g., dev → test → prod),
• but each environment is still isolated by its own Project.

If network policies are used, they are often defined per Project to control which other Projects can talk to it.

Working effectively with Projects as a developer

Practical tips:

• Always know your current Project before running commands:
• oc project or check the context in the web console.
• Use namespaces explicitly when scripting:
• Prefer -n my-app-dev in scripts and automation to avoid mistakes.
• Request appropriate roles:
• If you can’t create Deployments or Routes, you may need edit or admin in that Project.
• Treat Projects as boundaries:
• Don’t rely on cross-project assumptions.
• Keep configs, Secrets, and PVCs within the Project that owns the application.

---

Summary

• A Project in OpenShift is a higher-level construct that wraps a Kubernetes Namespace and adds OpenShift-specific metadata and defaults.
• Projects are the central unit for:
• isolating workloads,
• applying RBAC,
• attaching quotas, limits, and security policies.
• You normally create and manage Projects, not raw Namespaces, via:
• oc new-project, oc project, and the web console.
• Project design (naming, environment separation, team mapping) strongly influences how manageable and secure your OpenShift usage becomes.