[HN Gopher] Show HN: Kubernetes Spec Explorer
___________________________________________________________________
Show HN: Kubernetes Spec Explorer
I built an interactive explorer for Kubernetes resources spec A
few things included: - Tree view with schema, type and description
of all native resources - History changes since version X
(properties added/removed/modified) - Examples of some resources
that you can easily copy as a starting point - Supports all
versions since X, including the newly released 1.32 - I also want
to add support for popular CRD, but I'm not sure how I'll do that
yet, I'm open to suggestions! Everything is auto generated based
on the OpenAPI spec, with some manual inputs for examples and
external links. Hope you like it and if there's anything else you
think it could be useful just let me know.
Author : goenning
Score : 136 points
Date : 2024-12-12 15:02 UTC (7 hours ago)
(HTM) web link (kubespec.dev)
(TXT) w3m dump (kubespec.dev)
| robinhoodexe wrote:
| Very nice!
|
| Adding support for CRDs would be very nice. Maybe look up popular
| CNCF projects and find their official helm charts, that contain
| the CRDs?
| jzelinskie wrote:
| I think the next closest thing for CRDs is this:
| https://doc.crds.dev
| abuckenheimer wrote:
| This is really nice! The context switching that comes from using
| the [official k8s
| reference](https://kubernetes.io/docs/reference/kubernetes-
| api/workload...) is a real pain. If your writing a deployment and
| need to check one thing about the pod spec all of a sudden you
| jump to a new page and lost where you were. Ontop of that this
| keeps track of the indentation level the spec your looking at
| within the context of whatever parent path your writing it for.
|
| Maybe one nitpick would be to keep colon between the key and the
| type so one can copy paste multiple lines of relevant spec to be
| filled in your editor easily.
| fsniper wrote:
| Official docs should really have a direct link to the specs
| from the main technical docs.
| Xeago wrote:
| I find this hard-to-find official documentation so much easier
| to read:
| https://kubernetes.io/docs/reference/generated/kubernetes-ap...
|
| In my opinion, it comes with better navigation, safe to open in
| new tabs to drill-deep and unwind when done, much better use of
| horizontal space. Even though it is generated, I looks to have
| much of the exact same text?
| devops99 wrote:
| Nice.
| wpm wrote:
| This is what the official reference docs should look and work
| like. Well done.
| mdaniel wrote:
| I gravely disagree because having to click to open the
| description in the leaf nodes makes command-f not work. I would
| link to an example but it doesn't support permalinks and
| because they are all collapsed #:~:text=fieldRef doesn't work
| either
|
| This also has a UX implication because let's say one wished to
| know what values could go into envFrom[].fieldRef.fieldPath so
| they click on fieldPath to expand that node. It says,
| unhelpfully, "Path of the field to select in the specified API
| version." and then they go on HN to bitch about how complicated
| kubernetes is. When in reality they wanted to click on
| "fieldRef" itself, which coughs up "Selects a field of the pod:
| supports metadata.name, metadata.namespace,
| `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`,
| spec.nodeName, spec.serviceAccountName, status.hostIP,
| status.podIP, status.podIPs." but only if you knew to click on
| it
|
| Contrast that with
| https://kubernetes.io/docs/reference/generated/kubernetes-ap...
| (which, yes, takes 500 million years to load but _works_ )
| wpm wrote:
| >Contrast that with
|
| Ok, let's contrast.
|
| Your link does take a moment to load, _and_ it says the exact
| same thing about envFrom[].fieldRef.fieldPath as the OP 's
| site does. It takes up half browser window to do so. When I
| want to find out what the fuck an "ObjectFieldSelector" is,
| OP's site just lets me click on it inline with the keypaths
| I've already expanded to see the type definition. I can also,
| without scrolling at all, expand 'metadata' and see what keys
| are valid for that object. The generated ref docs scroll me
| to god-knows-where in some _massive_ HTML document to tell me
| that it consists of two keys, so I lose any power that
| spatial relation might give me in understanding things. I am
| admittedly a k8s scrub, but try to imagine coming at these
| docs without any muscle memory or scar tissue or experience.
| OP 's site doesn't require any "you just gotta know"'s of me,
| nor does it inexplicably wrench the structure and context
| away from the type definitions.
|
| >I would link to an example but it doesn't support permalinks
| and because they are all collapsed #:~:text=fieldRef doesn't
| work either
|
| Why would I need a hyperlink? Just give me the keypath. It's
| YAML. I can find it very quickly that way.
| Pod.containers.Container[].env.envFrom[].fieldRef.fieldPath.
| Linking me directly to "EnvVarSource v1 core" doesn't tell me
| anything except there are 4 different keys with 4 different
| types that can go in there (all huge jumps in a big ass barf
| pile of text, bye bye context). What do I do with this
| information? Where do I put this? What does it do? Your
| generated docs telegraph _none_ of that to me, a k8s scrub,
| trying to figure this crap so that I don 't have to bitch
| about how fucking complicated it is on HN. The friendlier
| docs over at https://kubernetes.io/docs/reference/kubernetes-
| api/workload... aren't much better or different. The keypath
| tells me more. This is where this goes. This is how this
| relates to the configuration. This is where put it in your
| YAML file. And if I need extra context or explanation, I just
| click on the thing I'm curious about and am immediately
| shown, with little latency, more context and explanation.
|
| Command-f can be fixed with an expand all or a search box,
| but overall I don't think a few extra clicks vs typing
| command-f, typing "EnvVarSource" in, and pressing enter are
| all that different (and one doesn't require you already know
| the type of the thing you're trying to look up).
| vbezhenar wrote:
| Why order of fields is different? Example:
|
| https://kubespec.dev/apps/v1/Deployment
| https://kubernetes.io/docs/reference/kubernetes-api/workload...
| minReadySeconds: integer paused: boolean
| progressDeadlineSeconds: integer ...
|
| vs selector template replicas
| minReadySeconds ...
|
| I'm very nitpicky about order of fields and I always follow
| kubernetes documentation order. Not sure where it really comes
| from, but generally it's good enough and better than alphabetical
| order (or inconsistent order).
| mdaniel wrote:
| > Not sure where it really comes from,
|
| It's almost certainly from the golang struct
| https://github.com/kubernetes/api/blob/v0.32.0/apps/v1/types...
| or its more succinct generated.proto friend
| https://github.com/kubernetes/api/blob/v0.32.0/apps/v1/gener...
|
| and, as you pointed out, the .dev one appears to just be
| alphabetical. In their defense, I would guess for humans that
| are looking for "paused" it's much easier to scan down to the
| "mnop" area and then look for "paused" than, lol, _guess_ where
| the paused was introduced in the timeline of a golang struct
| nosefrog wrote:
| Very cool! Finding the Kubernetes API docs is such a pain.
| JohnMakin wrote:
| This is so awesome and at a glance far better than the official
| documentation. Thank you!
| leg100 wrote:
| I like the version diffs.
|
| Perhaps add an "expand all" button to avoid clicking individually
| on properties to see their descriptions?
|
| I usually rely on the official generated docs (all on one giant
| page):
|
| https://kubernetes.io/docs/reference/generated/kubernetes-ap...
| lormayna wrote:
| Thank you! This is really really useful
| JeffMcCune wrote:
| Very nice, would love to see a kubectl explain type plugin to
| integrate with this somehow.
| swills wrote:
| Looks very nice! Thanks!
| joushx wrote:
| Please note that kubectl also contains something similar: e.g.
| kubectl explain deployment.spec
| imcritic wrote:
| If you only knew how I hate and struggle with the official docs
| and how your service is a very needed breath of fresh air! Thank
| you a lot!
| fikama wrote:
| Official Kubernetes docs are terrible. No versioning (most of the
| links on the internet are dead). A lot of text with not much
| exmaples. This one looks nice. Spec with full list of options,
| version history and examples. That's everything anyone would
| need. It reminds me of my favorite ansible documentation/spec
| which is a pleasure to use. Love it
___________________________________________________________________
(page generated 2024-12-12 23:01 UTC)