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.
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.
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?
Official docs should really have a direct link to the specs from the main technical docs.
The most frustrating part of Kubernetes (and I like k8s) is its data schema story:
* Go types are converted to Protobuf via go-to-protobuf.
* Protobuf generates OpenAPI specs and JSONSchemas via kube-openapi.
* Users rely on tools and DSLs to manage the complexity of YAML manifests.
This pipeline prioritizes some convenience for the core team over simplicity for end users. In the end, that minimal convenience transmutes into layers of convoluted code generators to maintain for the core team, and unwieldy, tens-of-thousands-of-lines schemas for the end users.
Also, does Kubernetes really benefit enough from Protobuf to justify the complexity? k8s IPC and network traffic likely account for a small fraction of overall app traffic. Perhaps JSON and schemas for validation could be enough.
The proliferation of tools to manage YAML manifests is a sign of room for improvement. Perhaps a "k8s 2.0" could start with JSONSchemas: this could encourage minimal, flat, simple, and user-friendly schemas, and hopefully a more coherent internal pipeline.
k8s API is complex, a good fit for Protobuf, IMO, a poor fit for YAML.
Please note that kubectl also contains something similar: e.g. kubectl explain deployment.spec
TIL
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...
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
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?
I think the next closest thing for CRDs is this: https://doc.crds.dev
A naive question: why does k8s require more documentation and understanding than using EC2 + EBS, if I don't have to consider cost. To set up my infrastructure, I launch clusters for my services, I map EBS or use ephemeral storage for stateful services. I use EC2's APIs to operate my clusters, such as autoscaling and auto healing. I don't have to worry about networking except probably private IP vs public IP. I barely need to spend time learning about EC2/EBS and simply use my intuitive to look up documentation when needed. Most of the EC2/EBS concepts are just intuitive. So, why do so many people say that k8s is complex and hard to get right? Shouldn't the default setup as easy as EC2+EBS, and leave the doors to more advanced stuff?
If you're so good you can intuite your way through AWS, you're good enough to do the same with K8s. It's about the same level of complexity, really. Don't listen to juniors who saw a cloud for the first time, shit the bed and went back to deploying onto something that looks more like their laptop.
Start with Minikube on Ubuntu via Snap if you want the really easy way. Deploy that on Hetzner or something using Cloud-init. Auto cluster discovery is a job for one evening. I like to use Pulumi or Terraform to see what I can play with on a cloud provider and operate it in a sane way.
And I use the K8s provider too: https://registry.terraform.io/providers/hashicorp/kubernetes...
Out of the box, k8s gives you a lot of things that you’d have to build out manually for EC2 deployed apps.
If you matched k8s features 1:1, you’d end up with a massive unwieldy beast, much more complex than k8s.
Is k8s complex? Yes, of course.
Why order of fields is different? Example:
https://kubespec.dev/apps/v1/Deployment https://kubernetes.io/docs/reference/kubernetes-api/workload...
vsminReadySeconds: integer paused: boolean progressDeadlineSeconds: integer ...
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).selector template replicas minReadySeconds ...> 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
This CLI should solve similar issues!
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!
This is great thank you. Been a k8s admin for many years but obviously still need to look up fields from time to time, and trying to find it or an example in the k8s documentation is always difficult
This is so awesome and at a glance far better than the official documentation. Thank you!
It would be great if you could paste in an existing k8s file to analyze as well. Would help for onboarding/modifying existing templates you haven't worked on in awhile, etc.
This is what the official reference docs should look and work like. Well done.
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)
>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).
Very nice, would love to see a kubectl explain type plugin to integrate with this somehow.
Very cool! Finding the Kubernetes API docs is such a pain.
Thank you! This is really really useful
Looks very nice! Thanks!
Really nice, GJ !
Nice.