Simplify explanation of system concepts

[bgrant0607]

We have lots of controllers now and lots of volume types, so it's important to explain system concepts in terms of categories of objects:

Primary:

• Running workloads: controllers, and pods they control, which are comprised of containers and volumes
• Exposing workloads: services, ingress

Secondary:

• Policies: LimitRange, ResourceQuota, PodSecurityPolicy, ...

cc @kubernetes/docs

[bgrant0607]

We should ensure the terminology is consistent across the UI and CLI, as well.
cc @bryk

[bryk]

CC @floreks @maciaszczykm

[maciaszczykm]

Last week me, @floreks, @bryk and @olekzabl have had meeting regarding categorizing resources, that we want to display in Dashboard. We've prepared a list of resources (and their members) exposed by Kubernetes API:

Namespace, pod, node, replica set, replication controller, job, deployment, daemon set, pet set, service, ingress, persistent volume claim, volume, persistent volume, resource quota, secret, limit range, service account, security context, image, horizontal pod autoscaler, label, endpoint, annotation, binding, component status, scale, event, selector, pod template, container, config map, name.

Then we've created two propositions for categorizing them.

First one contains 6 categories, second one merges two of them (policies into config):

1. Cluster, workloads, exposing workloads, storage, policies and config.
2. Cluster, workloads, exposing workloads, storage and config.

So here's ours proposal:

Resource	Description	Category	Comment
Namespace	provides support for multiple virtual clusters on the same physical cluster	cluster
Node	working machine in Kubernetes	cluster
Pod	group of one or more containers, shared storage for those containters and options how to run them	workloads
Replica set	next-generation replication controller, different selector support, rolling update by deployments	workloads
Replication controller	ensures that pods are running at any one time	workloads
Job	creates one or more pods and ensures that specified number of them terminate	workloads
Deployment	provides declarative updates for pods and replica sets	workloads
Daemon set	ensures that all (or some) nodes run a copy of a pod (as adding nodes pods are added too)	workloads
Pet set	improved stateful application support	workloads
Service	abstraction defining logical sets of pods and policy to access them, sometimes called microservice	exposing workloads
Ingress	collection of rules that allow inbound connections to reach the cluster services	exposing workloads
Persistent volume claim	request for storage by a user, similar to a pod	storage
Volume	container's storage with ability to share files between containers within same pod	storage
Persistent volume	piece of networked storage in the cluster that has been provisioned by an administrator, esource in the cluster just like a node is a cluster resource	storage
Resource quota	tool for administrators to share clusters with fixed number of nodes between users	policies (config)
Limit range		policies (config)
Service account	provides an identity for processes that run in a Pod	policies (config)
Security context	holds sensitive information, used for authentication	policies (config)
Secret	intended to hold sensitive information, such as passwords, OAuth tokens, and ssh keys	config
Pod template		config
Config map		config	not an menu item, under workload details
Label		-	not an object
Endpoint		-	should be moved to exposing workloads?
Annotation		-	not an object
Binding		-
Component status		-	shouldn't be displayed
Scale		-	the same as horizontal pod autoscaler
Event		-	add to overview page? add to resource details pages
Selector		-
Image	Docker image (currently only one supported), each container has its own image	-
Container		-
Horizontal pod autoscaler		-
Name		-

Could you please take a look and tell what you think about it? Do you agree with it or perhaps you would update it? How?

CC @kubernetes/dashboard-maintainers

[cheld]

In a DevOps team you will find a person that setup the cluster (the op guy) and the developers. In this sense I think the grouping should reflect these roles, e.g. I think security context and secret should not be in the same group as well as persistent volume and claims. I would rather group the resources to reflect the high level use cases "manage cluster" and "manage workloads" somehow.

[cheld]

CC @fwalker, @gertipoppel

[janetkuo]

cc @pwittrock

[janetkuo]

We also have a proposal for restructuring kubernetes docs. In the proposal we categorize concepts similar to your proposal, and we named "workloads" as "running workloads", "exposing workloads" as "discovering and load balancing", "config" as "configuring data".

Other categories include "obejct metadata" (label and selectors, annotations, namespaces, names), "infrastructure" (nodes, PV and PVC), "policy" (similar to yours).

We put HPA, image, container under "running workloads".

[janetkuo]

The naming of the categories is temporary now and should be either verb+ing or noun.

[bgrant0607]

It's long, but "exposing workloads" is most commonly described as:
"Service Discovery & Load Balancing"

[bgrant0607]

I'm not keen on the -ing convention.

Volume and Container are details of pods, not APIs unto themselves. Image and SecurityContext are details of a container. PodSecurityPolicy would be a policy object.

Scale and Binding are subresource APIs that won't appear in the UI, nor in user-facing docs. (They should be in developer-facing docs.) There may be a "scale" knob on some other resources, though (e.g., RCs, Deployment).

As Janet mentioned, several of the rows are metadata. Selector is a common concept, but not metadata.

Punt on component status until we start on cluster admin views.

I wouldn't make Endpoints a top-level menu item. At most, it should be a details page for a Service.

A PersistentVolume is like a Node, an infrastructure resource. It should go in the same category -- cluster.

I have a strong desire to minimize the number of categories that are relevant to end users / app developers. Given that PVC is the only "storage" resource, I propose a "Data" category that includes PVC, Secret, and ConfigMap.

PodTemplate isn't used. Don't display it.

[bgrant0607]

Maybe @erictune has a suggest about how to categorize ServiceAccount.

[bgrant0607]

@thockin says he prefers to think of PVC as storage, which would suggest Secret and ConfigMap would go into a separate Configuration category.

Or, maybe we could choose to not surface Secret and ConfigMap through the top-level menu. They are auxiliary resources.

[bgrant0607]

We still need to put Secret and ConfigMap somewhere in docs, though.

[erictune]

These categories are pretty abstract, without any description how how they are used.

I think serviceAccount is both a description (like a label or name) and a kind of config (it is a collection of secrets). I'd be fine with categorizing it as config.

[erictune]

Some upcoming objects and tentative categorization:

• ScheduledJob: creates jobs at a certain time. Sort of a periodic replication controller, so call it Workload?
• Workflow: creates jobs one after another? Workload?
• Authorization policy: (Roles, RoleBindings, ClusterRole and ClusterRoleBindings). Policy.
• PodSecurityPolicy: duh, policy.
• JobTemplate: ?

[bryk]

@janetkuo

We also have a proposal for restructuring kubernetes docs.

Is it on GitHub somewhere? From what you've described, it looks like very similar to what we've proposed here, so we could merge them.

[bryk]

@janetkuo

We put HPA, image, container under "running workloads".

I think this is what we've decided in the UI team talks, but decided that those objects do not deserve separate menu items or global listing. They are just properties of a pod/container/controller. CC @maciaszczykm

[bryk]

@janetkuo

Other categories include "obejct metadata" (label and selectors, annotations, namespaces, names), "infrastructure" (nodes, PV and PVC), "policy" (similar to yours).

1. "Object metadata": this is a category we omitted, because it is little useful from the UI perspective. In docs, it is needed though, so I agree we need it.
2. Namespaces in "Object metadata": why namespaces are here? We've put it in the "Cluster" category, since this is a global resource that you can do CRUD on.
3. "Infrastructure": how about having Nodes, PCs here? And possibly namespaces, if we change the name? Move PVC to, tentatively, "storage"

[maciaszczykm]

@janetkuo

We put HPA, image, container under "running workloads".

I think this is what we've decided in the UI team talks, but decided that those objects do not deserve separate menu items or global listing. They are just properties of a pod/container/controller. CC @maciaszczykm

@bryk Yes, it's true. We decided to put links to/information about some of the objects into details pages of another objects. We can access image details from controller page, but we do not list all images in the cluster and do not want to create separate menu entry for them.

[bryk]

@bgrant0607

I wouldn't make Endpoints a top-level menu item. At most, it should be a details page for a Service.

Yeah, makes sense. We've been thinking similar.

Volume and Container are details of pods, not APIs unto themselves. Image and SecurityContext are details of a container

Agreed. I think we should move Volume/Container/Image/SContext to categories of their owner objects.

Given that PVC is the only "storage" resource, I propose a "Data" category that includes PVC, Secret, and ConfigMap.

I like the grouping you propose, but I'm not fully satisfied with the name. "Storage" is bad for secrets and config maps, "Data" is acceptable, but generic enough to mean anything. We'll brainstorm in the UI team about other proposals.

[janetkuo]

@bryk the docs structure proposal is in Google Docs and I've cc'ed you. That was written before this UI proposal so the categories are different as expected, for example:

Namespaces in "Object metadata": why namespaces are here? We've put it in the "Cluster" category, since this is a global resource that you can do CRUD on.

This is because we didn't have "Cluster" category in docs. I plan to have the same categories in docs concept and UI (once we have a consensus). I like "Cluster"; I'll change "Infrastructure" to "Cluster" and have Nodes and namespaces there.

Not sure yet if PV should be under "Cluster" or "Storage", and if PVC should be under "Storage" or "Data" or "Cluster".

Note that not all concept in the doc will be shown in the UI.

[maciaszczykm]

@janetkuo

Other categories include "obejct metadata" (label and selectors, annotations, namespaces, names), "infrastructure" (nodes, PV and PVC), "policy" (similar to yours).

1. "Object metadata": this is a category we omitted, because it is little useful from the UI perspective. In docs, it is needed though, so I agree we need it.
2. Namespaces in "Object metadata": why namespaces are here? We've put it in the "Cluster" category, since this is a global resource that you can do CRUD on.
3. "Infrastructure": how about having Nodes, PVCs here? And possibly namespaces, if we change the name? Move PV to, tentatively, "storage"

1. Documentation is needed for "object metadata", but in my opinion we should avoid displaying it in the menu. However, we can create access to metadata in different way.
2. I agree with @bryk. From the dashboard perspective we need to create page to manage (perform CRUD operations) namespaces. It's important feature.

[maciaszczykm]

So, let's assume that we'll have following categories in the dashboard:

• Cluster - node, namespace and persistent volume.
• Workloads - pod, replica set, replication controller, job, deployment, daemon set, pet set, workflow and scheduled job.
• Service discovery and load balancing - service and ingress.
• Data - persistent volume claim, secret and config map.
• Policies - resource quota, limit range, pod security policy and service account.
• Objects not visible or accessible only from details pages - pod template, job template, scale, binding, selector, annotation, endpoint, name, component status, label, volume, security context, container, event, image and horizontal pod autoscaler.

Questions:

1. @janetkuo How does it match documentation? How can we adjust it to make it fit in your opinion? I think all categories should be the same (or at least very similar) in both places. Objects not visible or accessible only from details pages are exception, because they'll be categorized only in documentation.
2. Do you agree with category names? What about data category?
3. Do you agree with their contents?
4. Do you notice any missing resource, that should be taken into consideration here?
5. Should we display items written with italic font? Are they assigned to correct categories?
6. What should be done with authorization policies (role, role binding, cluster role and cluster role binding)? Should we display them? All in policies category?
7. @bryk Atfer applying suggestions it's a little bit different than our initial proposal. What do you think about it?

I'll try to keep above proposal up to date.

[janetkuo]

1. @janetkuo How does it match documentation? How can we adjust it to make it fit in your opinion? I think all categories should be the same (or at least very similar) in both places. Objects not visible or accessible only from details pages are exception, because they'll be categorized only in documentation.
2. Do you agree with category names? What about data category?
3. Do you agree with their contents?
4. Do you notice any missing resource, that should be taken into consideration here?
5. Should we display items written with italic font? Are they assigned to correct categories?
6. What should be done with authorization policies (role, role binding, cluster role and cluster role binding)? Should we display them? All in policies category?
7. @bryk Atfer applying suggestions it's a little bit different than our initial proposal. What do you think about it?

@maciaszczykm thanks, this proposal matches the docs well.

1. I agree on category names & contents, except for "Data"; as @bgrant0607 suggested, let's split "Data" back to "Storage" & "Config":
   Storage: PVC (+ PV details)
   Config: secrets, config maps, template, (podtemplate, jobtemplate - in docs only, not UI)
2. Yes, italic items (workflow, scheduled jobs, service accounts) and authorization policies are categorized correctly.
3. Tentative items to display: we should display workflow and scheduled jobs; I don't think we need to display service accounts and role/role bindings.

[bgrant0607]

@pwittrock I'm torn about DaemonSet. I view it as a cluster admin tool and one needs to think about Nodes in order to use it, but users rightfully see it as similar to the other controllers, which I don't think we want to fight. For now, I think it makes sense to keep it under Workloads.

[pwittrock]

If users see it as similar to other controllers, then IMHO Workloads is where it should go.

[maciaszczykm]

Current state:

• Cluster - nodes, namespaces and persistent volumes.
• Workloads - pods, replica sets, replication controllers, jobs, deployments, daemon sets, pet sets, workflows and scheduled jobs.
• Service discovery and load balancing - services and ingresses.
• Storage - persistent volume claims.
• Config - secrets and config maps.
• Policies - resource quotas, limit ranges and pod security policies.

---

• Objects not visible, not categorized or accessible only from details pages - pod templates, job templates, scales, bindings, selectors, annotations, endpoints, names, component statuses, labels, volumes, security contexts, containers, events, service accounts, images, horizontal pod autoscalers, metadata policies, third party resources, third party resources data, map reducies, pod security policy bindings, users, bindings, heartbeats, external service providers, metadata policies, pod status results, templates, raw nodes, raw pods, kube proxy configurations, subject access reviews, self subject access reviews, local subject access reviews and policies (roles, role bindings, cluster roles and cluster role bindings).

I've added objects from #20120, #8190 to last category, but it doesn't matter so much at the moment for the dashboard.

[pwittrock]

Workloads are getting a bit thick, but I am not sure there is a better option available.

[bgrant0607]

We could subdivide workloads into continuous and batch.

[pwittrock]

That might be better. Something like:

Need a home???

• pods

Continuous Workloads

• deployments
• replica sets
• replication controllers
• daemon sets
• pet sets

Run To Completion Workloads

• jobs
• scheduled jobs
• workflows

[bgrant0607]

Doc mocks:
https://docs.google.com/presentation/d/14mJwJGlwBJHIpMRGR-nYMSyyNk-kRpabyz74-YYXeTo/edit#slide=id.g12d21f53ed_2_11

[Lukenickerson]

The taxonomy-like grouping here mostly makes sense to me (as a Kubernetes novice). Two questions come to mind...

What happens to the objects that are not categorized? For the sake of documentation, will they be given a category or just "other"?

With respect to possibly using these conceptual groupings as navigation for the dashboard -- echoing both @cheld 's comment above and Material Design's navigation guide -- do we want to consider how ops and developer roles might be trying to accomplish different tasks and structure the navigation to help them best complete their tasks?

[pwittrock]

cc @johndmulhausen

@Lukenickerson Yes we want to structure navigation around roles + tasks the user is trying to accomplish. I think we do a better job of this in the non-concept sections. We should do that here as well to the extent that makes sense, but in some cases it will not. For example putting DaemonSet, Deployment and Job together in the same section. DaemonSet is typically going to be used most by folks managing the cluster itself, whereas Deployment and Job will be used typically by folks running their applications on the cluster. However conceptually they are just different ways of defining and scheduling workloads on the cluster and probably are should be logically close to one another.

Let me know if you think there are improvements we can make in this area.

What happens to the objects that are not categorized? For the sake of documentation, will they be given a category or just "other"?

Some of these are categorized for the docs now (Labels, Horizontal Pod Autoscalers). Some of these are really just part of a concept that is covered and will be covered in them (PodStatus as part of Pod). Some may or may not make sense to have a full concept for and be documented in Task pages only (Events). The docs may have more categories than the UI dashboard does.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

Prevent issues from auto-closing with an /lifecycle frozen comment.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or @fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or @fejta.
/lifecycle rotten
/remove-lifecycle stale

[bgrant0607]

This is done.