---
title: Core Schemas
description: BuildPlan defines the holos rendering pipeline.
sidebar_position: 100
---
<!-- Code generated by gomarkdoc. DO NOT EDIT -->


```go
import "github.com/holos-run/holos/api/core/v1alpha6"
```

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

## Index

- [Constants](<#constants>)
- [type Artifact](<#Artifact>)
- [type Auth](<#Auth>)
- [type AuthSource](<#AuthSource>)
- [type BuildContext](<#BuildContext>)
- [type BuildPlan](<#BuildPlan>)
- [type BuildPlanSpec](<#BuildPlanSpec>)
- [type Chart](<#Chart>)
- [type Command](<#Command>)
- [type Component](<#Component>)
- [type File](<#File>)
- [type FileContent](<#FileContent>)
- [type FileContentMap](<#FileContentMap>)
- [type FileOrDirectoryPath](<#FileOrDirectoryPath>)
- [type FilePath](<#FilePath>)
- [type Generator](<#Generator>)
- [type Helm](<#Helm>)
- [type InternalLabel](<#InternalLabel>)
- [type Join](<#Join>)
- [type Kind](<#Kind>)
- [type Kustomization](<#Kustomization>)
- [type Kustomize](<#Kustomize>)
- [type Metadata](<#Metadata>)
- [type Platform](<#Platform>)
- [type PlatformSpec](<#PlatformSpec>)
- [type Repository](<#Repository>)
- [type Resource](<#Resource>)
- [type Resources](<#Resources>)
- [type Transformer](<#Transformer>)
- [type Validator](<#Validator>)
- [type ValueFile](<#ValueFile>)
- [type Values](<#Values>)


## Constants

<a name="BuildContextTag"></a>BuildContextTag represents the cue tag holos render component uses to inject the json representation of a [BuildContext](<#BuildContext>) for use in a BuildPlan.

```go
const BuildContextTag string = "holos_build_context"
```

<a name="ComponentAnnotationsTag"></a>ComponentAnnotationsTag represents the tag holos uses to inject the json representation of [Component](<#Component>) metadata annotations from the holos render platform command to the holos render component command.

```go
const ComponentAnnotationsTag = "holos_component_annotations"
```

<a name="ComponentLabelsTag"></a>ComponentLabelsTag represents the cue tag holos uses to inject the json representation of [Component](<#Component>) metadata labels from the holos render platform command to the holos render component command.

```go
const ComponentLabelsTag string = "holos_component_labels"
```

<a name="ComponentNameTag"></a>ComponentNameTag represents the cue tag holos uses to inject a [Component](<#Component>) name from the holos render platform command to the holos render component command.

```go
const ComponentNameTag string = "holos_component_name"
```

<a name="ComponentPathTag"></a>ComponentPathTag represents the cue tag holos uses to inject a [Component](<#Component>) path relative to the cue module root from the holos render platform command to the holos render component command.

```go
const ComponentPathTag string = "holos_component_path"
```

<a name="Artifact"></a>
## type Artifact {#Artifact}

Artifact represents one fully rendered manifest produced by a [Transformer](<#Transformer>) sequence, which transforms a [Generator](<#Generator>) collection. A [BuildPlan](<#BuildPlan>) produces an [Artifact](<#Artifact>) collection.

Each Artifact produces one manifest file or directory artifact. Generator Output values are used as Transformer Inputs. The Output field of the final [Transformer](<#Transformer>) should have the same value as the Artifact field.

When there is more than one [Generator](<#Generator>) there should be at least one [Transformer](<#Transformer>) to combine outputs into one Artifact file, or the final artifact should be a directory containing the outputs of the generators. 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](<#BuildPlan>). One Artifact must not use an output of another Artifact as an input. Each [Generator](<#Generator>) within an artifact also runs concurrently with generators of the same artifact. Each [Transformer](<#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](<#BuildPlan>).

When directories are used as inputs or outputs, they behave similar to how \`git\` works with directories. When the output field references a directory, all files within the directory are recursively stored using their relative path as a key. Similar to git add . When the input field references an absent file, a / is appended and the resulting value is used as a prefix match against all previous task outputs.

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

<a name="Auth"></a>
## type Auth {#Auth}

Auth represents environment variable names containing auth credentials.

```go
type Auth struct {
    Username AuthSource `json:"username" yaml:"username"`
    Password AuthSource `json:"password" yaml:"password"`
}
```

<a name="AuthSource"></a>
## type AuthSource {#AuthSource}

AuthSource represents a source for the value of an [Auth](<#Auth>) field.

```go
type AuthSource struct {
    Value   string `json:"value,omitempty" yaml:"value,omitempty"`
    FromEnv string `json:"fromEnv,omitempty" yaml:"fromEnv,omitempty"`
}
```

<a name="BuildContext"></a>
## type BuildContext {#BuildContext}

BuildContext represents build context values owned by the holos render component command. End users should not manage context field values. End users may reference fields from within CUE to refer to late binding concrete values defined just before holos executes a [BuildPlan](<#BuildPlan>).

Holos injects build context values by marshalling this struct to json through the holos\_build\_context cue tag.

Example usage from cue to produce a [BuildPlan](<#BuildPlan>):

```
package holos

import (
  "encoding/json"
  "github.com/holos-run/holos/api/core/v1alpha6:core"
)

_BuildContextJSON: string | *"{}" @tag(holos_build_context, type=string)
BuildContext: core.#BuildContext & json.Unmarshal(_BuildContextJSON)

holos: core.#BuildPlan & {
  buildContext: BuildContext
  "spec": {
    "artifacts": [
      {
        artifact: "components/slice",
        "transformers": [
          {
            "kind": "Command"
            "inputs": ["resources.gen.yaml"]
            "output": artifact
            "command": {
              "args": [
                "kubectl-slice",
                "-f",
                "\(buildContext.tempDir)/resources.gen.yaml",
                "-o",
                "\(buildContext.tempDir)/\(artifact)",
              ]
            }
          }
        ]
      }
    ]
  }
}
```

```go
type BuildContext struct {
    // TempDir represents the temporary directory managed and owned by the holos
    // render component command for the execution of one BuildPlan.  Multiple
    // tasks in the build plan share this temporary directory and therefore should
    // avoid reading and writing into the same sub-directories as one another.
    TempDir string `json:"tempDir" yaml:"tempDir" cue:"string | *\"${TEMP_DIR_PLACEHOLDER}\""`
    // RootDir represents the fully qualified path to the platform root directory.
    // Useful to construct arguments for commands in BuildPlan tasks.
    RootDir string `json:"rootDir" yaml:"rootDir" cue:"string | *\"${ROOT_DIR_PLACEHOLDER}\""`
    // LeafDir represents the cleaned path to the holos component relative to the
    // platform root.  Useful to construct arguments for commands in BuildPlan
    // tasks.
    LeafDir string `json:"leafDir" yaml:"leafDir" cue:"string | *\"${LEAF_DIR_PLACEHOLDER}\""`
    // HolosExecutable represents the fully qualified path to the holos
    // executable.  Useful to execute tools embedded as subcommands such as holos
    // cue vet.
    HolosExecutable string `json:"holosExecutable" yaml:"holosExecutable" cue:"string | *\"holos\""`
}
```

<a name="BuildPlan"></a>
## type BuildPlan {#BuildPlan}

BuildPlan represents an implementation of the [rendered manifest pattern](<https://akuity.io/blog/the-rendered-manifests-pattern>). Holos processes a BuildPlan to produce one or more [Artifact](<#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. Holos injects late binding values such as the build temp dir using the [BuildContext](<#BuildContext>).

```go
type BuildPlan struct {
    // APIVersion represents the versioned schema of the resource.
    APIVersion string `json:"apiVersion" yaml:"apiVersion" cue:"\"v1alpha6\""`
    // Kind represents the type of the resource.
    Kind string `json:"kind" yaml:"kind" cue:"\"BuildPlan\""`
    // 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"`
    // BuildContext represents values injected by holos just before evaluating a
    // BuildPlan, for example the tempDir used for the build.
    BuildContext BuildContext `json:"buildContext" yaml:"buildContext"`
}
```

<a name="BuildPlanSpec"></a>
## type BuildPlanSpec {#BuildPlanSpec}

BuildPlanSpec represents the specification of the [BuildPlan](<#BuildPlan>).

```go
type BuildPlanSpec struct {
    // Artifacts represents the artifacts for holos to build.
    Artifacts []Artifact `json:"artifacts" yaml:"artifacts"`
    // Disabled causes the holos render platform command to skip the BuildPlan.
    Disabled bool `json:"disabled,omitempty" yaml:"disabled,omitempty"`
}
```

<a name="Chart"></a>
## type Chart {#Chart}

Chart represents a [Helm](<#Helm>) Chart.

```go
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"`
}
```

<a name="Command"></a>
## type Command {#Command}

Command represents a [BuildPlan](<#BuildPlan>) task implemented by executing an user defined system command. A task is defined as a [Generator](<#Generator>), [Transformer](<#Transformer>), or [Validator](<#Validator>). Commands are executed with the working directory set to the platform root.

```go
type Command struct {
    // DisplayName of the command.  The basename of args[0] is used if empty.
    DisplayName string `json:"displayName,omitempty" yaml:"displayName,omitempty"`
    // Args represents the argument vector passed to the os. to execute the
    // command.
    Args []string `json:"args,omitempty" yaml:"args,omitempty"`
    // IsStdoutOutput captures the command stdout as the task output if true.
    IsStdoutOutput bool `json:"isStdoutOutput,omitempty" yaml:"isStdoutOutput,omitempty"`
}
```

<a name="Component"></a>
## type Component {#Component}

Component represents the complete context necessary to produce a [BuildPlan](<#BuildPlan>) from a path containing parameterized CUE configuration.

```go
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"`
    // 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.  Holos copies Labels
    // from the Component to the resulting BuildPlan.
    Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
    // Annotations represents arbitrary non-identifying metadata.  Use the
    // `app.holos.run/description` to customize the log message of each BuildPlan.
    Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty"`
}
```

<a name="File"></a>
## type File {#File}

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

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

<a name="FileContent"></a>
## type FileContent {#FileContent}

FileContent represents file contents.

```go
type FileContent string
```

<a name="FileContentMap"></a>
## type FileContentMap {#FileContentMap}

FileContentMap represents a mapping of file paths to file contents.

```go
type FileContentMap map[FilePath]FileContent
```

<a name="FileOrDirectoryPath"></a>
## type FileOrDirectoryPath {#FileOrDirectoryPath}

FileOrDirectoryPath represents a file or a directory path.

```go
type FileOrDirectoryPath string
```

<a name="FilePath"></a>
## type FilePath {#FilePath}

FilePath represents a file path.

```go
type FilePath string
```

<a name="Generator"></a>
## type Generator {#Generator}

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

Each Generator in an [Artifact](<#Artifact>) must have a distinct Output value for a [Transformer](<#Transformer>) to reference.

1. [Resources](<#Resources>) \- Generates resources from CUE code.
2. [Helm](<#Helm>) \- Generates rendered yaml from a [Chart](<#Chart>).
3. [File](<#File>) \- Generates data by reading a file from the component directory.
4. [Command](<#Command>) \- Generates data by executing an user defined command.

```go
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\" | \"Command\""`
    // Output represents a file for a Transformer or Artifact to consume.
    Output FileOrDirectoryPath `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"`
    // Command generator. Ignored unless kind is Command.
    Command Command `json:"command,omitempty" yaml:"command,omitempty"`
}
```

<a name="Helm"></a>
## type Helm {#Helm}

Helm represents a [Chart](<#Chart>) manifest [Generator](<#Generator>).

```go
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 follow ValueFiles when both are provided.
    Values Values `json:"values" yaml:"values"`
    // ValueFiles represents hierarchial value files passed in order to the helm
    // template -f flag.  Useful for migration from an ApplicationSet.  Use Values
    // instead.  ValueFiles precede Values when both are provided.
    ValueFiles []ValueFile `json:"valueFiles,omitempty" yaml:"valueFiles,omitempty"`
    // 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"`
}
```

<a name="InternalLabel"></a>
## type InternalLabel {#InternalLabel}

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.

```go
type InternalLabel string
```

<a name="Join"></a>
## type Join {#Join}

Join represents a [Transformer](<#Transformer>) using [bytes.Join](<https://pkg.go.dev/bytes#Join>) to concatenate multiple inputs into one output with a separator. Useful for combining output from [Helm](<#Helm>) and [Resources](<#Resources>) together into one [Artifact](<#Artifact>) when [Kustomize](<#Kustomize>) is otherwise unnecessary.

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

<a name="Kind"></a>
## type Kind {#Kind}

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

```go
type Kind string
```

<a name="Kustomization"></a>
## type Kustomization {#Kustomization}

Kustomization represents a kustomization.yaml file for use with the [Kustomize](<#Kustomize>) [Transformer](<#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.

```go
type Kustomization map[string]any
```

<a name="Kustomize"></a>
## type Kustomize {#Kustomize}

Kustomize represents a kustomization [Transformer](<#Transformer>).

```go
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"`
}
```

<a name="Metadata"></a>
## type Metadata {#Metadata}

Metadata represents data about the resource such as the Name.

```go
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 `app.holos.run/description` annotation to log resources in a
    // user customized way.
    Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty"`
}
```

<a name="Platform"></a>
## type Platform {#Platform}

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

Inspect a Platform resource holos would process by executing:

```
cue export --out yaml ./platform
```

```go
type Platform struct {
    // APIVersion represents the versioned schema of this resource.
    APIVersion string `json:"apiVersion" yaml:"apiVersion" cue:"string | *\"v1alpha6\""`
    // Kind is a string value representing the resource.
    Kind string `json:"kind" yaml:"kind" cue:"\"Platform\""`
    // 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"`
}
```

<a name="PlatformSpec"></a>
## type PlatformSpec {#PlatformSpec}

PlatformSpec represents the platform specification.

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

<a name="Repository"></a>
## type Repository {#Repository}

Repository represents a [Helm](<#Helm>) [Chart](<#Chart>) repository.

The Auth field is useful to configure http basic authentication to the Helm repository. Holos gets the username and password from the environment variables represented by the Auth field.

```go
type Repository struct {
    Name string `json:"name" yaml:"name"`
    URL  string `json:"url" yaml:"url"`
    Auth Auth   `json:"auth,omitempty" yaml:"auth,omitempty"`
}
```

<a name="Resource"></a>
## type Resource {#Resource}

Resource represents one kubernetes api object.

```go
type Resource map[string]any
```

<a name="Resources"></a>
## type Resources {#Resources}

Resources represents Kubernetes resources. Most commonly used to mix resources into the [BuildPlan](<#BuildPlan>) generated from CUE, but may be generated from elsewhere.

```go
type Resources map[Kind]map[InternalLabel]Resource
```

<a name="Transformer"></a>
## type Transformer {#Transformer}

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

1. [Kustomize](<#Kustomize>) \- Patch and transform the output from prior generators or transformers. See [Introduction to Kustomize](<https://kubectl.docs.kubernetes.io/guides/config_management/introduction/>).
2. [Join](<#Join>) \- Concatenate multiple prior outputs into one output.
3. [Command](<#Command>) \- Transforms data by executing an user defined command.

```go
type Transformer struct {
    // Kind represents the kind of transformer. Must be Kustomize, or Join.
    Kind string `json:"kind" yaml:"kind" cue:"\"Kustomize\" | \"Join\" | \"Command\""`
    // Inputs represents the files to transform. The Output of prior Generators
    // and Transformers.
    Inputs []FileOrDirectoryPath `json:"inputs" yaml:"inputs"`
    // Output represents a file or directory for a subsequent Transformer or
    // Artifact to consume.
    Output FileOrDirectoryPath `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"`
    // Command transformer. Ignored unless kind is Command.
    Command Command `json:"command,omitempty" yaml:"command,omitempty"`
}
```

<a name="Validator"></a>
## type Validator {#Validator}

Validator validates files. Useful to validate an [Artifact](<#Artifact>) prior to writing it out to the final destination. Holos may execute validators concurrently. See the [validators](<https://holos.run/docs/v1alpha6/tutorial/validators/>) tutorial for an end to end example.

```go
type Validator struct {
    // Kind represents the kind of transformer. Must be Kustomize, or Join.
    Kind string `json:"kind" yaml:"kind" cue:"\"Command\""`
    // Inputs represents the files to validate.  Usually the final Artifact.
    Inputs []FileOrDirectoryPath `json:"inputs" yaml:"inputs"`
    // Command validator.  Ignored unless kind is Command.
    Command Command `json:"command,omitempty" yaml:"command,omitempty"`
}
```

<a name="ValueFile"></a>
## type ValueFile {#ValueFile}

ValueFile represents one Helm value file produced from CUE.

```go
type ValueFile struct {
    // Name represents the file name, e.g. "region-values.yaml"
    Name string `json:"name" yaml:"name"`
    // Kind is a discriminator.
    Kind string `json:"kind" yaml:"kind" cue:"\"Values\""`
    // Values represents values for holos to marshal into the file name specified
    // by Name when rendering the chart.
    Values Values `json:"values,omitempty" yaml:"values,omitempty"`
}
```

<a name="Values"></a>
## type Values {#Values}

Values represents [Helm](<#Helm>) Chart values generated from CUE.

```go
type Values map[string]any
```

Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)