cozyvalues-gen

cozyvalues-gen

Tiny helper that turns JSDoc-annotated values.yaml files into:

1. Go structs – strongly typed, IDE-friendly.
2. CustomResourceDefinitions (CRD) – produced by controller-gen.
3. values.schema.json – OpenAPI schema extracted from the CRD.
4. README.md – auto-updated ## Parameters section.

The chain "structs → CRD → OpenAPI" re-uses the same code that Kubernetes itself relies on, so you get maximum type compatibility for free.

Syntax Overview

Uses JSDoc-like syntax for clean, readable type annotations:

How it works

graph LR
    A[values.yaml] --> B(Go structs)
    B --> C[CRD YAML]
    C --> D[values.schema.json]
    A --> E[README.md]

• Annotate your values.yaml (see examples for the exact syntax).
• Run cozyvalues-gen; it parses the comments and spits out Go code.
• controller-gen compiles that code, emitting a CRD.
• The tool trims the CRD down to a Helm-compatible schema.

Usage (one-liner)

cozyvalues-gen \
  --values values.yaml \
  --schema values.schema.json

See cozyvalues-gen -h for all flags.

Installation

Homebrew (macOS and Linux)

brew tap cozystack/tap
brew install cozyvalues-gen

Note: This uses our incubating tap. The formula will be submitted to official homebrew/core once it reaches 75+ stars and stable adoption.

Using go install

Requires Go toolchain installed and accessible via $PATH.

go install github.com/cozystack/cozyvalues-gen@latest

The binary lands in $(go env GOPATH)/bin (usually ~/go/bin). Make sure that directory is on your $PATH.

Download a pre‑built release binary

Head over to https://github.com/cozystack/cozyvalues-gen/releases, grab the archive for your OS/arch, unpack it somewhere on your $PATH.

Annotation Tags

@param

Defines a top-level parameter:

## @param {type} name - description
## @param {string} hostname - Server hostname
hostname: "example.com"

## @param {int} replicas - Number of replicas
replicas: 3

@typedef

Defines a custom type (struct):

## @typedef {struct} Database - Database configuration
## @field {string} host - Database host
## @field {int} port - Database port

## @param {Database} database - Database config
database:
  host: localhost
  port: 5432

@field / @property

Defines fields within a typedef (@property is a synonym):

## @typedef {struct} User
## @field {string} name - User name
## @field {string} [email] - Email (optional, with omitempty)
## @field {int} age=18 - Age with default value

@enum

Defines an enumeration type:

## @enum {string} Size - Size preset
## @value small
## @value medium
## @value large

## @param {Size} size="medium" - Selected size
size: "medium"

Special Syntax

• Optional fields: [fieldName] adds omitempty to JSON tag
• Pointers: {*type} or {?type} (equivalent)
• Default values: fieldName=value or fieldName="value"

Supported value types

String-format aliases

These tokens map to a plain string field, plus format: "<alias>" in the OpenAPI schema:

Tip: use any alias exactly like a regular type, e.g.

## @param apiURL {uri} External URL of the API
apiURL: ""

Created for the Cozystack project. 🚀