How do metadata name, labels name, and “app.kubernetes.io/name” relate to each other?

General Discussions
1

Hi

I’m trying to understand the different approaches to setting “name” (and other properties) to objects. If I look at the public documentation, I see different ways:

According to “Recommended Labels” (Recommended Labels | Kubernetes) you should use “app.kubernetes.io/name” - but examples around Pods, Deployments, Services use either “metadata → name” or “labels → name”. Also, the “metadata → name” is required, so why would you use “labels → name”?

In the example below, what effect will the different names and labels have? Will all labels without “app.kubernetes.io/” become my “own” label standard? When to use what?

apiVersion: v1
kind: Pod
metadata:
  name: my-service
  namespace: my-namespace
  labels:
    app.kubernetes.io/name: my-service
    app.kubernetes.io/version: "1.0.0"
    name: my-service
    app: my-service
    release: beta
    owner: team_blue
spec:
  containers:
    - name: my-service
      image: my-service:latest
      ports:
        - containerPort: 80

Thanks for any answers :slight_smile:

2

metadata.name is required as the “primary key” in the “database”, but it is often not human-generated (especially for Pods) so it makes a terrible “target” for things like Services.

Labels are how we do grouping and indirection. Think of it like a tight WHERE clause: SELECT * FROM pods WHERE key=val

What you put into those labels is really up to you. There is no kube-defined meaning to them. You can say “app=foobar” or “mycompany.com/app=foobar” or something else entirely.

“naked” label keys (e.g. “app”) are always reserved for end-users, and any software that YOUR OWN ORGANIZATION didn’t write should not use them.

Software which wants to use labels (or annotations) for it’s own purposes should use prefixed keys (e.g. “mycompany.com/app”) with a domain they own. It’s sort of the honor system that they do this correctly.

End users may also use prefixed keys, of course, as long as they have the authority to assert that domain.

The kubernetes project “reserves” any key that has a *.kubernetes.io or *.k8s.io prefix. We can then define common meaning to those keys as a convenience to users. Again, it’s sort of the honor system that other people don’t use those prefixes, and if we (the kube project) later decide to use it and step on someone’s toes, we won’t feel bad about it.

“app.kubernetes.io/*” is a set of labels that we have documented to have common meaning. You don’t have to use them, but if you do, other components may recognize them and be able to do smart things (e.g. draw UIs or do smart grouping). Totally optional.

1 Like
3

Thanks. This clarifies a lot.

If I would have a cluster with ~50 services, would it then be a bad or a good idea to only use “app.kubernetes.io/name” and not “name”? Or both?

4

One more question :slight_smile:

In the case of Namespace:

apiVersion: v1
kind: Namespace
metadata:
  name: corp-namespace
  labels:
    name: corp-namespace

metadata.name and labels.name will always be the same? And we only add “labels.name” for grouping or indirection? In the kubeconfig, will the “name” or the “labels.name” be used when setting a custom namespace?

5

If you want this value to be recognized as the APP name (where “app” is a larger concept than just a single resource) then you MAY use “app.kubernetes.io”. Some people define app to mean a single service+deployment+configmaps+secrets. Some use it to mean something bigger. That’s up to you.

You do not HAVE TO use it, and you MAY use both (but not sure why you would :slight_smile:

6

Labels are ONLY used for selection and grouping and should always be considered N-ary. IOW selecting all namespaces whose “name” label is “foo” could return multiple results. This is because uniqueness of label values is NOT guaranteed.

There’s one special-case for namespaces, which is that we auto-populate (and prevent mutation of) a label called “kubernetes.io/metadata.name” which is guaranteed to be the same as the metadata.name of the namespace itself.