Show HN: Kubernetes Spec Explorer

kubespec.dev

216 points by goenning 7 days ago

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.

abuckenheimer 7 days ago

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.

  • Xeago 7 days ago

    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?

  • fsniper 7 days ago

    Official docs should really have a direct link to the specs from the main technical docs.

emmanueloga_ 7 days ago

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.

  • jbendotnet21 7 days ago

    k8s API is complex, a good fit for Protobuf, IMO, a poor fit for YAML.

joushx 7 days ago

Please note that kubectl also contains something similar: e.g. kubectl explain deployment.spec

fikama 7 days ago

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

robinhoodexe 7 days ago

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?

vbezhenar 7 days ago

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).
hintymad 7 days ago

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?

  • thrw42A8N 7 days ago

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

  • Atotalnoob 6 days ago

    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.

imcritic 7 days ago

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!

astonex 6 days ago

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

JohnMakin 7 days ago

This is so awesome and at a glance far better than the official documentation. Thank you!

wpm 7 days ago

This is what the official reference docs should look and work like. Well done.

  • mdaniel 7 days ago

    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 7 days ago

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

elliot07 7 days ago

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.

JeffMcCune 7 days ago

Very nice, would love to see a kubectl explain type plugin to integrate with this somehow.

nosefrog 7 days ago

Very cool! Finding the Kubernetes API docs is such a pain.

lormayna 7 days ago

Thank you! This is really really useful

swills 7 days ago

Looks very nice! Thanks!

pythops 7 days ago

Really nice, GJ !