A helm plugin for generating schema and docs for chart values.

• Getting Started
• Generate Schema
• Generate Docs
• Schema Comments
• Docs Template API
  • Built-In Templates
  • Extra Templates
  • Template Context
  • Sprig Functions
  • Additional Functions
• Development Roadmap

Install the plugin: _{(signed packages coming soon)}

helm plugin install https://github.com/brahmlower/helm-values/releases/download/0.1.0/values-0.1.0.tgz

Generate your values schema:

helm values schema ./path/to/my/chart

Generate your values docs:

helm values docs ./path/to/my/chart

Options:

Generate values schema

Usage:
  helm-values schema [flags] chart_dir [...chart_dir]

Flags:
      --dry-run            don't write changes to disk
  -h, --help               help for schema
      --log-level string   log level (debug, info, warn, error, fatal, panic) (default "warn")
      --stdout             write to stdout
      --strict             fail on doc comment parsing errors
      --write-modeline     write modeline to values file (default true)

jq 'walk(if type == "object" and .description then . = . * {"markdownDescription": .description} else . end)' ./path/to/schema.values.yaml

Options:

Generate values docs

Usage:
  helm-values docs [flags] chart_dir [...chart_dir]

Flags:
      --dry-run                  don't write changes to disk
      --extra-templates string   glob path to extra templates
  -h, --help                     help for docs
      --log-level string         log level (debug, info, warn, error, fatal, panic) (default "warn")
      --markup string            markup language (md, markdown, rst, restructuredtext)
      --output string            path to output (defaults to README.md or README.rst based on markup)
      --stdout                   write to stdout
      --strict                   fail on doc comment parsing errors
      --template string          path to template (defaults to README.md.tmpl or README.rst.tmpl based on markup)
      --use-default              uses default template unless a custom template is present (default true)

This plugin simplifies schema markup in the values.yaml comments.

Comments are used as the field description by default. Multiline values are supported.

# The foo configuration for my app.
foo: qux

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "foo": {
      "type": "string",
      "title": "foo",
      "description": "The foo configuration for my app",
      "default": "qux"
    },
  }
}

If the header comment is parsable as a yaml object, it will be treated as the schema configuration.

# type: string
# minLength: 3
# maxLength: 5
# examples:
#   - foo
#   - bar
#   - bax
# description: The foo configuration for my app.
foo: qux

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "foo": {
      "type": "string",
      "title": "foo",
      "minLength": 3,
      "maxLength": 5,
      "examples": ["foo", "bar", "baz"],
      "description": "The foo configuration for my app",
      "default": "qux"
    },
  }
}

Within the header comment, the description can be provided in a second yaml document for improved readability. This is especially helpful for detailed descriptions.

# type: string
# minLength: 3
# maxLength: 5
# examples: [foo, bar, baz]
# ---
# The foo configuration for my app.
#
# Only allows [metasyntactic variable][1] names up to length 5 (excluding quuux, etc).
# Used for XYZ purposes in this fictionalized app.
#
# [1]: https://en.wikipedia.org/wiki/Metasyntactic_variable "metasyntactic variable"
foo: qux

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "foo": {
      "type": "string",
      "title": "foo",
      "minLength": 3,
      "maxLength": 5,
      "examples": ["foo", "bar", "baz"],
      "description": "The foo configuration for my app.\n\nOnly allows [metasyntactic variable][1] names up to length 5 (excluding quuux, etc).\nUsed for XYZ purposes in this fictionalized app.\n\n[1]: https://en.wikipedia.org/wiki/Metasyntactic_variable \"metasyntactic variable\"",
      "default": "qux"
    },
  }
}

The $ref and $schema properties work too, however any other jsonschema properties will be ignored (including descriptions):

# $ref: https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/v1.34.0/_definitions.json#/definitions/io.k8s.api.core.v1.ResourceRequirements
# ---
# Container resources only, recommended 1tb mem, 1,000,000 cpu
resources: {}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "resources": {
      "title": "resources",
      "$ref": "https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/v1.34.0/_definitions.json#/definitions/io.k8s.api.core.v1.ResourceRequirements"
    },
  }
}

Markdown and ReStructuredText are supported.

Built-in template names are prefixed with the markup language they support (eg: md, rst) and are provided the full TemplateContext for flexibility when being overwritten (see extra templates).

• md.header

  Document title using the chart name declared in Chart.yaml

• md.description

  Subtitle description using the description declared in Chart.yaml

• md.valuesTable

  Produces a table of values with columns for Key, Type, Default, Description.

  No multiline support.

• rst.header

  Document title using the chart name declared in Chart.yaml

• rst.description

  Subtitle description using the description declared in Chart.yaml

• rst.valuesTable

  Produces a table of values with columns for Key, Type, Default, Description.

  No multiline support.

Built-in templates can be overwritten by including extra template files!

For example, the default md.header template can be overwritten by defining a template with the same name:

{{- define "md.header" }}
# {{ .Raw.Chart.Details.Name }} - A chart by me 😎
{{- end }}

Now generate the docs and include the extra template file:

helm values docs --extra-templates ./readme-helpers.tmpl

Docs generation uses the custom template rather than the builtin.

$ head -n 2 README.md

# MyChart - A chart by me 😎

The TemplateContext and related sub-structures are defined as follows:

type TemplateContext struct {
	Raw         *RawContext
	ValuesTable []ValuesRow
}

type RawContext struct {
	Chart  *charts.Chart
	Values *jsonschema.Schema
}

type ChartDetails struct {
	Name        string
	Description string
}

type ValuesRow struct {
	Key         string
	Type        string
	Default     string
	Description string
}

Functions from sprig version 3.3.0 are available.

These are by no means considered stable, and will almost certainly change before initial stable version.

The lpad function adds space to the left until the desired length has been met:

lpad "hello" 10

The above produces hello

The lpad function adds space to the right until the desired length has been met:

rpad "hello" 10

The above produces hello

The maxLen function returns the largest length in the list of strings:

maxLen "hello" "foo" "kubernetes"

The above produces 10

Features inspired by helm-schema and helm-docs.

• 0.0.2
  • Schema Generation
    • Check/validate values file
    • Write to non-default location
    • Write to stdout
    • Update values file with yaml-schema modeline
    • Requirement: helm lint checks
    • Warn on undocumented values property
  • Docs Generation
    • Mardown & ReStructured Text support
    • Render custom and builtin templates
    • Support rich template customization
      • Sprig functions
    • "UseDefault=false" flag to require existing gotmpl
  • Helm v4 Plugin support
• 0.1.0
  • Schema Generation
    • Set examples from comments
    • Warn on ignored jsonschema property (in cases of $ref/$schema usage)
  • Docs Generation
    • Template: Table of Contents
    • Helpers for table generation
    • Support values order (preserved, alphabetical)
  • fixed bug with null values
  • fixed comment parsing with empty lines
  • fixed values rows not being in a consistent order
  • package organization overhaul
• 0.2.0
  • Pre-Commit Hook support
  • Schema Generation
    • Warn on ignored jsonschema property (in cases of $ref/$schema usage)
    • Json-Schema Draft 7 support?
    • Support declaring root level attributes
    • Objects defined in Definitions sections
  • Docs Generation
    • Template: Table of Contents
    • Helpers for table generation
    • Support "Deprecated" indicator
    • Template: Chart Values
      • Values groups
• 0.3.0
  • Schema Generation
    • Support declaring and using yaml anchors in doc comments
    • Root level one-of/any-of/all-of
  • Docs Generation
    • TODO: Detect recursive templates
    • TODO: markdown/rst escaping
• 0.4.0
  • Template: Chart Dependencies (defined in Chart.yaml)
• some day
  • validate examples against schema

Dependencies:

• go
• goreleaser
• taskfile
• helm

Building just the binaries

task build:bin

Build the binaries and plugin will require providing the --snapshot flag if you have any uncommitted git changes.

task build:plugin -- --snapshot

Bump the changelog:

release to --version $(release next --type minor) --force
git add .
git commit -m "release $(release latest)"
git tag -a "$(release latest)" -m ''