4 ms·

I wish their tech writers would give us more English and less jargon. I pondered these release notes and the documentation earlier today and I still can't puzz

by bt848 7y ago

I wish their tech writers would give us more English and less jargon. I pondered these release notes and the documentation earlier today and I still can't puzzle out why "custom resource" is initialized as "CRD". And the rest of this gibberish is just meaningless. """A resource is an endpoint in the Kubernetes API that stores a collection of API objects of a certain kind.""" OK, almost completely free of meaning ... then later: """A declarative API allows you to declare or specify the desired state of your resource and tries to keep the current state of Kubernetes objects in sync with the desired state.""" But wait, I thought the resource _was_ an API endpoint? The API allows me to declare the desired state of my API? I know K8s is not Borg and I know a lot of xooglers hate Borg but at least the Borg documentation was concise and made sense.

whotheffknows 7y ago
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.
jacques_chester 7y ago
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/# https://gravitational.com/blog/kubernetes-release-cycle/# (and the HN discussion at the time: https://news.ycombinator.com/item?id=16285192 https://news.ycombinator.com/item?id=16285192)
cfors 7y ago
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.
- jacques_chester 7y ago
  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".
SEJeff 7y ago
CRD is Custom Resource Definition
atombender 7y ago
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.)
- whotheffknows 7y ago
  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.
- jeffdavis 7y ago
  "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.
  - rumanator 7y ago
    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.
    - bt848 7y ago
      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?
fivre 7y ago
If nothing else, I do love another excuse to call a piece of tech "crud" all the time.
strebeld 7y ago
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.
rumanator 7y ago
Ubiquitous language is not gibberish: https://martinfowler.com/bliki/UbiquitousLanguage.html https://martinfowler.com/bliki/UbiquitousLanguage.html

by bt848 7y ago

whotheffknows 7y ago

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.

jacques_chester 7y ago

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/# https://gravitational.com/blog/kubernetes-release-cycle/# (and the HN discussion at the time: https://news.ycombinator.com/item?id=16285192 https://news.ycombinator.com/item?id=16285192)

cfors 7y ago

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.

jacques_chester 7y ago
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".

SEJeff 7y ago

CRD is Custom Resource Definition

atombender 7y ago

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.)

whotheffknows 7y ago
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.
jeffdavis 7y ago
"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.
- rumanator 7y ago
  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.
  - bt848 7y ago
    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?

fivre 7y ago

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

strebeld 7y ago

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.

rumanator 7y ago

Ubiquitous language is not gibberish: https://martinfowler.com/bliki/UbiquitousLanguage.html https://martinfowler.com/bliki/UbiquitousLanguage.html