Skip to content

Data model and resource coverage ​

Object identity ​

Every object in v8s is addressed by an ObjectKey:

cluster / group / version-independent kind (GVR resource) / namespace / name      → stable address (URLs, bookmarks)
uid                                                                                → identity (problems, caches)
resourceVersion                                                                    → freshness (edits, cache validity)
  • URLs use the address: /c/prod-eu/apps/deployments/payments/api. Bookmarks survive object recreation.
  • Inside the agent, rows are addressed by dense u32 handles per (cluster, GVR), mapped from uid. Handles never leave the agent. The wire carries per-subscription ids that are never reused (performance.md §9), and actions resolve them back to (cluster, uid) in the agent.
  • A cluster has a stable local id assigned when it is first added, and a user-assigned name. A cluster can have a linked write context alongside its read context (auth.md); otherwise each context is its own cluster.

IP addresses ​

Kinds with IPs keep the addresses of each object next to its row (IP search, the IP-aware list filter, the Pods ip column). Fields:

KindFields
Podstatus.podIPs (falls back to podIP); Multus secondary networks from k8s.v1.cni.cncf.io/network-status (non-default entries; annotations over 16 KiB skipped, at most 32). hostIP is not indexed: the Node stands in for it
Servicespec.clusterIPs (None skipped), externalIPs, loadBalancerIP, the metallb.universe.tf, metallb.io, kube-vip.io and Cilium LB-IPAM annotations, status.loadBalancer.ingress[].ip
EndpointSliceendpoints[].addresses (FQDN slices skipped)
NodeInternalIP, ExternalIP, spec.podCIDRs (falls back to podCIDR), CNI annotations (Calico, Flannel, Cilium, Kube-OVN)
Ingressstatus.loadBalancer.ingress[].ip
Gatewaystatus.addresses, spec.addresses of type IPAddress

At most 1024 tokens are kept per row.

On-demand sources (read only while an IP search needs them, see performance.md §4):

KindFields
ServiceCIDR (networking.k8s.io v1, v1beta1)spec.cidrs
MetalLB IPAddressPool (metallb.io/v1beta1)spec.addresses (CIDR or a-b, v4 and v6)
MetalLB BGPPeer (metallb.io v1beta2, v1beta1)peerAddress; sourceAddress (ranks lower)
Multus NetworkAttachmentDefinition (k8s.cni.cncf.io/v1)spec.config JSON (up to 64 KiB): host-local subnet, rangeStart/rangeEnd, ranges[][], static addresses[], whereabouts range, range_start/range_end, ipRanges[], ovn-k8s subnets, one level of conflist plugins[]; gateways rank lower. An invalid config shows invalid config and holds no addresses
CiliumLoadBalancerIPPool (cilium.io v2, v2alpha1)spec.blocks[] (cidr or start/stop) and the legacy spec.cidrs[].cidr
CiliumPodIPPool (cilium.io v2alpha1, v2)spec.ipv4.cidrs, spec.ipv6.cidrs
CiliumNode (cilium.io/v2)CiliumInternalIP addresses only (InternalIP and ExternalIP duplicate the Node), spec.ipam.podCIDRs, spec.ipam.pools.allocated[].cidrs
Calico IPPool (crd.projectcalico.org/v1)spec.cidr

Once these CRDs have curated modules, their list pages show the curated columns (including a range column) instead of printer columns. Not indexed on purpose: v1 Endpoints, networking.k8s.io IPAddress, CiliumEndpoint, Kube-OVN IP, Calico IPAMBlock and projectcalico.org/v3 (they duplicate pod, Service or pool addresses).

Resource tiers ​

Each resource type has a view spec (columns, projection, sort keys, actions, detail tabs). Types without one get the generic CRD treatment from additionalPrinterColumns.

TierMeaning
CuratedHand-written view spec: purpose-built columns, status logic, actions, detail tabs, create form or template.
Generic+Generic CRD view spec plus a status-condition reader and known actions.
GenericColumns from additionalPrinterColumns (or name/namespace/age), YAML view/edit, events, delete.

Coverage matrix ​

P1–P5 are the roadmap phases in architecture.md §Roadmap.

Core ​

ResourceTierPhaseNotable columns / actions
NamespaceCuratedP1status, labels; create, delete (type-to-confirm)
NodeCuratedP1status, roles, version, CPU/mem capacity and allocatable, pods, taints, age; cordon/uncordon (P2), drain (P2), node shell (P2)
EventCuratedP1type, reason, object, message, count, last seen, source; global stream is Warning-only; all events of one object on demand in its Events tab
PodCuratedP1ready, status reason, restarts, node, IP, age, QoS; logs, exec (P2), delete, evict, debug container (P2)
DeploymentCuratedP1ready/up-to-date/available, images, age; scale, restart, rollback (P2), pause/resume
ReplicaSetCuratedP1desired/current/ready, owner; revision history for rollback
StatefulSetCuratedP1ready, update strategy/partition; scale, restart
DaemonSetCuratedP1desired/current/ready/up-to-date/available; restart
JobCuratedP1completions, duration, status; delete with pods, logs
CronJobCuratedP1schedule (human-readable), suspend, last schedule/success; trigger now, suspend/resume
ServiceCuratedP1type, cluster IP, external IP, ports, ready endpoints, selector; port-forward (P2)
EndpointSliceCuratedP1service, ready/total endpoints
IngressCuratedP1class, hosts, paths → backends with health, TLS; open URL
IngressClassGeneric+P1
NetworkPolicyCuratedP2pod selector, ingress/egress rule summary; "pods affected"
ConfigMapCuratedP1keys, size; edit
SecretCuratedP1type, keys (values masked, reveal per key), age; metadata-only list
PersistentVolumeClaimCuratedP1status, volume, capacity, access modes, storage class, used by
PersistentVolumeCuratedP1status, claim, reclaim policy
StorageClassGeneric+P1provisioner, default, binding mode
ServiceAccountCuratedP2secrets/tokens, used by
Role, ClusterRole, RoleBinding, ClusterRoleBindingCuratedP2rule summary; "who can" view (P4)
HorizontalPodAutoscalerCuratedP2target, min/max/current, metrics
PodDisruptionBudgetCuratedP2min/max, allowed disruptions, matched pods
ResourceQuota, LimitRangeGeneric+P2usage vs hard
PriorityClass, RuntimeClassGenericP2
CustomResourceDefinitionCuratedP1group, versions, scope, instance count; jump to instances
APIServiceGeneric+P2available condition
Validating/MutatingWebhookConfiguration, ValidatingAdmissionPolicy (+Binding)Generic+P3failure policy, endpoint health
LeaseGenericP4holder (leader election debugging)
CertificateSigningRequestGeneric+P4approve/deny
VolumeAttachment, CSIDriver, CSINodeGenericP4

Gateway API and common add-ons ​

ResourceTierPhase
Gateway, GatewayClass, HTTPRoute, GRPCRoute (gateway.networking.k8s.io/v1)CuratedP3
cert-manager Certificate, Issuer, ClusterIssuer, CertificateRequestGeneric+P3
VerticalPodAutoscaler, KEDA ScaledObjectGeneric+P5
Argo CD ApplicationGeneric+ (curated later via module)P5
Cilium CiliumNetworkPolicy, CiliumClusterwideNetworkPolicyGeneric+P5 (with Hubble)

First-class integrations ​

See integrations.md. Flux and Helm in P2; Kyverno and Trivy in P3 (they feed problems); Kubescape and Hubble in P5.

Metrics ​

Node and pod CPU/memory usage come from metrics.k8s.io (metrics-server) when present: polled every 30 s, only while a visible view shows usage columns, and only for the visible window; never watched (it has no watch). Usage columns appear only when metrics are available. Prometheus integration (history, sparklines) is a P5 option, not MVP.

Generic CRD support ​

  1. Discovery via aggregated discovery (/apis with application/json;g=apidiscovery.k8s.io;v=v2;as=APIGroupDiscoveryList): one request for all groups, versions, resources, verbs, scope. Cached per cluster in the agent with ETag, refreshed on CRD/APIService watch events and every 5 minutes.
  2. Schema from the CRD's openAPIV3Schema (or /openapi/v3/apis/<group>/<version> for aggregated APIs), fetched on demand when a create/edit form or YAML completion needs it.
  3. Columns from additionalPrinterColumns, computed by the API server: generic CRDs are watched in server-side Table mode (Accept: application/json;as=Table;v=v1;g=meta.k8s.io with ?includeObject=Metadata, performance.md §4), so the agent never decodes unknown CRDs into maps. Without printer columns: name, namespace, age.
  4. Status: Table mode does not carry status.conditions. When the user enables the generic crd.not-ready problem class for a CRD group (off by default), the agent promotes that GVR to a typed-partial-JSON projection of metadata + status.conditions (mode B), which gives the generic view a Ready/Available tag.

Starred resource types and bookmarks ​

  • Starred types (requirement): any resource type, curated or CRD, can be starred from its list header or the sidebar. Starred types appear at the top of the sidebar in user order, with live counts (from the agent's per-namespace counts, summed over namespaces the user may see; only for already-watched types; others show no count rather than starting a watch).
  • Bookmarks: any object or filtered list URL can be bookmarked with a name. Bookmarks are cross-cluster aware ("this Deployment in whichever selected cluster has it").
  • Desktop stores both locally; hosted stores them per user server-side. Both export/import as JSON.

Persisted user state ​

StateDesktopHosted
Last cluster selection, cluster groupslocal settings fileuser record
Starred types, bookmarks, column layouts, problem class toggleslocal settings fileuser record
Problem acknowledgementslocaluser record
Saved port-forwardslocaln/a
Recent activityin memory, cleared on quitin memory, cleared at logout
Kubeconfig contextsthe user's kubeconfig files (read, never rewritten) plus an optional v8s-managed kubeconfig for imported clusterscluster records configured by admins

Released under the MIT License.