Skip to main content
Version: v1alpha6

Author Schemas

import "github.com/holos-run/holos/api/author/v1beta1"

Package author contains a standard set of schemas for component authors to generate common core TaskSets.

This package defines types only. The concrete CUE that assembles a core TaskSet from the wrapper fields is hand-written CUE provided by the platform scaffolding from the holos init platform command, exactly as v1alpha6 assembles a BuildPlan from the author package wrapper fields.

Holos values stability, flexibility, and composition. This package intentionally defines only the minimal necessary set of structures. Component authors are encouraged to define their own structures building on our example topics.

The Holos Maintainers may add definitions to this package if the community identifies nearly all users must define the exact same structure. Otherwise, definitions should be added as a customizable example in topics.

For example, structures representing a cluster and environment almost always need to be defined. Their definition varies from one organization to the next. Therefore, customizable definitions for a cluster and environment are best maintained in topics, not standardized in this package.

Index​

type ComponentConfig​

ComponentConfig represents the configuration common to all kinds of components for use with the holos render component command. All component kinds may be transformed with kustomize configured with the KustomizeConfig field.

type ComponentConfig struct {
    // Name represents the TaskSet metadata.name field.  Used to construct the
    // fully rendered manifest file path.
    Name string
    // Labels represent the TaskSet metadata.labels field.
    Labels map[string]string
    // Annotations represent the TaskSet metadata.annotations field.
    Annotations map[string]string

    // Path represents the path to the component producing the TaskSet.
    Path string
    // Parameters are useful to reuse a component with various parameters.
    // Injected as CUE @tag variables.  Parameters with a "holos_" prefix are
    // reserved for use by the Holos Authors.
    Parameters map[string]string
    // OutputBaseDir represents the output base directory used when assembling
    // artifacts.  Useful to organize components by clusters or other parameters.
    // For example, holos writes resource manifests to
    // {WriteTo}/{OutputBaseDir}/components/{Name}/{Name}.gen.yaml
    OutputBaseDir string `cue:"string | *\"\""`

    // Resources represents kubernetes resources mixed into the rendered manifest.
    Resources core.Resources
    // KustomizeConfig represents the kustomize configuration.
    KustomizeConfig KustomizeConfig
    // Tasks represents additional tasks unified into the TaskSet.  Replaces the
    // v1alpha6 Artifacts and Validators mix-in fields.  Useful for adding GitOps
    // resources or validation commands.  Each Task is unified without
    // modification into the TaskSet spec.tasks field by the hand-written
    // assembly CUE provided by the platform scaffolding.
    Tasks map[NameLabel]core.Task
}

type Helm​

Helm assembles a TaskSet rendering a helm chart. Useful to mix in additional resources from CUE and transform the helm output with kustomize.

type Helm struct {
    ComponentConfig `json:",inline"`

    // Chart represents a Helm chart.
    Chart core.Chart
    // Values represents data to marshal into a values.yaml for helm.
    Values core.Values
    // ValueFiles represents value files for migration from helm value
    // hierarchies.  Use Values instead.
    ValueFiles []core.ValueFile `json:",omitempty"`
    // EnableHooks enables helm hooks when executing the `helm template` command.
    EnableHooks bool `cue:"true | *false"`
    // Namespace sets the helm chart namespace flag if provided.
    Namespace string `json:",omitempty"`
    // APIVersions represents the helm template --api-versions flag
    APIVersions []string `json:",omitempty"`
    // KubeVersion represents the helm template --kube-version flag
    KubeVersion string `json:",omitempty"`

    // TaskSet represents the derived TaskSet produced for the holos render
    // component command.
    TaskSet core.TaskSet
}

type Kubernetes​

Kubernetes assembles a TaskSet containing inline resources exported from CUE.

type Kubernetes struct {
    ComponentConfig `json:",inline"`

    // TaskSet represents the derived TaskSet produced for the holos render
    // component command.
    TaskSet core.TaskSet
}

type Kustomize​

Kustomize assembles a TaskSet rendering manifests from a kustomize kustomization.

type Kustomize struct {
    ComponentConfig `json:",inline"`

    // TaskSet represents the derived TaskSet produced for the holos render
    // component command.
    TaskSet core.TaskSet
}

type KustomizeConfig​

KustomizeConfig represents the configuration for kustomize post processing. Use the Files field to mix in plain manifest files located in the component directory. Use the Resources field to mix in manifests from network urls.

type KustomizeConfig struct {
    // Kustomization represents the kustomization used to transform resources.
    // Note the resources field is internally managed from the Files and Resources fields.
    Kustomization map[string]any `json:",omitempty"`
    // Files represents files to copy from the component directory for kustomization.
    Files map[string]struct{ Source string } `cue:"{[NAME=_]: Source: NAME}"`
    // Resources represents additional entries to included in the resources list.
    Resources map[string]struct{ Source string } `cue:"{[NAME=_]: Source: NAME}"`
    // CommonLabels represents common labels added without including selectors.
    CommonLabels map[string]string
}

type NameLabel​

NameLabel represents the common use case of converting a struct to a list where the name field of each value unifies with the field name of the outer struct.

For example:

S: [NameLabel=string]: name: NameLabel
S: jeff: _
S: gary: _
S: nate: _
L: [for x in S {x}]
// L is [{name: "jeff"}, {name: "gary"}, {name: "nate"}]
type NameLabel string

type Platform​

Platform assembles a core Platform in the Resource field for the holos render platform command. Use the Components field to register components with the platform.

type Platform struct {
    // Name represents the platform name.
    Name string `json:"name" yaml:"name" cue:"string | *\"default\""`
    // Components represents the components to register with the platform.
    Components map[NameLabel]core.Component `json:"components" yaml:"components"`
    // Resource represents the core Platform resource for the holos render
    // platform command.
    Resource core.Platform `json:"resource" yaml:"resource"`
}

Generated by gomarkdoc