Support for popular CRDs

[goenning]

Not sure how to do it though...

[craigbox]

Some brainstorming, given authorizationpolicies.security.istio.io, there are a couple of decisions to make in terms of presentation:

• use subdomain or path?
• use singular (as people use) or plural (as the CRD appears in API path)
• have a grouping for the project?

Some options:

• istio.kubespec.dev/security.istio.io/v1/authorizationpolicy (subdomain, singular name)
• kubespec.dev/istio/security.istio.io/v1/authorizationpolicies (path, plural name)
• kubespec.dev/security.istio.io/v1/authorizationpolicy (no subpath, singular name)

Any thoughts on a preference?

(Let me know how I can help get Istio's CRDs in there!)

[gecube]

I vote for kubespec.dev/security.istio.io/v1/AuthorizationPolicy

[goenning]

Yes, that’s also my preference 👍

subdomains get complicated very easily

[umutbasal]

https://doc.crds.dev/

[goenning]

I made some progress on this today. I decided to go with the subpath like kubespec.dev/istio/security.istio.io/v1/AuthorizationPolicy because that allow us to have a landing page for each project, example: https://kubespec.dev/istio

It's still a bit buggy, but we'll get there :)

For now I'm keeping the list of projects under https://github.com/aptakube/kubespec.dev/blob/main/src/lib/crds/projects.ts

[tom-butler]

@goenning this is looking really awesome! Kubespec.dev is easily the best implementation I've seen of k8s spec documentation and the way you've implemented CRD pulling makes it easily extensible too!

I'm looking at running a copy of this project internally to serve as user documentation, restricting it to just CRDs we have installed on our platform clusters to show our internal customers what things we support.

It's still a bit buggy, but we'll get there :)

I had a try at adding some extra CRDs but one thing I got caught on is that some providers e.g. Argo Rollouts have versions that don't follow semver spec e.g. 'stable', so this logic might need to be relaxed when dealing with CRDs.

  {
    name: "Argo Rollouts",
    slug: "argo-rollouts",
    logo: "https://avatars.githubusercontent.com/u/30269780?s=48&v=4",
    repo: "argoproj/argo-rollouts",
    pathToManifests: "manifests/crds",
  },

14:33:03 [ERROR] Invalid Version: stable

[goenning]

I'm looking at running a copy of this project internally to serve as user documentation, restricting it to just CRDs we have installed on our platform clusters to show our internal customers what things we support.

That’s an interesting use case, I think we could support that via environment variables where you can select which CRDs to show?

And maybe another variable to select which Kubernetes version(s) as well

14:33:03 [ERROR] Invalid Version: stable

it seems like Argo has both semver + named tags, I think we could just ignore non-semver tags? There’s an example in that list on how to ignore tags

[howardjohn]

Looks awesome! One possible suggestion for Istio is the versions are all identical in schema and will never not be identical. Might be a bit cleaner to not show the multiple copies in that regard?

For a generic non-Istio specific case, I think you can say the same for any CRD that doesn't specify crd.spec.conversion.webhook -- otherwise the API server will reject differences between versions.

[goenning]

Looks awesome! One possible suggestion for Istio is the versions are all identical in schema and will never not be identical. Might be a bit cleaner to not show the multiple copies in that regard?

These ones?

Is there any value in showing all versions at all?

I was thinking of an alternative view, something like:

[howardjohn]

There is definitely not value in having multiple entries. There may be some value in showing the list of versions, so maybe something like you have as the alternative view above.

I would think maybe even only on the detail view instead of the overview perhaps to reduce some noise, but not a big deal.

All the same can apply to https://kubespec.dev/gateway-api as well btw

[goenning]

It's live now!

Next up I need to think how to simplify the Change History, there's just too many versions 😅
I've been thinking of something like this:

Istio 1.24.1 (+3 changes)
No changes from 1.22.1 to 1.24.0
Istio 1.22.0 (+3 changes)
No changes from 1.21.5 to 1.21.6
Istio 1.21.4 (+3 changes)

[craigbox]

Do you distinguish between description/comment changes and field changes?

[goenning]

The changes we currently highlight are:

• properties added
• properties removed
• description change

But I also want to support changes to type, enum, validation and other things