Principles

This page explains, in plain terms, how the web interface works: why it is split into two parts, how a project differs from a namespace, how the interface knows which sections to show you, how it respects your permissions, and how it behaves on smaller screens.

The System / Projects split

In many organizations, running the cluster and working inside it fall to different people: platform engineers set up and maintain the platform itself, while product teams use it for their applications without administering the cluster. The interface mirrors this division of labor so that each role works in its own part without being distracted by the other:

The split is strict: things that belong to the platform cannot be opened under “Projects”, and vice versa. You switch between the halves manually, using the selector in the top-left corner; the interface never moves you between them on its own.

How a project differs from a namespace

They are almost the same thing — here is the difference:

• A namespace is a standard Kubernetes concept: a “folder” that groups the resources of one application or team.
• A project is the same kind of namespace, but created and managed by the Deckhouse platform from a template. The template immediately sets up the limits and rules it needs (resource quotas, network policies, access permissions), and the platform looks after its lifecycle.

In short, a project is a namespace “furnished” by the platform. That is why user namespaces appear under “Projects”, while the platform’s own service namespaces appear under “System”.

How the interface sorts namespaces

The platform keeps all namespaces together and does not split them into “system” and “user”. The interface does this itself, by the namespace name: the platform’s service names (for example, those starting with kube- or d8-, plus default) go to “System”, and everything else goes to “Projects”.

• The interface remembers the last namespace you opened separately for each half and returns to it next time.
• If a namespace is not selected, does not exist, was deleted, or belongs to the other half, the interface shows a list to choose from rather than opening something at random.
• If no namespaces are available (you have no permissions, or there are none), you will see an explanatory empty state.

Why you see some sections and not others

Different users see different sets of sections — and that is normal. A section appears in the menu only when both conditions are met:

• The relevant platform module is enabled. If the module is off, its section is not shown.
• You have permissions for the data the section relies on.

So you only see what exists in your cluster and is allowed for you personally.

For example, the monitoring section appears only if one of the monitoring modules is enabled and you have permission to view it.

How the screens are built

The interface is made up of two kinds of screens:

• Hand-built. Complex or special screens — the cluster overview, updates, the platform operator, forms with their own logic — are designed and coded separately by developers.
• Generated automatically. For most Kubernetes resources, the screens (lists, viewing, and create/edit forms) are built on the fly from that resource’s OpenAPI specification.

An OpenAPI specification is a machine-readable description of a resource (what fields it has, of what type, and what is required) that Kubernetes itself exposes through its API. The interface reads this description and draws a form with hints and validation from it. Thanks to this, even new and non-standard resources show up in the interface without separate development work, and every resource always has a raw YAML tab next to its form.

How your permissions are respected

The interface has no special powers of its own: it acts on your behalf. Whatever you cannot do in the platform directly, you cannot do through the interface either. Permissions are checked in several places:

• In the menu — an item is hidden if you have no permissions for its contents.
• When opening a screen — if required permissions are missing, you get a clear message instead of the screen, listing exactly which permissions are missing.
• On buttons and blocks within a screen — actions such as create, edit, or delete are simply hidden when they are not available to you.

At the same time, the interface does not break under limited permissions but adapts gracefully:

• if you only have access to some projects, it shows data for those instead of failing with an error;
• supplementary data (quotas, metrics) is simply omitted when permissions are missing, while the main list keeps working;
• if something is unavailable, you can see it — data does not disappear silently.

How the interface behaves on smaller screens

The interface adapts to the available width: on narrow screens, blocks that sit side by side on a wide monitor stack into a single column. While data is loading, gray placeholders of the same height appear in their place, so the content does not jump as it loads.