The "Kustomization" kind should really be KustomizationBuild

[stuartpb]

kustomization.yaml files use Kustomization as their kind. In GOTK right now, that's also the name of the kind that's used to build kustomizations. This is especially confusing considering that the alternative, HelmCharts, are distinct from HelmRelease, the kind that is used to represent a build of a Helm Chart.

Ideally, it would be possible to include Kustomization documents themselves in the cluster (ie. where all of their data is either a remote URL or specified inline), and have them be maintained by operators just like HelmChart objects are now. In that scenario, it would be much tricker to work with GitOps Toolkit (from a kubectl point of view) if it's using the same Kind name to mean a different thing.

[romsnl]

I would like to add that using kustomization.yaml as filename to define a kustomization object will result in an error on the kustomization controller, it might be a good idea to mention it in the documentation as this can be confusing.

[rawkode]

Yeah, I agree with this. This was particularly confusing to me when I first came across the Kustomize controller and Kustomization resource.

Potential alternative:

• ManifestConfigController / ManifestConfig

I'll think of a few more alternatives for the next call

[stealthybox]

+1 on renaming Kustomization to something less confusing.

kustomize already has a kind: Kustomization and it means what it is literally, a customization of manifests via patches.
Flux's Kustomization overloads the Kind but it's much more about applying, pruning, RBAC, referencing a source, checking health, and waiting for dependencies.

Reading getting started guides, user questions, and blog-posts as well as watching my own videos, it seems like it's difficult to finish a paragraph about Flux's Kustomization object without sounding like you're referring to a kustomize directory.

Seems like Apply , Applier , Reconcile , or Reconciler would all be more clear?
It might be easier to express that a Reconciler or Applier supports both plain manifests and kustomizations as well since the name kustomize-controller has also been a point of confusion and fear for folks either looking for plain kubectl apply or who have had a bad taste with changing behavior in kustomize.

Let's also consider that HelmReleases are applied, configured instances of HelmCharts.
In the kustomize-controller case, we aren't using a separate term like KustomizeBuildApply, we're just calling the applied instance the term for a package of unapplied manifests.

apply-controller also happens to be a very clear name, but we could keep calling it kustomize-controller to avoid disrupting existing deployments too much.

[monotek]

The difference here is the used API.

Flux:

apiVersion: kustomize.toolkit.fluxcd.io/v1beta1

Kustomize:

apiVersion: kustomize.config.k8s.io/v1beta1

As there are many CRDs out there i guess it's not uncommon that kind could have the same name in different crds.

[stealthybox]

^ yes this is good to point out.
This isn't a hard technical limitation since the Kinds are in separate API Groups.
This is primarily a usability and understanding issue.

[stuartpb]

I know these are technically two different API groups, but it's still awkward for tooling, where you usually don't spell out the Group of a Resource, and items of a common Kind but different Group are usually semantically compatible, where items of different Groups but the same Kind can be naturally converted between the two (eg. beta's Ingress kind versus v1's Ingress kind).

If you're not caring about cross-group compatibility within the kinds, you might as well just call every kind "Resource" and give each one its own API group - there's nothing technically stopping you from doing that in the current Kubernetes model. It's only a common social contract across the community, to express analogous Kinds of document without stepping on each others' toes.

[jonaskello]

I also found having two things called Kustomization very confusing. There are a lot of yaml files in my projects and when I swtich between the many open tabs in my editor and checking the header of files I find myself in this scenario :

"Checks yaml in open tab..., ah, so this is the Kustomatization ok... swithes tab.. ah, so this is the Kustomatization.. but hang on wasn't the other file the Kustomatization ... switches tab.. ah yes, this one is the Kustomatization.... but hang on...." and so on.

I know they differ in the apiVersion field but my brain seems configured to ignore that field :-).

To me

apiVersion: kustomize.toolkit.fluxcd.io/v1beta1
kind: Kustomization
metadata:
  name: apps
  namespace: myns

looks the same as

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
metadata:
  name: apps
namespace: myns

So basically +1 for any name that is not the same as a well known native k8s kind :-).

[glerchundi]

I second this. I found it very confusing too. Trying to ellucidate what does each do and also I get messed up with both two parameters multiple times.

[Artemu]

Well, that solves that conundrum.
The overlapping name and lack of documentation to show they are different left me befuddled for quite some time. Definitely needs clarification.

[stefanprodan]

The overlapping name and lack of documentation to show they are different left me befuddled for quite some time. Definitely needs clarification.

Have you seen? https://toolkit.fluxcd.io/faq/#are-there-two-kustomization-types

[seh]

See this Slack thread in the "flux" channel of the "Cloud Native Computing Foundation" workspace for yet more confusion from these names—and a few suggestions for alternatives.

[seh]

Have you seen? https://toolkit.fluxcd.io/faq/#are-there-two-kustomization-types

That's a nice document, making this all seem so much clearer. And yet, with five minutes away from it, and with every developer who faces this system for the first time or two, we're going to suffer this confusion.

[arash-bizcover]

Extremely confusing even after a week of working with it.
If I had the emergency brake of this project, I'd pull it and change this Kind name first.

[cmd-werner-diers]

Hi all, it is indeed confusing. I came across this fluxcd/flux#3533 because as soon as I updated the apiVersion from kustomize.config.k8s.io/v1beta to kustomize.toolkit.fluxcd.io/v1beta2 flux errored out with:

kustomize build failed: Failed to read kustomization file under /tmp/infra-prerequisites759435280/infra/prerequisites:
apiVersion for Kustomization should be kustomize.config.k8s.io/v1beta

However, in the docs for the kustomization API https://fluxcd.io/docs/components/kustomize/api/ there is no mention of this https://fluxcd.io/docs/faq/#are-there-two-kustomization-types

More over, if you go here https://fluxcd.io/docs/components/kustomize/api/#kustomize.config.k8s.io/v1beta1.Kustomization

and here
https://fluxcd.io/docs/components/kustomize/api/#kustomize.toolkit.fluxcd.io/v1beta2.Kustomization

Both links redirect to the same documentation.

Thanks!!!

[qingvincentyin]

Another angle to this confusion... each resource can be in a different namespace. Now try to say:

"The Kustomization is defined in flux-system but the Kustomization is done in my-namespace."

It's like Abbott & Costello Who's On First. If you don't think that skit is funny, then you wouldn't see problems with two Kustomization.

P.S. We often encounter the same term used in two different technologies with different meanings, and there's no outcry of confusion because the technologies don't overlap. For example, a Kubernetes "cluster" is in an entirely different area of technology from a Kafka "cluster" -- in this case, the term "cluster" isn't confusing anybody. However, these two "Kustomization" refer to two very closely related things. It's like naming all your children "Bob" and claim that you can always distinguish them by their driver's license numbers anyway and therefore no confusion. On the other hand, two Bobs belonging to two different families living in two different cities will never cause confusion.

[airtonix]

If a HelmRelease creates a HelmChart, then to make it predictable - shouldn't a KustomizationRelease create a Kustomization ?

yes I necro threads without care.

[stefanprodan]

Given that Flux v2 is being used in production by many organisation, we have no intention of breaking everyones clusters by renaming a core CRD.

We could reopen this in a couple of years when we'll be designing Flux v3 😄

[rhummelmose]

@stefanprodan Great idea :D

[nick4fake]

@stefanprodan Hi, sorry for bumping this thread once again.

Firstly: I truly understand the reason behind closing this issue. It is indeed not correct to change resource names during a single major version, so your point is right.

But what do you think about extending docs? As a new Flux user I've literally already spent a few hours trying to understand the difference and how they are used, looked through multiple github issues, checked the docs page: https://fluxcd.io/flux/faq/#are-there-two-kustomization-types. I've tried googling both APIs and... For me it is still extremely confusing (I am still in re-reading loop of that docs page as it still doesn't make much sense to me, but I am trying), and I bet every new engineer might go through the same process.