what is the difference between 'metadata.labels' and 'spec.template.metadata.labels'

Question

reading the kubernetes docs, it is not very clear to me what is the difference between specifying labels at the top-level metadata key, versus at the spec level.

Consider:

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    run: nginx
  name: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      run: nginx
  strategy: {}
  template:
    metadata:
      labels:
        run: nginxv1
    spec:
      containers:
      - image: nginx
        name: nginx

which I have copied from https://stackoverflow.com/questions/54837981/k8s-significance-of-spec-template-metadata-section , where my google searching landed me.

What's the difference between the two labels that are set in this manifest?

Answer 1

metadata.labels sets the labels that apply to the deployment.

spec.template.metadata.labels sets the labels that apply to pods management by the deployment.

The values in spec.selectors.matchLabels are used to select pods, so they need to match the labels in spec.template.metadata.labels; they have nothing to do with the Deployment's metadata.labels.