FAQ example: How to patch CoreDNS and other pre-installed addons

[qingvincentyin]

Consider this section of FAQ:

• https://fluxcd.io/docs/faq/#how-to-patch-coredns-and-other-pre-installed-addons

It contains a sample yaml of how to patch an existing resource, i.e.,

---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    k8s-app: kube-dns
  annotations:
    kustomize.toolkit.fluxcd.io/prune: disabled
    kustomize.toolkit.fluxcd.io/ssa: merge
  name: coredns
  namespace: kube-system
spec:
  replicas: 5
  selector:
    matchLabels:
      eks.amazonaws.com/component: coredns
      k8s-app: kube-dns
  template:
    metadata:
      labels:
        eks.amazonaws.com/component: coredns
        k8s-app: kube-dns
    spec:
      containers: []

Except for a short (but helpful) sentence explaining .spec.containers: [], there is no explanation of why we need all the other stuff, e.g., the entire .spec.selector and .spec.template sections.

If the only thing we intend to change is the .spec.replicas field (a single numeric number 5), why do we need those other sections?

[kingdonb]

Try removing those other sections – they are also needed for the patch to work.

What do those fields all have in common?

https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#pod-template

The .spec.template and .spec.selector are the only required fields of the .spec.

The spec.containers field is also required, I don't know why it is not considered required here. Maybe it's because spec.template is a defined type (PodSpec) and it is defined there as a requirement, minimum one container per pod:

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#podspec-v1-core

(I get it now... .spec.template.spec.containers is not a field on .spec)

If you leave these things out, then your "resource" will not be valid, it should be pre-empted with a validation error, and your patch will not apply. (Did this change when the ssa: merge annotation was added as a requirement to patch/merge? If so, it would be news to me, but it could explain why you're asking... did you try removing one of these fields and it worked OK?)

[qingvincentyin]

That's very helpful explanation! I wish it was in the docs to begin with.

Yes, I had tried to do without those other sections of yaml, and failed. But I didn't know the exact minimal content that Kubernetes wants in a patch yaml (such as your example). Your sample yaml doesn't repeat the full content of those sections contained in the running manifest yaml. For example, it doesn't repeat the existing content spec.template.metadata.annotations.

Knowing what to look for now and seeing your proven sample yaml, your code kind of makes sense. But Kubernetes docs (or a quick search on the internet) doesn't have any sample code like yours (which isn't trivial at all). Prior to your answer above, it had been a mystery of exactly what I need (at the minimum) for a patch yaml. Now I know.

Thanks! We can close this issue.

[kingdonb]

it doesn't repeat the existing content spec.template.metadata.annotations.

That's right, the existing content is inferred from the existing content on the cluster, and the function of patchesStrategicMerge is a bit difficult to grapple with at first. This is the behavior that you are opting into when you set the kustomize.toolkit.fluxcd.io/ssa: merge annotation.

I'll make a PR to adjust the doc that you referenced before closing this, because I agree it's lacking some "How" and "Why"

👍