Skip to content

2.2. Topology

When to Look at This​

  • To see at a glance which resources make up a deployed application
  • To check whether a Service is properly connected to its pods
  • To see what is affected if you delete one resource
  • To find Services, PVCs, ConfigMaps, and Secrets that are not connected to any workload

List screens are divided by resource type, which makes connections hard to see. This screen shows those connections as a diagram.

The Topology Screen​

Select Topology in the left menu.

Topology screen

Each card is one resource, or a group of resources of the same kind. The lines between cards are the connections.

The diagram appears only after you choose a namespace. If no namespace is chosen, the diagram area shows Select a namespace to view the topology and no resources are loaded. Choose one or more in Namespaces at the top right of the screen. If you clear the whole selection, the diagram disappears and the same message appears.

  • In the same browser tab, the namespaces you chose last are selected again when you come back.
  • A user who can access only one namespace has that namespace selected automatically.
  • While the message is shown, the resource type, grouping, status filter and Find by name controls are unavailable.
  • List View shows the full list even when no namespace is chosen.

The diagram shows things that are hard to tell from lists alone.

  • Which Service sends traffic to which pods
  • How many pods a Deployment is running
  • How far an incoming Ingress reaches
  • Which pod uses which ConfigMap or Secret

Reading the Cards​

MarkerMeaning
Card titleThe resource name. A long name is shortened (see below). Hover to see the full name
Icon on the leftThe resource type. A workload scaled to zero pods is shown dimmed
Number next to the kindThe workload's pod count (ready/desired, for example 1/1). Shows a gray 0 when scaled to zero
Number button at the top rightHow many child resources this card has collapsed
Circular badge at the top rightHow many resources have errors or warnings
Border colorStatus. Green = normal, orange = warning, red = error
Used by N workloads next to the kindA PersistentVolumeClaim (PVC) that several groups use. N is the number of groups that use the PVC

When several resources are grouped into one, the count appears at the top right of the card. With 10 pods, one card carries 10.

Long names stay easy to recognize. When a name does not fit on the card, the leading namespace name is removed first. If it is still too long, the beginning, middle, and end are kept and the parts between them become …. For example, openmaru-observ-clickhouse-shard0-replica1-headless in the openmaru-observ namespace appears as clickhouse-shard0-replica1-headless, or as clickhou…ard0-rep…headless when space is tighter. All cards on the map have the same width, so the rows stay even.

Three Interactions​

Each interaction produces a different result.

InteractionResult
Selecting the card bodyA detail drawer opens on the right
Selecting the number button at the top rightThe grouped child resources expand
Selecting empty spaceClears the selection

Selecting the body of a group card opens the detail of that group's representative resource. Selecting a Deployment card, for example, opens the Deployment detail; to see the pods inside it, expand with the number button and then select an individual pod card.

The card whose detail you last opened keeps a highlight. When moving among several resources, it shows how far you have looked. The highlight disappears when you hover another card or select empty space.

Zoom in and out with the mouse wheel over the diagram, and pan by dragging empty space.

Double-click empty space or a namespace box to return to 100% size. The point you double-clicked stays in the same place on the screen. Double-clicking a card does not change the size and only opens the detail. The 100% button sets the size to 100% and puts the whole diagram in the center of the screen.

Creating Resources With a Right-Click​

You can create a workload directly from the Topology screen. Right-click empty space or a namespace box to open the Add to Namespace menu.

Add to Namespace menu
Menu itemResource created
DeploymentDeployment (see 3.2)
StatefulSetStatefulSet (see 3.2)
DaemonSetDaemonSet (see 3.2)
Build ConfigBuild config (see 4.2). Appears only on clusters where the build feature is installed

Select an item to open the same create window as the + on the list screen. When you save, the new card appears with a highlight. The position and size of the view do not change.

The namespace field in the create window is filled in according to where you right-clicked.

Where you right-clickedNamespace field
A namespace box, or an expanded group inside itThat namespace
Empty space (only one namespace chosen at the top of the screen)The chosen namespace
Empty space (all other cases)Empty. Choose it in the create window
  • Right-clicking empty space inside an expanded group also opens this menu. Right-clicking a card opens the card menu instead (next section).
  • Items you do not have permission to create are dimmed and cannot be selected. Hover over one to see You do not have permission to create in this namespace.
  • To open the menu with the keyboard, focus a namespace box and press the menu key or Shift+F10. The menu opens at the top left of the box.
  • When there are no resources to show, Right-click an empty area to add a workload. appears in the center of the screen. When Group By is Namespace, an empty namespace box appears instead of this message. Right-click that box.

Card Right-Click Menu​

Work with a resource right where you see it on the map. Without opening the detail screen, right-click a card to change the Pod count, restart, or edit environment variables.

  1. Right-click a card. The resource name appears at the top of the menu.
  2. Choose an action. The same window opens as when you select the same button on the detail screen.
Card right-click menu
CardWhat you can do from the menu
DeploymentEdit Pod count, Restart, Pause rollouts / Resume rollouts, Edit Health Checks, Edit Resource Limits, Edit Labels and Annotations, Edit Environment Variables, Edit, Edit Build Config, Delete
StatefulSetEdit Pod count, Restart, Edit Health Checks, Edit Resource Limits, Edit Labels and Annotations, Edit Environment Variables, Edit, Delete
DaemonSetRestart, Edit Health Checks, Edit Resource Limits, Edit Labels and Annotations, Edit Environment Variables, Edit, Delete
Service, IngressEdit, Delete
Build configStart Build, Rebuild, Cancel Build, Deploy, Edit, Delete
  • Only items you have permission for appear. Edit opens the YAML editor. For how the edit windows work, see 3.2.
  • On a workload whose Pod count an HPA (Horizontal Pod Autoscaler) or CronHPA manages, Edit Pod count is dimmed and cannot be selected.
  • Right-clicking a card not in the table above (a pod and so on) opens the browser's own menu.

Expanding and Collapsing Groups​

Namespaces start expanded, so the group cards inside them, such as Deployments, are visible right away. Cards are grouped by kind (workloads such as Deployment and StatefulSet → build configs → pods → Services and so on). Within a kind, cards are sorted by name, so they stay in place when a rollout or a Pod count change alters the number of resources. A Service is connected to the workload (Deployment, StatefulSet, or DaemonSet) whose pod labels match its selector, and appears as a branch beside the ReplicaSet when that group is expanded. It looks the same regardless of the pod count. The Ingress and Endpoints in front of the Service appear in the column after the Service.

When Group By is Namespace, Services, Ingresses, PVCs, and build configs that are not connected to any workload are not drawn on the map. They are collected in the namespace box lists instead (see "Resource Lists on the Namespace Box" below). With Node or Instance grouping, they are drawn as cards with a dashed border. Hover over the broken-link icon before the kind name to see the reason.

Selecting the number button on a group card expands that card in place and shows the resources attached to it. Other cards and namespaces stay on the screen. The view moves to the expanded group, and the path Home / Namespace <name> / <resource name> appears at the top of the screen. Selecting the card body opens the detail on the right.

In an expanded group, the card in the leftmost column with a thicker border is the group's representative resource. It is the resource whose detail opens when you select the collapsed card.

Topology resource detail

The figure above expands one Deployment, and the following appear on one screen.

  • The current ReplicaSet, with a Previous ReplicaSets (N) button under it (an earlier ReplicaSet is created on each deployment; see 3.2)
  • The pods currently running
  • The PersistentVolumeClaim those pods use (see 6.1)
  • The Service and Endpoints in front of the pods, and the Ingress in front of those (see 5.1)

Many pods do not make the map long. On a card with 6 or more pods, only the first 3 by name, pods with a warning or error status, and the pod whose detail is open are shown. The rest fold into one More pods (N) card. Pods with problems are never folded, so you notice them at once.

More pods (N) card
  1. Select More pods (N). All hidden pods appear.
  2. To fold them again, select Collapse pods.

In the detail on the right, you check that resource's metadata, replica count and running state, pod list, and conditions. It is the same content as the detail on the list screen, so you can also edit, restart, and delete from here.

Earlier ReplicaSets remaining is normal. A Deployment creates a new ReplicaSet on every deployment and leaves the previous one at zero pods. This is so it can be used for rollback (see 3.2). Only the current ReplicaSet is shown directly; when there are earlier ones, a Previous ReplicaSets (N) button appears under its card. Builds work the same way: only the most recent build of each build config is shown directly, with a Previous builds (N) button under it. Selecting the button shows each earlier item as its own card, and the button changes to Collapse previous ReplicaSets / Collapse previous builds. While collapsed, no error marker is shown even if an earlier build failed.

Selecting Collapse at the top right of an expanded group collapses that group and everything inside it. If you expanded a Deployment inside a namespace, one Collapse on the namespace collapses both and returns to the first diagram.

To expand or collapse all groups in a namespace at once, use the buttons on the right of the namespace box title bar. After you select one, the view moves to that namespace box.

ButtonResultShown when
Expand allExpands all collapsed cards in that namespaceAt least one card is collapsed
Collapse allCollapses all groups you expanded in that namespaceAt least one group is expanded

Neither button changes the expanded groups in other namespaces. Expand all does not expand the items behind the Previous ReplicaSets (N) and Previous builds (N) buttons.

  • Several groups can stay expanded together. Expanding another group leaves the earlier ones expanded.
  • Groups you expanded stay expanded when you go to List View or another menu and come back in the same browser tab. A new tab starts from the first view.
  • Selecting the name at the top of a group opens only the detail. The expanded state does not change.
  • To view one namespace in full, select only that namespace in the namespace selector at the top of the screen.

Build jobs gather under their build config, and the build config is grouped with its deploy target. Each build from the Build menu creates a job (Job), but the diagram gathers them under that build config. If there is a Deployment that the build config deploys to, the two are connected by a line and grouped into that Deployment card. When expanded, build config → job → pod and build config → Deployment appear together. Check a build config without a deploy target in the Build Configs list on the namespace box with Namespace grouping, or as a card with a dashed border with Node or Instance grouping.

The red marker on a card reflects only the most recent build of each build config. Even if an earlier failed build remains in the history, there is no red marker when the most recent build succeeded.

Scaling resources are grouped with their target workload. Scaling resources are HPA (Horizontal Pod Autoscaler), CronHPA (scheduled scaling), VPA (Vertical Pod Autoscaler), and PDB (PodDisruptionBudget, a limit on how many pods can be stopped at the same time). An HPA, CronHPA, or VPA goes into the card of the target workload written in its settings. A PDB goes into a workload card only when exactly one workload matches its selector. When you expand the group, they appear after the Service and Ingress and before the PersistentVolumeClaim, ConfigMap, and Secret.

CaseDiagram
The target workload of an HPA, CronHPA, or VPA does not existAppears as its own card. It is not removed from the map and has no dashed border
Two or more workloads match the PDB selector, or the selector is emptyAppears as its own card. Check the targets on the PDB detail
VPA or CronHPA is not installed in the clusterThose cards do not appear. No error is shown

A PVC that several workloads use appears separately in each group. When workloads in different groups use one PVC, the diagram draws one card for that PVC in each group. The PVC does not merge the workload groups into one. These PVC cards show Used by N workloads next to the kind name.

CaseDiagram
Only one workload uses the PVC, or the workloads that use it are already in one group (for example, a CronJob and its Jobs)There is one PVC card. No usage count is shown
No workload uses the PVCWith Namespace grouping, it appears in the PVCs list on the namespace box. With Node or Instance grouping, it appears as its own card with a dashed border
  • N is the number of groups that use the PVC. Several workloads in one group count as one.
  • Selecting any of the PVC cards opens the detail of the same PVC. The highlight for the last opened detail appears on all cards of that PVC.
  • When you type the PVC name in Find by name, all groups that have that PVC match.

Resource Lists on the Namespace Box​

Find Services, ConfigMaps, Secrets, and similar resources without cluttering the map. The namespace box title row has a button for each resource kind, and each button shows how many of those resources the namespace has (for example, S 3). Resources that are not drawn on the map because nothing is connected to them are also found here.

ButtonList it opens
SServices
IIngresses
PVCPVCs
CMConfigMaps
SECSecrets
BCBuild Configs
  1. Select a button on the namespace box title row. A list sorted by name opens below the button.
  2. If the list is long, type part of a name in Find by name above the list.
  3. Select a name to open its detail, or select the Edit icon to open the YAML editor.
  4. Select the same button again to close the list.

Resources with no connected workload are marked in orange. The orange number at the top right of the Services, Ingresses, PVCs, and Build Configs buttons is the number of items with nothing connected. In the list, those items get an orange broken-link icon before the name. Hover over the icon to see the reason, such as No connected workload. Use this to find resources to clean up or settings that are missing.

Service list of a namespace box

In an expanded workload box, see only the ConfigMaps and Secrets that the workload uses. When you expand a Deployment, StatefulSet, or DaemonSet group, the CM and SEC buttons appear after Collapse on the box title row. Select one to open the list filtered to what that workload uses; Used by <workload name> appears under the list title. This is handy for checking which settings go into which application.

Secret list of an expanded workload box
  • The buttons appear only when Group By is Namespace.
  • A button does not appear for a kind whose list you do not have permission to see. The BC button does not appear on clusters where the build feature is not installed.
  • The ConfigMaps and Secrets buttons do not show an orange number. Check the icons in the list.

Narrowing the View​

With many resources, the diagram becomes complicated. Narrow the scope at the top of the screen.

ControlDescription
NamespaceShows only a particular namespace
Resource typeSelects which types to show — pods only, or pods and Services, and so on. The Scaling group (HPA, CronHPA, VPA, PDB) is directly below Workloads and is on from the start
Group BySelects whether resources are grouped into boxes by Namespace, Instance, or Node. It is Namespace at first
Find by nameHighlights the cards whose names match and dims the other cards

Choose only the namespaces you need. Choosing many namespaces at once produces hundreds of cards and the connections become unreadable.

When you type in Find by name, the result appears at once. Cards whose names match get a thick orange border, and the other cards are dimmed. You can still select a dimmed card. The match count (for example, 3 matches) appears next to the input.

  • Case does not matter. A name matches when it contains the search text as is. For example, sp1 matches test-sp1-api but not spring1. You can also find a pod by a name copied from a log.
  • A group card matches when the name of at least one resource in it matches. When you expand the group, each inner card is compared separately.
  • Pods folded into More pods (N) are also searched. When a folded pod matches, the More pods (N) card is marked as a match.
  • When a namespace box list has a resource whose name matches, that button gets an orange border. Open the list to see the matching rows marked with the same border.
  • Finding does not change the view position or size.
  • Select ✕ on the right of the input or press Esc to clear the search text. The search text stays when you change the namespace or expand a group, and is cleared when you leave the Topology screen.

List View​

The same content can also be seen as a table. Switch to List View at the top of the screen.

Connections are easier to see in the diagram, while counts and statuses are easier to tally in the list. When you have to count failing resources, the list is more convenient.

The Jobs table has the same Build jobs buttons (Hidden, Builds only, All) as the Job list. Build jobs are hidden by default, and the selected value is shared with the Job list (see 3.3).

When a Connection Is Not Shown​

If there is no line from a Service to its pods, the selector does not match the pod labels. Check the selector on the Service detail and the labels on the pod detail, and compare them (see 5.1, 3.1).

If there is no line from an Ingress to a Service, either the Service name written in the Ingress rule differs from the actual one, or that Service is in a different namespace.

When Group By is Namespace, a Service or Ingress that is not connected to any workload does not appear on the map. Select the S or I button on the namespace box and look for items with the broken-link icon in the list.