skarlso / crd-to-sample-yaml

Generate a sample YAML file from a CRD

crd-to-sample-yaml or cty ( city )

Generate a sample YAML file from a CRD definition.

Getting started

• Prerequisites: Go installed on your machine. (Check out this link for details: https://go.dev/doc/install)
• Clone the repository
• Execute make build to build the binary

Now you can simply run:

cty generate -c delivery.krok.app_krokcommands

Optionally, define a URL at which a CRD is located:

cty generate -u https://raw.githubusercontent.com/kubernetes-sigs/cluster-api-provider-aws/main/config/crd/bases/infrastructure.cluster.x-k8s.io_awsclusters.yaml

cty does not support authentication modes, therefore the CRD needs to be publicly accessible.

This will result in a file similar to this:

apiVersion: delivery.krok.app/v1alpha1
kind: KrokCommand
metadata: {}
spec:
  commandHasOutputToWrite: true
  dependencies: ["string"]
  enabled: true
  image: string
  platforms: ["string"]
  readInputFromSecret:
    name: string
    namespace: string
  schedule: string
status: {}

A single file will be created containing all versions in the CRD delimited by ---.

Optionally, you can provide the flag -s which will output the generated content to stdout.

HTML output

It's possible to generate a pre-rendered HTML based output for self-hosting what the website produces online.

To get an HTML output provide the format flag like this:

cty generate -c delivery.krok.app_krokcommands --comments --format html

Minimal required CRD sample

It's possible to generate a sample YAML for a CRD that will make the CRD validation pass. Meaning, it will only contain samples for fields that are actually required. All other fields will be ignored.

For example, a CRD having a single required field with an example and the rest being optional would generate something like this:

apiVersion: delivery.krok.app/v1alpha1
kind: KrokCommand
spec:
  image: "krok-hook/slack-notification:v0.0.1"

To run cty with minimal required fields, pass in --minimal to the command like this:

cty generate -c delivery.krok.app_krokcommands --comments --minimal --format html

Folder source

To parse multiple CRDs in a single folder, just pass in the whole folder like this:

cty generate -r folder

Any other flag will work as before.

WASM frontend

There is a WASM based frontend that can be started by navigating into the wasm folder and running the following make target:

make run

This will start a front-end that can be used to paste in and parse CRDs.

Shareable Link

It's possible to provide a link that can be shared using a url parameter like this:

https://crdtoyaml.com/share?url=https://raw.githubusercontent.com/Skarlso/crd-to-sample-yaml/main/sample-crd/infrastructure.cluster.x-k8s.io_awsclusters.yaml

Will load the content, or display an appropriate error message.

Comments

Comments can be added to each line of the generated YAML content where descriptions are available. This looks something like this:

# APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
# Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
kind: AWSCluster
metadata: {}
# AWSClusterSpec defines the desired state of an EC2-based Kubernetes cluster.
spec:
  # AdditionalTags is an optional set of tags to add to AWS resources managed by the AWS provider, in addition to the ones added by default.
  additionalTags: {}
  # Bastion contains options to configure the bastion host.
  bastion:
  ...

To add comments simply run cty with:

cty generate -c sample-crd/infrastructure.cluster.x-k8s.io_awsclusters.yaml --comments

The frontend also has a checkbox to add comments to the generated yaml output.

Templated CRDs

It's possible to provide a templated CRD like this one for flux: Helm Controller.

It contains template definition like:

{{- if and .Values.installCRDs .Values.helmController.create }}

These are trimmed so that the CRD parses correctly. Any values that might be in-lined are replaced with replaced. This is done to avoid trying to parse a breaking yaml.

Things like this:

kind: CustomResourceDefinition
metadata:
  annotations:
    controller-gen.kubebuilder.io/version: v0.15.0
  labels:
    app.kubernetes.io/component: helm-controller
    app.kubernetes.io/instance: {{ .Release.Namespace }}
    app.kubernetes.io/managed-by: {{ .Release.Service }}
    app.kubernetes.io/part-of: flux
    app.kubernetes.io/version: {{ .Chart.AppVersion }}
    helm.sh/chart: '{{ .Chart.Name }}-{{ .Chart.Version | replace "+" "_" }}'
  name: helmreleases.helm.toolkit.fluxcd.io

Where some templated value isn't escaped with ' will create an invalid YAML that fails to parse.

Showcase

Parsed Yaml output on the website:

crd-to-sample-yaml's Issues

Update showcase images in readme

URL fetch displays an error

Oops!
failed to fetch data: Get "https://github.com/Skarlso/crd-to-sample-yaml/raw/main/sample-crd/infrastructure.cluster.x-k8s.io_awsclusters.yaml": net/http: fetch() failed: TypeError: FetchEvent.respondWith received an error: TypeError: Load failed

There is a discrapancy between the CLI generated default and the web one somehow

feat: URL to CRDs definition will ignore go-template blocks

Hi,

in helm chart templates, there are usually go-template functions or blocks, and I wish to point to the CRDs definition with go-template blocks and render yaml from this file.

for example:
https://raw.githubusercontent.com/fluxcd-community/helm-charts/main/charts/flux2/templates/helm-controller.crds.yaml

{{- if and .Values.installCRDs .Values.helmController.create }}
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  annotations:
    controller-gen.kubebuilder.io/version: v0.15.0
  labels:
    app.kubernetes.io/component: helm-controller
...
...
...
    subresources:
      status: {}
{{- end }}

Now I getting error in UI

Code highlighter doesn’t highlight

Uh. No idea why.

Ability to point at a folder and parse multiple CRDs

It would be nice to just point at a folder and parse all CRDs that said folder contains.

Same for the web-app. Point at a location and fetch all yaml files from that location and parse them.

Make the collapse all and expand all buttons actually work

`bool`s and `int`s are translated with actual values

When the value type is a string or []string, it is represented in the translated yaml as "string".

When the types are bool or int, there are actual values true and 1, rather than types

Implement a nicer error handling

Right now, it just outputs the line. It should display the error on the page it is currently on.

Add sharable link to render a crd with a link

Shareable link

With the new wasm frontend I lost the shareable link feature. I should add that back somehow.

Make clipboard.js work for the YAML output on the frontend

The deployed site doesn't route the shared link

Getting a 404 once the site is deployed.

Create a YAML on the frontend

Because of how I'm parsing individual elements this might be a bit difficult, but not impossible.

The child nodes that are empty shouldn’t be accordion items

It looks weird that they can be opened up but have nothing inside.

Generate a static Typescript page from a CRD

Similar to what OpenShift Web Console does dynamically for CRDs.

Update generate -c to receive a url to some yaml

Rather than having to have a local crd, it would be cool to point to any online crd and have cty pull it for me.

(yes i alias to cty i will not type more than that)

Re-design the frontend

It's rather ugly right now. I desperately need some CSS help.

Add minimal value definition to the website.

Done

bug: minimal example lacks required metadata

Hi, sorry, I didn't saw it yesterday - was late:

apiVersion: cdaas.dp.db.de/v1alpha1
kind: KubernetesAgent
# All information for the provider
spec:
...

The minimal example lacks the required metadata XD. Even if it's not marked as required, name and namespace should be present.

how get those nice rendered website?

Hi,
could you provider some sample docs on how to generate those nice looking html for the crds? Is it possible to generate them as static files for use in github pages and so on?

I would like to generate static files for my crds - is this possible?

Something like

make static path/to/my/crd.yaml

If description is available, put that into the yaml file as comment

You should be able to turn this feature off.

Idea: add flag to generate "minimal" examples, only containing required values

I have another Idea. It would be great if there were a flag to only generate minimalistic examples, containing only flags that are required, not optional ones.

There are two use cases:

• For users we could provide minimal working examples
• We could generate Testvalues for testing defaults/unset values

feat: version command that prints the current version

Hi,
now I am trying to automate the update process of cty and there it would be great if I could check if the installed cty version is the correct one. But I didn't found any version information - so something like cty version would be great ;-)

Sorry if I have so many ideas - at the moment your tool is just the best I found for generating examples :)

Maybe I could implement this - my go is not so fluent XD

descriptions would be nice

😜

Improved Navbar

Using basic HTML and CSS
Also please consider it under hacktoberfest

Write some frigging tests

Honestly. This is embarrassing.

Have option to print output to stdout, rather than writing to a file

Add a back button once a CRD was rendered

Now, I have to refresh the page to get back which is not nice UX.

The frontend also needs a way to pass in a URL to parse

map[string]string is not recognised

Check out these renderings: https://weaveworks-liquidmetal.github.io/site/docs/guides/capmvm/#capmvm-api

metadata, failureDomains, kernelCmdKine etc are all map[string]string.

I would imaging all maps do not get translated

[Improvement] Styling updates

@Skarlso Increasing Github icon size with white color as well as add space between text-area and submit button

Kindly add it as hacktoberfest label

Do something about empty descriptions, they look weird

Create a WASM Parser and make the whole thing a static site

I'm doing this so I can host it on github pages instead of my own server.

If default value is provided use that

If the default marker is set try using that as a value.

And if there is an enum value try use one of it.

Use "example" value if provided

First of all, great tool - I really like!

At the moment the generation of examples seems to use "type", or if exists "default" as example value. It would be great if it also could parse "example" and use this, if exists.

precedence should be:

1. default
2. example
3. type

What do you think about this?

Feat: Add authentication option for cty to access private URLs

There is no real reason I guess for cty to NOT use authentication. I'll just add username / password / token for now. Then we can see about certificates or some such if there is a need.

The website probably will still not support it, but the command line tool's URL option should be able to.

Release v0.3.1 messed up the website's functionality

https://github.com/Skarlso/crd-to-sample-yaml/pull/45/files

This made the accordion no longer work. 🤔