-
Notifications
You must be signed in to change notification settings - Fork 1.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
KEP-3784: Names DB (first draft) #3787
base: master
Are you sure you want to change the base?
Conversation
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: thockin The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
2f74ea6
to
1f760a7
Compare
1f760a7
to
8aa3654
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Some thoughts
valueType: "String", | ||
resources: [ "core/nodes", core/persistentvolumes ], | ||
description: "The availability zone of the resource.", | ||
docsLink: https://kubernetes.io/docs/reference/labels-annotations-taints/#topologykubernetesiozone |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We could store just the fragment identifier, even.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If we think all docs go to the same page, sure. This is a little self-referential right now - do we generate this docs page from metadata, or do we generate this metadata from the docs, or do we demand contributors update 2 things (we know how well that works)?
I really want to hear your thougts on this specifically. The docs that exist are much more verbose than the examples I am providing here and include cross-refs and other things which might be awkward in the database text. But having 2 sources of truth is always suspect.
key: "topology.kubernetes.io/region", | ||
sig: "Architecture", | ||
context: "Label", | ||
valueType: "String", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
All labels and annotations have string values, right?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe this is an optional key to define the format of that string? (eg: valid JSON only please, or even specify a schema)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The transport type is string, but the actual value can be something else. E.g. annotation values are sometimes JSON-encoded structs. I meant this as a place to describe the "inner" type, but I see it's not clear.
Will update some text
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Watch out for whether you're defining the Kubernetes API (ie, as seen for conformance), or a particular implementation of that API.
If we change the internal implementation, could this drift?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't know of any places where that is true, off the top of my head. In general annotations are either entirely impl-specific or they are generic - impls should not use a generic name that has impl-specific payload.
Do you know of any?
Should we have a YAML per key - easier lookups and collision avoidance, but | ||
lots of files. Would maybe need Context to be a list. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Another potential home for one-file-per-key is k/website. Code that wants to could pull from the website repo and turn front matter YAML into something that other tools want to consume.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd like ONE source of truth and the rest derived from that, if possible. Secondary concern is ease of adding/updating (which is why I suggest k/k/staging). But I am open...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Website is the current source of truth - but not machine readable.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Another problem with the website is that it lags releases. In other words, main documents the last minor release. That feels like the bigger challenge.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If we put enough human-friendly text into this DB, would you want to generate the doc from it?
8aa3654
to
b31156c
Compare
## Proposal | ||
|
||
The "database" should live in a new git repo (proposed name: | ||
"kubernetes/namesdb"). In this repo we will establish a files-and-directories |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We have reserved things besides names too. eg https://github.com/kubernetes/kubernetes/blob/master/pkg/cluster/ports/ports.go. Would it be useful to step back one level and just have a generic "kubernetes reserved things" repository ("Kubernetes Assigned Numbers Authority"?), with names being one subdir and others potentially added later?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't know that ports need all the same tooling and metadata, but I agree we don't do a great job of documenting them. Would it be enough to just convert that .go file into markdown for k/website?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would it be enough to just convert that .go file into markdown for k/website?
We (SIG Docs) can also work with JSON or YAML. JSON is handy because it has a defined media type and we can do HTTP fetches.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I was not concerned specifically with ports being documented/parseable, I was just wondering if we're going to need a bigger registry later, and thinking it would be nicer to have it all in one repo rather than having both a "namesdb" and a "portsdb" and who knows what else (Kubernetes-specific IPFIX elements?)
(Though the fact that ports was the first thing that came to mind is because OpenShift does have a centralized port registry because random operators kept trying to claim the same metrics ports. But this is a bigger management problem in OpenShift because it's spread across so many repos.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ACK - I don't object to leaving room at the root for an alternate hierarchy of of data (e.g. .../names/... vs .../ports/...) with different schema.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That changes "namesdb" to ... "iddb" or "nndb" (names and numbers) or "metadb" or something?
b31156c
to
7a65d15
Compare
|
||
## Drawbacks | ||
|
||
It's YET ANOTHER thing to update. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does this make it harder to localize the label / annotation definitions?
(I think: probably it does, but it's still do-able)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great insight - yes. Perhaps we need to split the machine-data from the human-data? E.g. one of the fields in the record is a pointer the human-friendly strings which are localized and can feed docs? Ideally it would be one PR to update those - does that mean all the localized strings live in the same repo? Or do we put EN in this DB and non-EN translations are a secondary DB which is used by docs?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For the website, a common pattern is to generate [the relevant part of] the English docs using automation, and then have each localized version be generated and maintained by hand.
So the localized text would live only in k/website. I think that would work for this.
The Kubernetes project currently lacks enough contributors to adequately respond to all PRs. This bot triages PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale |
The Kubernetes project currently lacks enough contributors to adequately respond to all PRs. This bot triages PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale |
The Kubernetes project currently lacks enough active contributors to adequately respond to all PRs. This bot triages PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle rotten |
The Kubernetes project currently lacks enough contributors to adequately respond to all PRs. This bot triages PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale |
The Kubernetes project currently lacks enough contributors to adequately respond to all PRs. This bot triages PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale |
First draft of a database for kube-owned names.
Issue link: #3784