Documentation
¶
Overview ¶
Package manifest provides helpers for Atmos configuration manifest envelopes and rendered Kubernetes-style object streams.
Index ¶
- Constants
- func ArtifactFiles(objects []*unstructured.Unstructured) (map[string][]byte, error)
- func DecodeObjects(data []byte) ([]*unstructured.Unstructured, error)
- func Detect(data []byte) (kind, apiVersion string, err error)
- func Kinds() []string
- func MultiDocumentYAML(objects []*unstructured.Unstructured) ([]byte, error)
- func MustRegister(kind, apiVersion string, specPrototype any)
- func ObjectFileName(index int, obj *unstructured.Unstructured) string
- func ObjectYAML(obj *unstructured.Unstructured) ([]byte, error)
- func Register(kind, apiVersion string, specPrototype any) error
- func Validate(kind string, data []byte) error
- func ValidateRenderOptions(options RenderOptions) error
- func WriteObjects(objects []*unstructured.Unstructured, options RenderOptions) error
- type Definition
- type LoadOption
- type LoadOptions
- type Manifest
- type Metadata
- type RenderOptions
Constants ¶
const (
// DefaultAPIVersion is the apiVersion used by all current Atmos manifests.
DefaultAPIVersion = "atmos/v1"
)
Variables ¶
This section is empty.
Functions ¶
func ArtifactFiles ¶
func ArtifactFiles(objects []*unstructured.Unstructured) (map[string][]byte, error)
ArtifactFiles builds a deterministic per-object file set (name -> YAML bytes) suitable for delivery to a provision target.
func DecodeObjects ¶
func DecodeObjects(data []byte) ([]*unstructured.Unstructured, error)
DecodeObjects decodes a multi-document YAML/JSON byte stream into a slice of unstructured objects. Embedded Kubernetes List objects are expanded into their individual items.
func Detect ¶ added in v1.224.0
Detect returns the kind and apiVersion declared by a YAML manifest without validating or decoding its spec. Use it to dispatch documents to the right kind before calling Load.
func Kinds ¶ added in v1.224.0
func Kinds() []string
Kinds returns all registered manifest kinds sorted alphabetically.
func MultiDocumentYAML ¶
func MultiDocumentYAML(objects []*unstructured.Unstructured) ([]byte, error)
MultiDocumentYAML serializes objects into a single multi-document YAML stream.
func MustRegister ¶ added in v1.224.0
MustRegister registers a manifest kind and panics on failure. Intended for package init functions where registration errors are programming errors.
func ObjectFileName ¶
func ObjectFileName(index int, obj *unstructured.Unstructured) string
ObjectFileName returns a deterministic, filesystem-safe file name for an object, prefixed with its 1-based position so ordering is preserved.
func ObjectYAML ¶
func ObjectYAML(obj *unstructured.Unstructured) ([]byte, error)
ObjectYAML serializes a single object to YAML.
func Register ¶ added in v1.224.0
Register adds a manifest kind to the registry. The spec prototype is a (typically zero-valued) instance of the kind's spec struct; its JSON Schema is generated immediately so schema errors surface at startup rather than at first load.
Re-registering an existing kind replaces it (last registration wins).
func Validate ¶ added in v1.224.0
Validate checks a YAML manifest against the registered JSON Schema for the given kind, including the envelope (apiVersion, kind, metadata).
func ValidateRenderOptions ¶
func ValidateRenderOptions(options RenderOptions) error
ValidateRenderOptions verifies the output flag combination is valid.
func WriteObjects ¶
func WriteObjects(objects []*unstructured.Unstructured, options RenderOptions) error
WriteObjects writes the rendered objects according to the resolved output mode. With no Output/OutputDir set, the multi-document YAML is written to stdout.
Types ¶
type Definition ¶ added in v1.224.0
Definition describes a registered manifest kind: its identity, the JSON Schema generated from its spec prototype, and the compiled validator.
func GetDefinition ¶ added in v1.224.0
func GetDefinition(kind string) (Definition, bool)
GetDefinition returns a copy of the definition for a registered kind. A value copy is returned so callers cannot mutate the registry's internal state.
func (*Definition) SchemaJSON ¶ added in v1.224.0
func (d *Definition) SchemaJSON() string
SchemaJSON returns the generated JSON Schema document for this kind. The schema covers the full envelope (apiVersion, kind, metadata, spec) and can be exported for IDE completion or SchemaStore publication.
func (*Definition) SpecType ¶ added in v1.224.0
func (d *Definition) SpecType() reflect.Type
SpecType returns the reflect.Type of the spec struct registered for this kind. It is the dereferenced element type of the prototype passed to Register.
type LoadOption ¶ added in v1.231.0
type LoadOption func(*LoadOptions)
LoadOption configures an optional Load behavior.
func WithIncludeResolution ¶ added in v1.231.0
func WithIncludeResolution(atmosConfig *schema.AtmosConfiguration, file string, consumedPaths *[]string) LoadOption
WithIncludeResolution enables !include/!include.raw tag resolution on the raw document tree before schema validation and decoding, so a manifest can use either tag anywhere a literal YAML value is otherwise accepted. The supplied atmosConfig provides the base path (and, for a remote target, any settings/credentials) !include's own local/remote dispatch needs; file is the nominal manifest path relative-path resolution anchors on -- only its directory matters, the file itself never needs to exist. Omitted entirely (the default for every existing Load caller), the raw bytes are decoded unchanged, exactly as before this option existed.
The consumedPaths slice, when non-nil, is appended with every tag's raw path argument exactly as written (before resolution, and regardless of whether it turns out to be local or remote) -- e.g. "./lib/regions.yaml". A caller that also enumerates a template's own local files by the same relative-path convention can intersect the two sets to find which local files exist solely to be included, never meant to be copied into generated output. A remote target's raw argument is harmless to collect too: it simply never matches anything in a local file enumeration.
type LoadOptions ¶ added in v1.231.0
type LoadOptions struct {
// contains filtered or unexported fields
}
LoadOptions holds the options a LoadOption can set on a Load call. Unexported: callers only ever construct one via a LoadOption function.
type Manifest ¶ added in v1.224.0
type Manifest[S any] struct { APIVersion string `yaml:"apiVersion" json:"apiVersion"` Kind string `yaml:"kind" json:"kind"` Metadata Metadata `yaml:"metadata" json:"metadata"` Spec S `yaml:"spec,omitempty" json:"spec,omitempty"` }
Manifest is the generic Kubernetes-style envelope shared by all Atmos manifest kinds. S is the kind-specific spec type registered for the kind.
func Load ¶ added in v1.224.0
Load parses, validates, and decodes a YAML manifest of the given kind. The document is validated against the JSON Schema generated at registration time before being decoded into the typed envelope, so a successful return guarantees a schema-valid manifest. Passing WithIncludeResolution resolves every !include/!include.raw tag in data first, so both the schema check and the final decode see the fully resolved document rather than an unprocessed tag -- see resolveIncludeTags. Omitted, data is validated and decoded unchanged, exactly as before this option existed.
The type parameter S must match the spec type registered for kind; a mismatch is rejected before decoding to prevent silently returning a zeroed or partially decoded Spec.
type Metadata ¶ added in v1.224.0
type Metadata struct {
Name string `yaml:"name" json:"name" jsonschema:"description=Unique name of this manifest,minLength=1"`
Description string `yaml:"description,omitempty" json:"description,omitempty" jsonschema:"description=Human-readable description"`
Author string `yaml:"author,omitempty" json:"author,omitempty" jsonschema:"description=Author or maintainer"`
Version string `yaml:"version,omitempty" json:"version,omitempty" jsonschema:"description=Version of this manifest"`
}
Metadata identifies a manifest, mirroring the Kubernetes object metadata convention. Name is required; the remaining fields are optional, human-oriented annotations.
type RenderOptions ¶
type RenderOptions struct {
// Output writes all objects to a single multi-document YAML file.
Output string
// OutputDir writes objects to a directory (a single manifest.yaml unless Split is set).
OutputDir string
// Split writes one file per object. Requires OutputDir.
Split bool
// Noun is the human-readable object noun used in status output (e.g. "Helm", "Kubernetes").
Noun string
// AtmosConfig controls TTY-aware syntax highlighting for stdout output.
AtmosConfig *schema.AtmosConfiguration
}
RenderOptions controls how rendered manifests are written.
Source Files