v1alpha3

Documentation

Overview

Package v1alpha3 contains the core API contract between the holos cli and CUE configuration code. Platform designers, operators, and software developers use this API to write configuration in CUE which `holos` loads. The overall shape of the API defines imperative actions `holos` should carry out to render the complete yaml that represents a Platform.

Platform defines the complete configuration of a platform. With the holos reference platform this takes the shape of one management cluster and at least two workload cluster. Each cluster has multiple Component resources applied to it.

Each holos component path, e.g. `components/namespaces` produces exactly one BuildPlan which in turn contains a set of Component kinds.

The primary kinds of Component are:

1. HelmChart to render config from a helm chart.
2. KustomizeBuild to render config from Kustomize
3. KubernetesObjects to render APIObjects defined directly in CUE configuration.

Note that Holos operates as a data pipeline, so the output of a HelmChart may be provided to Kustomize for post-processing.

Index

• Constants
• type APIObject
• type APIObjectMap
• type APIObjects
• type BuildPlan
• type BuildPlanComponents
• type BuildPlanSpec
• type Chart
• type Component
• type FileContent
• type FileContentMap
• type FilePath
• type HelmChart
• type InternalLabel
• type Kind
• type KubernetesObjects
• type Kustomize
• type KustomizeBuild
• type Metadata
• type Platform
• type PlatformMetadata
• type PlatformSpec
• type PlatformSpecComponent
• type Repository

Constants

const (
	APIVersion    = "v1alpha3"
	BuildPlanKind = "BuildPlan"
	HelmChartKind = "HelmChart"
	// ChartDir is the directory name created in the holos component directory to cache a chart.
	ChartDir = "vendor"
	// ResourcesFile is the file name used to store component output when post-processing with kustomize.
	ResourcesFile = "resources.yaml"
)

const KubernetesObjectsKind = "KubernetesObjects"

Types

type APIObject

type APIObject structpb.Struct

APIObject represents the most basic generic form of a single kubernetes api object. Represented as a JSON object internally for compatibility between tools, for example loading from CUE.

type APIObjectMap

type APIObjectMap map[Kind]map[InternalLabel]string

APIObjectMap represents the marshalled yaml representation of kubernetes api objects. Do not produce an APIObjectMap directly, instead use APIObjects to produce the marshalled yaml representation from CUE data, then provide the result to Component.

type APIObjects

type APIObjects struct {
	APIObjects   map[Kind]map[InternalLabel]APIObject `json:"apiObjects"`
	APIObjectMap APIObjectMap                         `json:"apiObjectMap"`
}

APIObjects represents Kubernetes API objects defined directly from CUE code. Useful to mix in resources to any kind of Component, for example adding an ExternalSecret resource to a HelmChart.

Kind must be the resource kind, e.g. Deployment or Service.

InternalLabel is an arbitrary internal identifier to uniquely identify the resource within the context of a `holos` command. Holos will never write the intermediate label to rendered output.

Refer to Component which accepts an APIObjectMap field provided by APIObjects.

type BuildPlan

type BuildPlan struct {
	Kind       string        `json:"kind" cue:"\"BuildPlan\""`
	APIVersion string        `json:"apiVersion" cue:"string | *\"v1alpha3\""`
	Spec       BuildPlanSpec `json:"spec"`
}

BuildPlan represents a build plan for the holos cli to execute. The purpose of a BuildPlan is to define one or more Component kinds. For example a HelmChart, KustomizeBuild, or KubernetesObjects.

A BuildPlan usually has an additional empty KubernetesObjects for the purpose of using the Component DeployFiles field to deploy an ArgoCD or Flux gitops resource for the holos component.

type BuildPlanComponents

type BuildPlanComponents struct {
	Resources             map[InternalLabel]KubernetesObjects `json:"resources,omitempty"`
	KubernetesObjectsList []KubernetesObjects                 `json:"kubernetesObjectsList,omitempty"`
	HelmChartList         []HelmChart                         `json:"helmChartList,omitempty"`
	KustomizeBuildList    []KustomizeBuild                    `json:"kustomizeBuildList,omitempty"`
}

type BuildPlanSpec

type BuildPlanSpec struct {
	// Disabled causes the holos cli to take no action over the [BuildPlan].
	Disabled bool `json:"disabled,omitempty"`
	// Components represents multiple [HolosComponent] kinds to manage.
	Components BuildPlanComponents `json:"components,omitempty"`
}

BuildPlanSpec represents the specification of the build plan.

type Chart

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

Chart represents a helm chart.

type Component

type Component struct {
	// Kind is a string value representing the resource this object represents.
	Kind string `json:"kind"`
	// APIVersion represents the versioned schema of this representation of an object.
	APIVersion string `json:"apiVersion" cue:"\"v1alpha3\""`
	// Metadata represents data about the holos component such as the Name.
	Metadata Metadata `json:"metadata"`

	// APIObjectMap holds the marshalled representation of api objects.  Useful to
	// mix in resources to each Component type, for example adding an
	// ExternalSecret to a [HelmChart] Component.  Refer to [APIObjects].
	APIObjectMap APIObjectMap `json:"apiObjectMap,omitempty"`

	// DeployFiles represents file paths relative to the cluster deploy directory
	// with the value representing the file content.  Intended for defining the
	// ArgoCD Application resource or Flux Kustomization resource from within CUE,
	// but may be used to render any file related to the build plan from CUE.
	DeployFiles FileContentMap `json:"deployFiles,omitempty"`

	// Kustomize represents a kubectl kustomize build post-processing step.
	Kustomize `json:"kustomize,omitempty"`

	// Skip causes holos to take no action regarding this component.
	Skip bool `json:"skip" cue:"bool | *false"`
}

Component defines the fields common to all holos component kinds. Every holos component kind should embed Component.

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 HelmChart

type HelmChart struct {
	Component `json:",inline"`
	Kind      string `json:"kind" cue:"\"HelmChart\""`

	// Chart represents a helm chart to manage.
	Chart Chart `json:"chart"`
	// ValuesContent represents the values.yaml file holos passes to the `helm
	// template` command.
	ValuesContent string `json:"valuesContent"`
	// EnableHooks enables helm hooks when executing the `helm template` command.
	EnableHooks bool `json:"enableHooks" cue:"bool | *false"`
}

HelmChart represents a holos component which wraps around an upstream helm chart. Holos orchestrates helm by providing values obtained from CUE, renders the output using `helm template`, then post-processes the helm output yaml using the general functionality provided by Component, for example Kustomize post-rendering and mixing in additional kubernetes api objects.

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.

A InternalLabel is useful to convert a CUE struct to a list, for example producing a list of APIObject resources from an APIObjectMap. A CUE struct using InternalLabel keys is guaranteed to not lose data when rendering output because a InternalLabel is expected to never be written to the final output.

type Kind

type Kind string

Kind is a kubernetes api object kind. Defined as a type for clarity and type checking.

type KubernetesObjects

type KubernetesObjects struct {
	Component `json:",inline"`
	Kind      string `json:"kind" cue:"\"KubernetesObjects\""`
}

KubernetesObjects represents a Component composed of Kubernetes API objects provided directly from CUE using APIObjects.

type Kustomize

type Kustomize struct {
	// KustomizeFiles holds file contents for kustomize, e.g. patch files.
	KustomizeFiles FileContentMap `json:"kustomizeFiles,omitempty"`
	// ResourcesFile is the file name used for api objects in kustomization.yaml
	ResourcesFile string `json:"resourcesFile,omitempty"`
}

Kustomize represents resources necessary to execute a kustomize build. Intended for at least two use cases:

1. Process a KustomizeBuild Component which represents raw yaml file resources in a holos component directory.
2. Post process a HelmChart Component to inject istio, patch jobs, add custom labels, etc...

type KustomizeBuild

type KustomizeBuild struct {
	Component `json:",inline"`
	Kind      string `json:"kind" cue:"\"KustomizeBuild\""`
}

KustomizeBuild represents a Component that renders plain yaml files in the holos component directory using `kubectl kustomize build`.

type Metadata

type Metadata struct {
	// Name represents the name of the holos component.
	Name string `json:"name"`
	// Namespace is the primary namespace of the holos component.  A holos
	// component may manage resources in multiple namespaces, in this case
	// consider setting the component namespace to default.
	//
	// This field is optional because not all resources require a namespace,
	// particularly CRDs and DeployFiles functionality.
	// +optional
	Namespace string `json:"namespace,omitempty"`
}

Metadata represents data about the object such as the Name.

type Platform

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

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

Platform represents a platform to manage. A Platform resource informs holos which components to build. The platform resource also acts as a container for the platform model form values provided by the PlatformService. The primary use case is to collect the cluster names, cluster types, platform model, and holos components to build into one resource.

type PlatformMetadata

type PlatformMetadata struct {
	// Name represents the Platform name.
	Name string `json:"name"`
}

type PlatformSpec

type PlatformSpec struct {
	// Model represents the platform model holos gets from from the
	// PlatformService.GetPlatform rpc method and provides to CUE using a tag.
	Model structpb.Struct `json:"model" cue:"{...}"`
	// Components represents a list of holos components to manage.
	Components []PlatformSpecComponent `json:"components"`
}

PlatformSpec represents the specification of a Platform. Think of a platform specification as a list of platform components to apply to a list of kubernetes clusters combined with the user-specified Platform Model.

type PlatformSpecComponent

type PlatformSpecComponent struct {
	// Path is the path of the component relative to the platform root.
	Path string `json:"path"`
	// Cluster is the cluster name to provide when rendering the component.
	Cluster string `json:"cluster"`
}

PlatformSpecComponent represents a holos component to build or render.

type Repository

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

Repository represents a helm chart repository.