Documentation
¶
Overview ¶
Package helmvalues renders Helm-style value templates and reads and writes the nested interface values those templates draw on.
Values are addressed by ZEP-0021 value paths: a leading dot followed by dot-separated keys, with list indices written after a key, as in .servers[0].port. A lone "." names the root.
Scalar typing follows Helm's strvals package rather than Go's own parsing rules, so a value that travels through cargoship lands in a chart as the same type it would have landed as under plain `helm --set`.
Index ¶
- func ApplyMapping(dst map[string]any, values map[string]any, source string, target string) (bool, error)
- func EvaluateValuesTemplates(v any, data any, opts ...Option) (any, error)
- func FuncMap(opts ...Option) template.FuncMap
- func GetValuePath(src map[string]any, path string) (any, bool, error)
- func LoadFiles(ctx context.Context, baseDir, tmpDir string, paths []string) (_ map[string]any, err error)
- func MergeValues(dst, src map[string]any) map[string]any
- func ParseFile(path string) (map[string]any, error)
- func RenderTemplate(tmplStr string, data any, opts ...Option) (string, error)
- func RenderValues(v any) (string, error)
- func ResolveFiles(ctx context.Context, baseDir, tmpDir string, paths []string) ([]string, error)
- func SetValuePath(dst map[string]any, path string, val any) error
- type Option
- type Schema
- type ValidationError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApplyMapping ¶
func ApplyMapping(dst map[string]any, values map[string]any, source string, target string) (bool, error)
ApplyMapping copies the value at source in values to target in dst, and reports whether values defined source at all.
A source the values do not define leaves dst untouched, so whatever dst already held stands as the default. That is what makes a mapping safe to declare for every knob a package exposes: a cluster that says nothing about one of them gets the package's own setting, not a zero value.
func EvaluateValuesTemplates ¶
EvaluateValuesTemplates recursively renders template strings inside any map or slice structure.
A string that contained a template is typed afterwards, so "{{ .Values.enabled }}" can produce a real chart boolean rather than the string "true". Typing uses Helm's scalar rules (see typedScalar) and does not interpret list syntax, so rendered output that happens to look like "[a,b]" stays a string. A string that contained no template is left exactly as the YAML decoder produced it, since it already carries its type.
func FuncMap ¶
FuncMap returns the sprig-compatible template FuncMap, minus the functions that read host state, plus the Helm serialization helpers sprig itself lacks and, with WithCreateFuncs, cargoship's own create-time helpers.
The sprig compatibility layer is used rather than a hand-picked set of sprout registries because the raw registries register none of the sprig aliases - toYaml, upper, b64enc and the rest - that Helm users expect to be able to type.
func GetValuePath ¶
GetValuePath reads the value at a Zarf Values path in src. The path must start with a dot; see valuePath. A path of "." returns src itself.
The second result reports whether the path is present. A path that runs into a scalar, a missing key, or past the end of a list is absent rather than an error, so a sourcePath a package leaves unset reads as missing instead of failing the whole mapping. Only a malformed path is an error.
func LoadFiles ¶
func LoadFiles(ctx context.Context, baseDir, tmpDir string, paths []string) (_ map[string]any, err error)
LoadFiles reads and merges every values file in paths, in order.
A later file wins over an earlier one, key by key, which is the order `helm -f a.yaml -f b.yaml` resolves in and what ZEP-0021 specifies when two sources set the same path.
A path may be a URL or a local file. A relative local path resolves against baseDir, so a package's values files are named relative to the package definition rather than to the directory cargoship was invoked from.
A URL is fetched fresh into tmpDir rather than served from the shared cache: a values file is configuration that an author edits in place, and a cached copy would silently build the package from values that have since changed. When tmpDir is empty a temporary directory is created and removed before returning; a caller that needs the downloaded copies afterwards passes its own directory, or uses ResolveFiles.
func MergeValues ¶
MergeValues returns the recursive merge of src into dst, with src winning wherever both set a key.
Neither argument is modified. Values files are merged repeatedly while composing a package, so an in-place merge would let one merge's result leak into the defaults that every later merge starts from.
Nested maps are matched by shape rather than by Go type, so a dig.Mapping or a map[any]any from a YAML decoder deep-merges with a map[string]any instead of replacing that whole branch. The result is map[string]any all the way down.
func ParseFile ¶
ParseFile reads one YAML values file from disk.
An empty file yields an empty map rather than an error, so a placeholder checked into a repository is not a build failure. A file whose top level is anything but a mapping is rejected: values are addressed by key, and a document that is a list or a bare scalar has no keys to address.
func RenderTemplate ¶
RenderTemplate evaluates a Go template string using sprig-compatible template functions.
func RenderValues ¶
RenderValues renders any value (string, map, slice, scalar) into YAML values content.
func ResolveFiles ¶
ResolveFiles turns a list of values file references into readable local paths, in the same order, downloading any that are URLs into tmpDir.
It is separate from LoadFiles so a caller that has to do something with the files themselves - copy them into a package, say - works from the same resolution rules as a caller that only wants the merged values. tmpDir is required here, since the downloaded files outlive the call.
func SetValuePath ¶
SetValuePath assigns val at a Zarf Values path within dst, creating the maps and lists along the way. The path must start with a dot; see valuePath.
A path of "." addresses the root, so val must be a map there and is merged into dst rather than replacing it. That mirrors what a targetPath of "." means for a chart: contribute these keys to the chart's values, not overwrite all of them.
Types ¶
type Option ¶
type Option func(*options)
Option adjusts which template functions are available to a render.
func WithCreateFuncs ¶
WithCreateFuncs exposes the helpers that reach the local filesystem and the network: fileExists, cachedFileExists, cachedFilePath and downloadToCache.
These belong to onCreate actions, where pulling a missing artifact into the cache is the whole point. Everywhere else - values files, manifests, files, and deploy-time actions - leave them off. A template that names one without this option fails at parse time with "function ... not defined", which is the behaviour we want: rendering a chart's values should not be able to probe the deploy host or issue HTTP requests.
ctx governs the downloads downloadToCache performs. It is taken here rather than on RenderTemplate because this option is the only thing that makes a render capable of I/O at all; a values render without it cannot block on anything and has no use for a context.
type Schema ¶
Schema is a parsed JSON schema document describing what a package's values may hold.
func LoadSchema ¶
LoadSchema reads and parses a JSON schema file.
func ParseSchema ¶
ParseSchema decodes a JSON schema document. name is used in error messages.
The schema is checked for external references and compiled here rather than at validation time, so a malformed schema fails when the package is built rather than when it is deployed.
type ValidationError ¶
type ValidationError struct {
Problems []string
}
ValidationError reports every way a set of values failed its schema.
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string
Source Files