It's not gibberish, though.

A resource has an endpoint, i.e. a URL that represents its configuration and state. But a resource and its endpoint can be thought of as the same thing, in that the endpoint is the resource's canonical URI. Think REST/HATEOAS.

A resource is any object that Kubernetes can track. They include objects like services, pods, nodes, ingresses and so on. Together resources form an API.

A CRD is a Custom Resource Definition. It defines the schema and API of a custom resource (as opposed to a built-in one like "service" or "pod").

A resource is pure declarative data -- configuration and state commingled in one JSON document -- but can have behaviour associated with it.

(Confusingly, Kubernetes also uses the word "resource" to refer to compute resources like CPU and RAM. For that reason, you'll often see "object" used instead.)

"But a resource and its endpoint can be thought of as the same thing, in that the endpoint is the resource's canonical URI."

After reading your description, "a resource is an endpoint" still seems wrong. Perhaps just lazy, but laziness in technical docs gets confusing fast.

It's not laziness at all. It's the project's Ubiquitous Language, which helps refer to concepts objectively and free from ambiguities. You're complaining because you are not familiar with Kubernetes, and thus you are not the target audience. Do keep in mind you're reading the release notes of a minor release.

With respect I disagree and my objection is that this verbiage is ambiguous and imprecise, the opposite of a ubiquitous domain language. Why does the “declarative API” allow one to “declare or specify”? Which is it? Is there meaning in the clause “or specify”, or is it a superfluous verbal tic? If the API is declarative why is it called a Definition? Declaration and definition are well-used terms of art in our industry but they are not synonymous. And what about “tries to keep them in sync”? Tried by what means? Are they eventually synchronized or not?

Resource as in URI. What’s wrong about that?

Ok but ingress controllers don't talk to the kube-controller-manager though, so I wouldn't lump them in as a standard object. In fact k8s doesn't even have a standard ingress controller object.

It's a OSS project, so if there is feedback filing an issue on the docs or submitting a PR is hugely beneficial. The docs team has a single full-time technical writer and the rest is contributions from the community.

I think this will be a due to multiple authors and the curse of the expert.

Kubernetes is fairly gigantic now and continuing to spurt out in all sorts of directions, feature-wise.

"The full-time job of keeping up with Kubernetes"[0] was published in February 2018 and nothing's slowed down.

[0] https://gravitational.com/blog/kubernetes-release-cycle/# (and the HN discussion at the time: https://news.ycombinator.com/item?id=16285192)

I enjoy Kubernetes because it weeds me out from all the people who aren't used to actually having to read docs to understand the layered concepts of k8s as a networking model, of which there can be multiple opensource Implementations.

The opsys bros I know who are used to hacking together docker-composes that are more insecure than your grandmother's internet explorer browser in 30 seconds, slapping a json parsing logger on it and calling themselves geniuses fail miserably when they are left to design construct and optimise secure kubernetes clusters and elegantly port a variety of full stack web applications in a cost efficient manner.

It requires planning and design. Just because you haven't invested hundreds of hours into reading the docs and testing, and building k8s clusters for which the docs are incredibly useful doesn't mean you have to attack the verbage, just read the docs. If you can't do that then maybe your best investing your criticism into a domain of expertise you're actually knowledgeable and/or experienced in.

Also "kind" represents the type of k8s object, like service or deployment. It's not ambiguous at all, it just requires reading to the third paragraph of "general Kubernetes concepts" in the Kubernetes docs to understand it.

Both of your examples made sense to me, but when you take a step back that sentence doesn't really mean anything without context.

A "resource" === "endpoint" in the sense that the endpoint defines where you can define the configuration of a specific resource. They are being specifically vague I am assuming because of the concept of CRDs.

But without that sort of knowledge ("Hey, Kubernetes has a customizable API using custom resources!"), that sentence is rather hard to unpack.

edit: Thinking about it some more I suppose an endpoint is an overloaded term w.r.t. Pod IPs.

When you submit a CRD to Kubernetes you get a few things:

1. The CustomResourceDefinition itself, a document that tells Kubernetes "Hey, I have a kind of custom resource I want you to know about".

2. Instances of that custom resource that have been submitted to Kubernetes. "Submitted how?", you ask, which leads to:

3. When you submitted the CRD, Kubernetes automatically created HTTPS endpoints based on the values of the group, kind and version of the CRD. It accepts that custom resource at that endpoint.

What makes dealing with CRDs confusing, in my experience, is that "CRD" is used in two senses. One is the actual resource, the actual chunk of YAML submitted to Kubernetes that contains "kind: CustomResourceDefinition".

The second sense is to bundle together all the things that can be done with or flow from CRDs. Usually this is where you hear about controllers, operators and so on, but it will still be called "the Foo CRD", even though that's like referring to a 3-tier application as "the Foo table schema".

Ubiquitous language is not gibberish:

https://martinfowler.com/bliki/UbiquitousLanguage.html

If nothing else, I do love another excuse to call a piece of tech "crud" all the time.

CRD is Custom Resource Definition