Skip to content

docs: Edit learn project docs #4145

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 11, 2025
Merged

docs: Edit learn project docs #4145

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs/learn/projects.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_position: 5

# Projects

Headlamp Projects make Kubernetes easier to manage by grouping related resources into a single, application-centric view that is designed with developers in mind. Instead of navigating cluster-wide lists or searching for labels, Projects let you organize workloads across one or more namespaces and even multiple clusters into a logical group. This approach gives developers clarity on their application as a whole, making collaboration, troubleshooting, and onboarding much simpler.
Headlamp Projects makes managing Kubernetes easier by providing an application-centric view. Projects organize workloads across multiple namespaces and clusters into one logical group. This approach offers developers offers more clarity as opposed to traditional list views. The Projects feature makes collaboration, troubleshooting, and onboarding much simpler.

## Why Use Projects

Expand Down Expand Up @@ -65,42 +65,42 @@ After creating a project, you can explore it using the available tabs in the Pro

![Project Overview](https://github.com/user-attachments/assets/a03ed234-e734-47e2-86d6-2bf11bf71963)

Teams often struggle to understand application context because labels, annotations, and cluster details are scattered across multiple views. The Overview tab solves this by providing a single, project-scoped snapshot that brings labels, annotations, linked clusters, and included namespaces together. This clarity helps teams align quickly and reduces time spent piecing information together.
Scattered details across multiple views can make understanding application context difficult. The Overview tab solves this via a single project-scoped view. This view gathers labels, annotations, linked clusters, and included namespaces in one location.

### Resources Tab

![Project Resources](https://github.com/user-attachments/assets/fbca87df-34ad-423f-995c-3c04d72ac5b9)

Finding the right resources across clusters and namespaces can be slow and error-prone when using cluster-wide views. The Resources tab eliminates this friction by listing deployments, pods, services, and other objects scoped to the project. Everything is aggregated across associated clusters, so developers can navigate faster and focus on the application instead of searching through unrelated data.
Resource navigation across multiple clusters and namespaces can be slow and error-prone. The Resources tab smooths navigation by listing deployments, pods, services, and other objects. With Project aggregation, developers no longer need to search through unrelated data.

### Access Tab

![Project Access](https://github.com/user-attachments/assets/c0e56948-6fdd-4a4e-b678-7cb5418cb9a3)

Managing permissions in Kubernetes can be confusing, and developers often do not know where they have access. The Access tab provides confidence and safety by showing who can interact with project resources. Headlamp respects Kubernetes RBAC, so users only see and manage what they are allowed to, reducing mistakes and improving security.
Managing permissions in Kubernetes can be confusing often making developer access unclear. The Access tab provides clarity and safety by showing who can interact with project resources. Headlamp respects Kubernetes RBAC, so users only see and manage what they are allowed to, reducing mistakes and improving security.

### Map Tab

![Project Map](https://github.com/user-attachments/assets/87341cfd-3978-4555-b34b-020e4666c789)

Understanding dependencies and relationships through lists alone is difficult, which slows troubleshooting and planning. The Map tab gives teams a visual representation of how resources within the project connect, such as services to pods and configurations. This makes it easier to spot broken links, missing dependencies, and unhealthy workloads, speeding up issue resolution and improving application reliability.
Understanding dependencies and relationships through list views can be difficult and time-consuming. The Map tab provides a visual representation of the relationship between project resources. Using the map makes it easier to follow connections like services to pods and configurations. This also makes it easier to spot issues like broken links, missing dependencies, and unhealthy workloads.

## Use Cases

### Multi-environment management

Teams often juggle development, test, and production with resources spread across clusters and namespaces, which leads to drift, mistakes, and slow handoffs. Projects give each environment a clear and scoped home so the team sees only what belongs to that environment. By grouping resources across namespaces and even clusters under a single project, you reduce confusion, prevent accidental changes in the wrong place, and create a shared context for releases and rollbacks.
Teams often manage dev, test, and prod across clusters, causing drift and slow handoffs. Projects give each environment a defined space, keeping resources organized. Grouping resources under one project reduces errors and simplifies releases.

### Developer onboarding

New developers usually face a wall of Kubernetes complexity with scattered views, YAML hunting, and uncertainty about where they have access. Projects provide an application centric space that shows only the resources that matter, while honoring Kubernetes RBAC so people see what they are allowed to work with. A lead can create a project in a few clicks, and a new developer can sign in, find the app, deploy changes, and monitor results without navigating cluster internals.
Kubernetes can overwhelm new developers with cluttered views and unclear access. Projects simplify onboarding by showing only what is relevant and respecting RBAC permissions. A lead creates the project, and new devs can start deploying and monitoring right away.

### Troubleshooting and monitoring

Triage slows down when logs, events, metrics, and relationships are spread across tools and cluster wide views. Projects scope operational data to the application boundary so teams can focus on relevant signals instead of sifting through noise. With resources, logs, events, metrics, and the map all filtered to the project, developers can spot broken links, understand dependencies, and resolve issues faster with greater confidence.
Triage slows when logs and metrics are scattered across tools and clusters. Projects focus data within the app boundary so teams can see only relevant signals. With everything scoped to the project, devs can trace issues and fix them faster.

## Get Started Today

Headlamp Projects make Kubernetes simpler, and more application focused. Create a project, link the right namespaces, and give your team a clear, scoped space to collaborate and manage workloads without cluster-wide complexity.
Headlamp Projects make Kubernetes simpler, and more application focused. Create a project, link resources, and give your team a clear space to collaborate.

Open Headlamp, select Projects, and start organizing your applications for faster onboarding, easier troubleshooting, and better team alignment.