core

Documentation

Overview

Package core contains schemas for a Platform and BuildPlan. Holos takes a Platform as input, then iterates over each Component to produce a BuildPlan. Holos processes the BuildPlan to produce fully rendered manifests, each an Artifact.

Index

• type Artifact
• type BuildPlan
• type BuildPlanSource
• type BuildPlanSpec
• type Chart
• type Component
• type File
• type FileContent
• type FileContentMap
• type FilePath
• type Generator
• type Helm
• type InternalLabel
• type Join
• type Kind
• type Kustomization
• type Kustomize
• type Metadata
• type Platform
• type PlatformSpec
• type Repository
• type Resource
• type Resources
• type Transformer
• type Values

Types

type Artifact

type Artifact struct {
	Artifact     FilePath      `json:"artifact,omitempty" yaml:"artifact,omitempty"`
	Generators   []Generator   `json:"generators,omitempty" yaml:"generators,omitempty"`
	Transformers []Transformer `json:"transformers,omitempty" yaml:"transformers,omitempty"`
	Skip         bool          `json:"skip,omitempty" yaml:"skip,omitempty"`
}

Artifact represents one fully rendered manifest produced by a Transformer sequence, which transforms a Generator collection. A BuildPlan produces an Artifact collection.

Each Artifact produces one manifest file artifact. Generator Output values are used as Transformer Inputs. The Output field of the final Transformer should have the same value as the Artifact field.

When there is more than one Generator there must be at least one Transformer to combine outputs into one Artifact. If there is a single Generator, it may directly produce the Artifact output.

An Artifact is processed concurrently with other artifacts in the same BuildPlan. An Artifact should not use an output from another Artifact as an input. Each Generator may also run concurrently. Each Transformer is executed sequentially starting after all generators have completed.

Output fields are write-once. It is an error for multiple Generators or Transformers to produce the same Output value within the context of a BuildPlan.

type BuildPlan

type BuildPlan struct {
	// Kind represents the type of the resource.
	Kind string `json:"kind" yaml:"kind" cue:"\"BuildPlan\""`
	// APIVersion represents the versioned schema of the resource.
	APIVersion string `json:"apiVersion" yaml:"apiVersion" cue:"string | *\"v1alpha5\""`
	// Metadata represents data about the resource such as the Name.
	Metadata Metadata `json:"metadata" yaml:"metadata"`
	// Spec specifies the desired state of the resource.
	Spec BuildPlanSpec `json:"spec" yaml:"spec"`
}

BuildPlan represents an implementation of the rendered manifest pattern. Holos processes a BuildPlan to produce one or more Artifact output files. BuildPlan artifact files usually contain Kubernetes manifests, but they may have any content.

A BuildPlan usually produces two artifacts. One artifact contains a manifest of resources. A second artifact contains a GitOps resource to manage the first, usually an ArgoCD Application resource.

Holos uses CUE to construct a BuildPlan. A future enhancement will support user defined executables providing a BuildPlan to Holos in the style of an external credential provider.

type BuildPlanSource

type BuildPlanSource struct {
	// Component reflects the component that produced the build plan.
	Component Component `json:"component,omitempty" yaml:"component,omitempty"`
}

BuildPlanSource reflects the origin of a BuildPlan. Useful to save a build plan to a file, then re-generate it without needing to process a Platform component collection.

type BuildPlanSpec

type BuildPlanSpec struct {
	// Artifacts represents the artifacts for holos to build.
	Artifacts []Artifact `json:"artifacts" yaml:"artifacts"`
	// Disabled causes the holos cli to disregard the build plan.
	Disabled bool `json:"disabled,omitempty" yaml:"disabled,omitempty"`
}

BuildPlanSpec represents the specification of the BuildPlan.

type Chart

type Chart struct {
	// Name represents the chart name.
	Name string `json:"name" yaml:"name"`
	// Version represents the chart version.
	Version string `json:"version" yaml:"version"`
	// Release represents the chart release when executing helm template.
	Release string `json:"release" yaml:"release"`
	// Repository represents the repository to fetch the chart from.
	Repository Repository `json:"repository,omitempty" yaml:"repository,omitempty"`
}

Chart represents a Helm Chart.

type Component

type Component struct {
	// Name represents the name of the component. Injected as the tag variable
	// "holos_component_name".
	Name string `json:"name" yaml:"name"`
	// Path represents the path of the component relative to the platform root.
	// Injected as the tag variable "holos_component_path".
	Path string `json:"path" yaml:"path"`
	// WriteTo represents the holos render component --write-to flag.  If empty,
	// the default value for the --write-to flag is used.
	WriteTo string `json:"writeTo,omitempty" yaml:"writeTo,omitempty"`
	// Parameters represent user defined input variables to produce various
	// [BuildPlan] resources from one component path.  Injected as CUE @tag
	// variables.  Parameters with a "holos_" prefix are reserved for use by the
	// Holos Authors.  Multiple environments are a prime example of an input
	// parameter that should always be user defined, never defined by Holos.
	Parameters map[string]string `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	// Labels represent selector labels for the component.  Copied to the
	// resulting BuildPlan.
	Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
	// Annotations represents arbitrary non-identifying metadata.  Use the
	// `cli.holos.run/description` to customize the log message of each BuildPlan.
	Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty"`
}

Component represents the complete context necessary to produce a BuildPlan from a path containing parameterized CUE configuration.

type File

type File struct {
	// Source represents a file sub-path relative to the component path.
	Source FilePath `json:"source" yaml:"source"`
}

File represents a simple single file copy Generator. Useful with a Kustomize Transformer to process plain manifest files stored in the component directory. Multiple File generators may be used to transform multiple resources.

type FileContent

type FileContent string

FileContent represents file contents.

type FileContentMap

type FileContentMap map[FilePath]FileContent

FileContentMap represents a mapping of file paths to file contents.

type FilePath

type FilePath string

FilePath represents a file path.

type Generator

type Generator struct {
	// Kind represents the kind of generator.  Must be Resources, Helm, or File.
	Kind string `json:"kind" yaml:"kind" cue:"\"Resources\" | \"Helm\" | \"File\""`
	// Output represents a file for a Transformer or Artifact to consume.
	Output FilePath `json:"output" yaml:"output"`
	// Resources generator. Ignored unless kind is Resources.  Resources are
	// stored as a two level struct.  The top level key is the Kind of resource,
	// e.g. Namespace or Deployment.  The second level key is an arbitrary
	// InternalLabel.  The third level is a map[string]any representing the
	// Resource.
	Resources Resources `json:"resources,omitempty" yaml:"resources,omitempty"`
	// Helm generator. Ignored unless kind is Helm.
	Helm Helm `json:"helm,omitempty" yaml:"helm,omitempty"`
	// File generator. Ignored unless kind is File.
	File File `json:"file,omitempty" yaml:"file,omitempty"`
}

Generator generates Kubernetes resources. Helm and Resources are the most commonly used, often paired together to mix-in resources to an unmodified Helm chart. A simple File generator is also available for use with the Kustomize transformer.

Each Generator in an Artifact must have a distinct Output value for a Transformer to reference.

1. Resources - Generates resources from CUE code.
2. Helm - Generates rendered yaml from a Chart.
3. File - Generates data by reading a file from the component directory.

type Helm

type Helm struct {
	// Chart represents a helm chart to manage.
	Chart Chart `json:"chart" yaml:"chart"`
	// Values represents values for holos to marshal into values.yaml when
	// rendering the chart.
	Values Values `json:"values" yaml:"values"`
	// EnableHooks enables helm hooks when executing the `helm template` command.
	EnableHooks bool `json:"enableHooks,omitempty" yaml:"enableHooks,omitempty"`
	// Namespace represents the helm namespace flag
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	// APIVersions represents the helm template --api-versions flag
	APIVersions []string `json:"apiVersions,omitempty" yaml:"apiVersions,omitempty"`
	// KubeVersion represents the helm template --kube-version flag
	KubeVersion string `json:"kubeVersion,omitempty" yaml:"kubeVersion,omitempty"`
}

Helm represents a Chart manifest Generator.

type InternalLabel

type InternalLabel string

InternalLabel is an arbitrary unique identifier internal to holos itself. The holos cli is expected to never write a InternalLabel value to rendered output files, therefore use a InternalLabel when the identifier must be unique and internal. Defined as a type for clarity and type checking.

type Join

type Join struct {
	Separator string `json:"separator,omitempty" yaml:"separator,omitempty"`
}

Join represents a Transformer using bytes.Join to concatenate multiple inputs into one output with a separator. Useful for combining output from Helm and Resources together into one Artifact when Kustomize is otherwise unnecessary.

type Kind

type Kind string

Kind is a discriminator. Defined as a type for clarity and type checking.

type Kustomization

type Kustomization map[string]any

Kustomization represents a kustomization.yaml file for use with the Kustomize Transformer. Untyped to avoid tightly coupling holos to kubectl versions which was a problem for the Flux maintainers. Type checking is expected to happen in CUE against the kubectl version the user prefers.

type Kustomize

type Kustomize struct {
	// Kustomization represents the decoded kustomization.yaml file
	Kustomization Kustomization `json:"kustomization" yaml:"kustomization"`
	// Files holds file contents for kustomize, e.g. patch files.
	Files FileContentMap `json:"files,omitempty" yaml:"files,omitempty"`
}

Kustomize represents a kustomization Transformer.

type Metadata

type Metadata struct {
	// Name represents the resource name.
	Name string `json:"name" yaml:"name"`
	// Labels represents a resource selector.
	Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
	// Annotations represents arbitrary non-identifying metadata.  For example
	// holos uses the `cli.holos.run/description` annotation to log resources in a
	// user customized way.
	Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty"`
}

Metadata represents data about the resource such as the Name.

type Platform

type Platform struct {
	// Kind is a string value representing the resource.
	Kind string `json:"kind" yaml:"kind" cue:"\"Platform\""`
	// APIVersion represents the versioned schema of this resource.
	APIVersion string `json:"apiVersion" yaml:"apiVersion" cue:"string | *\"v1alpha5\""`
	// Metadata represents data about the resource such as the Name.
	Metadata Metadata `json:"metadata" yaml:"metadata"`

	// Spec represents the platform specification.
	Spec PlatformSpec `json:"spec" yaml:"spec"`
}

Platform represents a platform to manage. A Platform specifies a Component collection and integrates the components together into a holistic platform. Holos iterates over the Component collection producing a BuildPlan for each, which holos then executes to render manifests.

Inspect a Platform resource holos would process by executing:

cue export --out yaml ./platform

type PlatformSpec

type PlatformSpec struct {
	// Components represents a collection of holos components to manage.
	Components []Component `json:"components" yaml:"components"`
}

PlatformSpec represents the platform specification.

type Repository

type Repository struct {
	Name string `json:"name" yaml:"name"`
	URL  string `json:"url" yaml:"url"`
}

Repository represents a Helm Chart repository.

type Resource

type Resource map[string]any

Resource represents one kubernetes api object.

type Resources

type Resources map[Kind]map[InternalLabel]Resource

Resources represents Kubernetes resources. Most commonly used to mix resources into the BuildPlan generated from CUE, but may be generated from elsewhere.

type Transformer

type Transformer struct {
	// Kind represents the kind of transformer. Must be Kustomize, or Join.
	Kind string `json:"kind" yaml:"kind" cue:"\"Kustomize\" | \"Join\""`
	// Inputs represents the files to transform. The Output of prior Generators
	// and Transformers.
	Inputs []FilePath `json:"inputs" yaml:"inputs"`
	// Output represents a file for a subsequent Transformer or Artifact to
	// consume.
	Output FilePath `json:"output" yaml:"output"`
	// Kustomize transformer. Ignored unless kind is Kustomize.
	Kustomize Kustomize `json:"kustomize,omitempty" yaml:"kustomize,omitempty"`
	// Join transformer. Ignored unless kind is Join.
	Join Join `json:"join,omitempty" yaml:"join,omitempty"`
}

Transformer combines multiple inputs from prior Generator or Transformer outputs into one output. Kustomize is the most commonly used transformer. A simple Join is also supported for use with plain manifest files.

1. Kustomize - Patch and transform the output from prior generators or transformers. See Introduction to Kustomize.
2. Join - Concatenate multiple prior outputs into one output.

type Values

type Values map[string]any

Values represents Helm Chart values generated from CUE.