holos/doc/md/api/core.md

---
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/v1alpha5"
```

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

- [type Artifact](<#Artifact>)
- [type BuildPlan](<#BuildPlan>)
- [type BuildPlanSource](<#BuildPlanSource>)
- [type BuildPlanSpec](<#BuildPlanSpec>)
- [type Chart](<#Chart>)
- [type Component](<#Component>)
- [type File](<#File>)
- [type FileContent](<#FileContent>)
- [type FileContentMap](<#FileContentMap>)
- [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 Values](<#Values>)


<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 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 must be at least one [Transformer](<#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](<#BuildPlan>). An Artifact should not use an output from another Artifact as an input. Each [Generator](<#Generator>) may also run concurrently. 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>).

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

<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. A future enhancement will support user defined executables providing a BuildPlan to Holos in the style of an [external credential provider](<https://github.com/kubernetes/enhancements/blob/313ad8b59c80819659e1fbf0f165230f633f2b22/keps/sig-auth/541-external-credential-providers/README.md>).

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

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

BuildPlanSource reflects the origin of a [BuildPlan](<#BuildPlan>). Useful to save a build plan to a file, then re\-generate it without needing to process a [Platform](<#Platform>) component collection.

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

<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"`
    // Disabled causes the holos cli to disregard the build plan.
    Disabled bool `json:"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"`
    // Version represents the chart version.
    Version string `json:"version"`
    // Release represents the chart release when executing helm template.
    Release string `json:"release"`
    // Repository represents the repository to fetch the chart from.
    Repository Repository `json:"repository,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"`
    // Path represents the path of the component relative to the platform root.
    // Injected as the tag variable "holos_component_path".
    Path string `json:"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"`
    // 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"`
}
```

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

<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="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.

```go
type Generator struct {
    // Kind represents the kind of generator.  Must be Resources, Helm, or File.
    Kind string `json:"kind" cue:"\"Resources\" | \"Helm\" | \"File\""`
    // Output represents a file for a Transformer or Artifact to consume.
    Output FilePath `json:"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"`
    // Helm generator. Ignored unless kind is Helm.
    Helm Helm `json:"helm,omitempty"`
    // File generator. Ignored unless kind is File.
    File File `json:"file,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"`
    // Values represents values for holos to marshal into values.yaml when
    // rendering the chart.
    Values Values `json:"values"`
    // EnableHooks enables helm hooks when executing the `helm template` command.
    EnableHooks bool `json:"enableHooks,omitempty"`
    // Namespace represents the helm namespace flag
    Namespace string `json:"namespace,omitempty"`
    // APIVersions represents the helm template --api-versions flag
    APIVersions []string `json:"apiVersions,omitempty"`
    // KubeVersion represents the helm template --kube-version flag
    KubeVersion string `json:"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" cue:"string | *\"---\\n\""`
}
```

<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"`
    // Files holds file contents for kustomize, e.g. patch files.
    Files FileContentMap `json:"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"`
}
```

<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 {
    // Kind is a string value representing the resource.
    Kind string `json:"kind" cue:"\"Platform\""`
    // APIVersion represents the versioned schema of this resource.
    APIVersion string `json:"apiVersion" cue:"string | *\"v1alpha5\""`
    // Metadata represents data about the resource such as the Name.
    Metadata Metadata `json:"metadata"`

    // Spec represents the platform specification.
    Spec PlatformSpec `json:"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"`
}
```

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

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

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

<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.

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