v1alpha2

package
v0.97.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 17, 2024 License: Apache-2.0 Imports: 1 Imported by: 0

Documentation

Overview

Package v1alpha2 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 HolosComponent resources applied to it.

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

The primary kinds of HolosComponent 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

View Source 
const (
	APIVersion    = "v1alpha2"
	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"
)
View Source 
const KubernetesObjectsKind = "KubernetesObjects"

Variables

This section is empty.

Functions

This section is empty.

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[Label]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 HolosComponent.

type APIObjects 

type APIObjects struct {
	APIObjects   map[Kind]map[Label]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 HolosComponent, for example adding an ExternalSecret resource to a HelmChart.

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

Label 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 HolosComponent 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 | *\"v1alpha2\""`
	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 HolosComponent kinds. For example a HelmChart, KustomizeBuild, or KubernetesObjects.

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

type BuildPlanComponents 

type BuildPlanComponents struct {
	Resources             map[Label]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 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. Paths are relative to the `holos` output "deploy" directory, and may contain sub-directories.

type FilePath 

type FilePath string

FilePath represents a file path.

type HelmChart 

type HelmChart struct {
	HolosComponent `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 HolosComponent, for example Kustomize post-rendering and mixing in additional kubernetes api objects.

type HolosComponent 

type HolosComponent 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:"string | *\"v1alpha2\""`
	// 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 HolosComponent type, for example adding an
	// ExternalSecret to a HelmChart HolosComponent.  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"`
}

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

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 {
	HolosComponent `json:",inline"`
	Kind           string `json:"kind" cue:"\"KubernetesObjects\""`
}

KubernetesObjects represents a HolosComponent 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 HolosComponent which represents raw yaml file resources in a holos component directory.
  2. Post process a HelmChart HolosComponent to inject istio, patch jobs, add custom labels, etc...

type KustomizeBuild 

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

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

type Label 

type Label string

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

A Label 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 Label keys is guaranteed to not lose data when rendering output because a Label is expected to never be written to the final output.

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 CRD's and DeployFiles functionality.
	// +optional
	Namespace string `json:"namespace,omitempty"`
}

Metadata represents data about the holos component 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 | *\"v1alpha2\""`
	// 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"`
	// 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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.