metadata.labels, selector.matchLabels, template.metadata.labels – Kubernetes Deployments Explained

There are a lot of label and selectors being placed all around deployment yaml files inside Kubernetes deployments and this gets people confused. Let me try to shed some light on this and clear your confusion.

Let’s start with an example Kubernetes Deployment configuration:

Now let’s divide this file into pieces and explain what is going on.

1- metadata.labels

Here the “labels” are used to label the deployment itself. Here, we are labeling the deployment. If we wanted to delete this deployment later, we could do so using this command:  kubectl delete -l app=nginx,tier=backend .


2- spec.selector.matchLabels

selector.matchLabels tells us how the deployment finds which pods it should be managing. Here, we simply specify a label that is given in part 3 below which is the template section for the pods. As indicated in the official Kubernetes documentation, more sophisticated selection rules are possible, as long as the Pod template itself satisfies the rule.

3- template.metadata.labels

Here we are telling which labels should be applied to the pods that are to be managed by this deployment.

To sum up,

  • We are labeling the deployment itself
  • We are specifying which pods should be managed by this Deployment object by providing a value for matchLabels
  • Finally, we are telling Kubernetes which image should be used to create the containers managed by this deployment and what labels should be associated with them.

Now, you must be asking: “We already have the labels for pods defined under “template.metadata”, why do we have to specify them also under “selector.matchLabels”? Good question!

My studies show that the usage of matchLabels depends on the version of the API you are using. For API version apps/v1beta1, usage of matchLabels is not mandatory and if not used, it will default to spec.template.metadata.labels. For API version apps/v1beta2 it’s usage is mandatory and won’t default to any labels specified inside the template section.

I am still trying to find some official Kubernetes documentation which states whether the use of this selector is mandatory or not for a specific API and better explains the reasons behind making matchLabels selector’s usage mandatory.

Edit: At the time of writing this post I was not able to find any documentation that explicitly said anything about this selector being mandatory or not.



But by looking into the code I was able to figure out if this selector was mandatory or not for a specific API. The same inspection can be done for other API versions.

For example, for this version Selector is mandatory, NOT optional. Observe the lack of  ,omitempty tag.

Edit: You can also use the “kubectl” command line tool to get information about specific tags for specific Kubernetes objects as shown below. But it seems there will be no additional information to what is already stated in the official documentation.




Hope this helps.
Good Luck,