{"id":21758504,"url":"https://github.com/skarlso/crd-to-sample-yaml","last_synced_at":"2026-01-16T17:46:04.944Z","repository":{"id":61794164,"uuid":"553804896","full_name":"Skarlso/crd-to-sample-yaml","owner":"Skarlso","description":"Generate a sample YAML file from a CRD and view it rendered on a nice website","archived":false,"fork":false,"pushed_at":"2024-10-18T05:21:30.000Z","size":85543,"stargazers_count":113,"open_issues_count":6,"forks_count":17,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-18T19:39:40.410Z","etag":null,"topics":["customresourcedefinition","documentation","go","golang","hacktoberfest","kubernetes","visualization","yaml"],"latest_commit_sha":null,"homepage":"https://crdtoyaml.com/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Skarlso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"Skarlso","buy_me_a_coffee":"skarlso"}},"created_at":"2022-10-18T19:54:22.000Z","updated_at":"2024-10-18T05:21:24.000Z","dependencies_parsed_at":"2023-02-16T21:15:35.071Z","dependency_job_id":"4cbb7db7-f11a-4991-81bd-4ed49221741b","html_url":"https://github.com/Skarlso/crd-to-sample-yaml","commit_stats":{"total_commits":122,"total_committers":6,"mean_commits":"20.333333333333332","dds":"0.16393442622950816","last_synced_commit":"859a8bf0c0bc2381ddb6b1b27bdcdd6a15434e1b"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Skarlso%2Fcrd-to-sample-yaml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Skarlso%2Fcrd-to-sample-yaml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Skarlso%2Fcrd-to-sample-yaml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Skarlso%2Fcrd-to-sample-yaml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Skarlso","download_url":"https://codeload.github.com/Skarlso/crd-to-sample-yaml/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247332604,"owners_count":20921853,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["customresourcedefinition","documentation","go","golang","hacktoberfest","kubernetes","visualization","yaml"],"created_at":"2024-11-26T11:22:05.917Z","updated_at":"2026-01-12T06:35:24.070Z","avatar_url":"https://github.com/Skarlso.png","language":"HTML","funding_links":["https://github.com/sponsors/Skarlso","https://buymeacoffee.com/skarlso"],"categories":[],"sub_categories":[],"readme":"# crd-to-sample-yaml or cty ( city )\n\n![logo](./imgs/cty_logo.png)\n\nGenerate a sample YAML file from a CRD definition.\n\n## Dynamic CRD Parsing on the frontend\n\n![dynamic parsing](./imgs/dynamic-editing-showcase.gif)\n\n## CRD Testing using CTY\n\nFor more information about how to use `cty` for helm-like unit testing your CRD schemas,\nplease follow the [How to test CRDs with CTY Readme](./crd-testing-README.md).\n\n![crd-unittest-sample-output](./imgs/crd-unittest-outcome.png)\n\nExample project using CTY for CRD validation: [External Secrets Operator](https://github.com/external-secrets/external-secrets/blob/main/.github/workflows/crds.yml).\n\nAnd the test locations are [here](https://github.com/external-secrets/external-secrets/tree/3a1c8b8ab51f1bc151ee33c2f555376d1a543f35/tests).\n\n## Schema validation between versions\n\nFor information on this feature, please see [Schema Validation README](SCHEMA_VALIDATION.md).\n\n## Conditions parsing with cty annotation\n\n`cty` can parse conditions and reasons from Go type definitions and render them in the HTML output.\nThe annotation to use is of the following two formats: `cty:conditions` and `cty:conditions:reason`.\n\nFor information on this feature, please see [Conditions annotation](CONDITION_ANNOTATIONS.md).\n\n## vscode extension\n\nUnder [vscode-extension](./vscode-extension) you can find an extension for CTY for vscode browser.\n\nHowever, actions and intellisense is available to generate samples for a CRD in the current window.\n\n![vscode-extension-showcase-1.png](./imgs/vscode-extension-showcase-1.png)\n\nThe extension can be installed from it's official page: [CRD To Sample YAML Extension](https://marketplace.visualstudio.com/items?itemName=GergelyBrautigam.crd-to-sample-yaml).\n\n## Getting started\n\n- Prerequisites: Go installed on your machine. (Check out this link for details: https://go.dev/doc/install)\n- Clone the repository\n- Execute `make build` to build the binary\n\nNow you can simply run:\n\n```\ncty generate crd -c delivery.krok.app_krokcommands\n```\n\nOptionally, define a URL at which a CRD is located:\n\n```\ncty generate crd -u https://raw.githubusercontent.com/kubernetes-sigs/cluster-api-provider-aws/main/config/crd/bases/infrastructure.cluster.x-k8s.io_awsclusters.yaml\n```\n\n`cty` does not support authentication modes, therefore the CRD needs to be publicly accessible.\n\nThis will result in a file similar to this:\n\n```yaml\napiVersion: delivery.krok.app/v1alpha1\nkind: KrokCommand\nmetadata: {}\nspec:\n  commandHasOutputToWrite: true\n  dependencies: [\"string\"]\n  enabled: true\n  image: string\n  platforms: [\"string\"]\n  readInputFromSecret:\n    name: string\n    namespace: string\n  schedule: string\nstatus: {}\n```\n\nA single file will be created containing all versions in the CRD delimited by `---`.\n\nOptionally, you can provide the flag `-s` which will output the generated content to `stdout`.\n\nYou can also point at a git repository to _discover_ CRDs inside the repository. Simply call `crd` with:\n\n```\n➜ cty generate crd -g https://github.com/Skarlso/crd-bootstrap\nDiscovered number of CRDs:  1\n```\n\nThe following authentication methods are available:\n- username and password\n```\n./cty generate crd -g https://github.com/Skarlso/crd-bootstrap --username skarlso --password password\n```\n- token\n```\n./cty generate crd -g https://github.com/Skarlso/crd-bootstrap --token token\n```\n- SSH with provided private key\n```\n./cty generate crd -g git@github.com:Skarlso/crd-bootstrap --private-ssh-key-file ~/.ssh/main-key\n```\n- SSH by using the local ssh-agent\n```\n./cty generate crd -g git@github.com:Skarlso/crd-bootstrap --ssh-agent\n```\n\nNotice the URL change in case SSH authentication is provided.\n\nFurther certificate bundles can be provided for privately hosted git servers with `--ca-bundle-file`.\n\n### HTML output\n\nIt's possible to generate a pre-rendered HTML based output for self-hosting what the website produces online.\n\nTo get an HTML output provide the format flag like this:\n\n```\ncty generate crd -c delivery.krok.app_krokcommands --comments --format html\n```\n\nIn case of multiple CRD files being parsed using a `folder` target, the CRDs will be listed\nin collapsed drop-down menus where their KIND is the title.\n\n![parsed3_cli](./imgs/rendered-with-folder.png)\n\n#### Custom CSS\n\nThe HTML output can be customized by providing a custom CSS file.\nTo do that, pass `--css-file` to the command like this:\n\n```console\ncty generate crd -c ./sample-crd/delivery.krok.app_krokcommands.yaml --comments --format html --css-file pkg/test-custom.css --output krok.html\n```\n\nThis way, you can customize the output however you want.\n\n### Minimal required CRD sample\n\nIt's possible to generate a sample YAML for a CRD that will make the CRD validation pass. Meaning, it will only contain\nsamples for fields that are actually required. All other fields will be ignored.\n\nFor example, a CRD having a single required field with an example and the rest being optional would generate something\nlike this:\n\n```yaml\napiVersion: delivery.krok.app/v1alpha1\nkind: KrokCommand\nspec:\n  image: \"krok-hook/slack-notification:v0.0.1\"\n```\n\nTo run cty with minimal required fields, pass in `--minimal` to the command like this:\n\n```\ncty generate crd -c delivery.krok.app_krokcommands --comments --minimal --format html\n```\n\n### Folder source\n\nTo parse multiple CRDs in a single folder, just pass in the whole folder like this:\n\n```\ncty generate crd -r folder\n```\n\nAny other flag will work as before.\n\n### Kubernetes Config\n\nUse `cty` to search for a resource in an existing Kubernetes Cluster.\n\n```\ncty generate crd -k krokcommands.delivery.krok.app\n```\n\nThis will look for this CRD in the cluster and generate a sample file for it. If you wish to use a different resource\nthat supports `openAPIV3Schema` you can configure the group/version/resource `cty` is looking for.\n\n```\ncty generate crd -k xxtstorageaccounts.crossplane.fnietoga.me --resource CompositeResourceDefinition --group apiextensions.crossplane.io --version v1\n```\n\n### Config File\n\nIt's possible to define a config file that designates groups for various rendered CRDs.\n\nTo use a config file, set the switch `--config`. A sample config file could look something like this:\n\n```yaml\napiGroups:\n  - name: \"com.aws.services\"\n    description: \"Resources related to AWS services\"\n    files: # files and folders can be defined together or on their own\n      - sample-crd/infrastructure.cluster.x-k8s.io_awsclusters.yaml\n      - sample-crd/delivery.krok.app_krokcommands\n  - name: \"com.azure.services\"\n    description: \"Resources related to Azure services\"\n    folders:\n      - azure-crds\n```\n\n\nIf no grouping information is provided, the rendered CRD's group version is used.\n\n![rendered with groups](imgs/showcase5.png)\n\nAll ways of fetching CRDs are supported through the configuration file. When dealing with URLs I recommend templating\nthis file and fetching sensitive data from elsewhere. For Git, I recommend using the local ssh-agent or a link to\nan SSH file.\n\n## Schema Generation\n\n`cty` also provides a way to generate a JSON Schema out of a CRD. Simply use:\n\n```\ncty generate schema -c sample-crd/delivery.krok.app_krokcommands.yaml\n```\n\nto target a single file. Or\n\n```\ncty generate schema -r sample-crd\n```\n\nto target a folder.\n\n## CRD Types\n\nANY kind of type can be used, not just `CustomResourceDefinitions` as long as they provide the following structure:\n\n```yaml\n# top level spec field\nspec:\n  names:\n    kind: # this should be the kind of the generated object\n  group: # the group of the generated object\n  # optional version field \n  versions:\n    - name: v1alpha1\n      # OpenAPI schema (like the one used by Kubernetes CRDs). Determines what fields\n      # the XR (and claim) will have. Will be automatically extended by crossplane.\n      # See https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/\n      # for full CRD documentation and guide on how to write OpenAPI schemas\n      schema:\n        openAPIV3Schema:\n  # optional validation field describing all versions\n  validation:\n    openAPIV3Schema:\n```\n\nIf these fields are respected, the apiVersion or the kind of the resource doesn't matter. It's all unstructured in the\nbackground.\n\n## WASM frontend\n\nThere is a WASM based frontend that can be started by navigating into the `wasm` folder and running the following make\ntarget:\n\n```shell\nmake run\n```\n\nThis will start a front-end that can be used to paste in and parse CRDs.\n\n### Diff View\n\nIf you paste in two CRDs ( or the provided content fetched from a link contains two CRDs of the same type by different versions ),\nyou can compare them by clicking on the `diff` button.\n\n![diff view](./imgs/diff-view.png)\n\n### Shareable Link\n\nIt's possible to provide a link that can be shared using a url parameter like this:\n\n```\nhttps://crdtoyaml.com/share?url=https://raw.githubusercontent.com/Skarlso/crd-to-sample-yaml/main/sample-crd/infrastructure.cluster.x-k8s.io_awsclusters.yaml\n```\n\nWill load the content, or display an appropriate error message.\n\n## Comments\n\nComments can be added to each line of the generated YAML content where descriptions are available. This looks something\nlike this:\n\n```yaml\n# 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\napiVersion: infrastructure.cluster.x-k8s.io/v1beta1\n# 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\nkind: AWSCluster\nmetadata: {}\n# AWSClusterSpec defines the desired state of an EC2-based Kubernetes cluster.\nspec:\n  # 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.\n  additionalTags: {}\n  # Bastion contains options to configure the bastion host.\n  bastion:\n  ...\n```\n\nTo add comments simply run cty with:\n```console\ncty generate -c sample-crd/infrastructure.cluster.x-k8s.io_awsclusters.yaml --comments\n```\n\nThe frontend also has a checkbox to add comments to the generated yaml output.\n\n## Templated CRDs\n\nIt's possible to provide a templated CRD like this one for flux: [Helm Controller](https://raw.githubusercontent.com/fluxcd-community/helm-charts/main/charts/flux2/templates/helm-controller.crds.yaml).\n\nIt contains template definition like:\n\n```yaml\n{{- if and .Values.installCRDs .Values.helmController.create }}\n```\n\nThese are trimmed so that the CRD parses correctly. Any values that might be in-lined are replaced with `replaced`.\nThis is done to avoid trying to parse a breaking yaml.\n\nThings like this:\n```yaml\nkind: CustomResourceDefinition\nmetadata:\n  annotations:\n    controller-gen.kubebuilder.io/version: v0.15.0\n  labels:\n    app.kubernetes.io/component: helm-controller\n    app.kubernetes.io/instance: {{ .Release.Namespace }}\n    app.kubernetes.io/managed-by: {{ .Release.Service }}\n    app.kubernetes.io/part-of: flux\n    app.kubernetes.io/version: {{ .Chart.AppVersion }}\n    helm.sh/chart: '{{ .Chart.Name }}-{{ .Chart.Version | replace \"+\" \"_\" }}'\n  name: helmreleases.helm.toolkit.fluxcd.io\n```\n\nWhere some templated value isn't escaped with `'` will create an invalid YAML that fails to parse.\n\n## Showcase\n\n![showcase1](./imgs/showcase1.png)\n![showcase2](./imgs/showcase2.png)\n![showcase3](./imgs/showcase3.png)\n![showcase4](./imgs/showcase4.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskarlso%2Fcrd-to-sample-yaml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskarlso%2Fcrd-to-sample-yaml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskarlso%2Fcrd-to-sample-yaml/lists"}