kindsys

README

kindsys

This is the cue+thema + global kindsys wrapper for k8s objects.

Further development on thema is on hold while we evaluate options, but this package includes all thema bindings needed for app platform.

Documentation

Index

• Variables
• func BuildInstance(ctx *cue.Context, relpath string, pkg string, overlay fs.FS) (cue.Value, error)
• func CUEFramework(ctx *cue.Context) cue.Value
• func LoadInstance(relpath string, pkg string, overlay fs.FS) (*build.Instance, error)
• func ToKindProps[T KindProperties](v cue.Value) (T, error)
• type CommonProperties
• type Custom
  • func BindCustom(rt *thema.Runtime, def Def[CustomProperties], opts ...thema.BindOption) (Custom, error)
• type CustomProperties
  • func (m CustomProperties) Common() CommonProperties
• type Def
  • func ToDef[T KindProperties](v cue.Value) (Def[T], error)
  • func (def Def[T]) Some() SomeDef
• type Kind
• type KindProperties
• type Maturity
  • func (m Maturity) Less(om Maturity) bool
  • func (m Maturity) String() string
• type SomeDef
  • func (def SomeDef) BindKindLineage(rt *thema.Runtime, opts ...thema.BindOption) (thema.Lineage, error)
  • func (def SomeDef) IsCustom() bool
• type SomeKindProperties

Variables

var (
	// ErrValueNotExist indicates that a necessary CUE value did not exist.
	ErrValueNotExist = errors.New("cue value does not exist")

	// ErrValueNotAKind indicates that a provided CUE value is not any variety of
	// Kind. This is almost always a user error - they oops'd and provided the
	// wrong path, file, etc.
	ErrValueNotAKind = errors.New("not a kind")

	// ErrInvalidCUE indicates that the CUE representing the kind is invalid.
	ErrInvalidCUE = errors.New("CUE syntax error")
)

var CueSchemaFS embed.FS

CueSchemaFS embeds all CUE files in the Kindsys project.

Functions

func BuildInstance

func BuildInstance(ctx *cue.Context, relpath string, pkg string, overlay fs.FS) (cue.Value, error)

func CUEFramework

func CUEFramework(ctx *cue.Context) cue.Value

CUEFramework returns a cue.Value representing all the kindsys framework raw CUE files.

For low-level use in constructing other types and APIs, while still letting us define all the frameworky CUE bits in a single package. Other Go types make the constructs in the returned cue.Value easy to use.

Calling this with a nil cue.Context (the singleton returned from [CUEContext]) will memoize certain CUE operations. Prefer passing nil unless a different cue.Context is specifically required.

func LoadInstance

func LoadInstance(relpath string, pkg string, overlay fs.FS) (*build.Instance, error)

LoadInstance returns a build.Instance populated with the CueSchemaFS at the root and an optional overlay filesystem.

func ToKindProps

func ToKindProps[T KindProperties](v cue.Value) (T, error)

ToKindProps takes a cue.Value expected to represent a kind of the category specified by the type parameter and populates the Go type from the cue.Value.

Types

type CommonProperties

type CommonProperties struct {
	Name              string   `json:"name"`
	PluralName        string   `json:"pluralName"`
	MachineName       string   `json:"machineName"`
	PluralMachineName string   `json:"pluralMachineName"`
	LineageIsGroup    bool     `json:"lineageIsGroup"`
	Maturity          Maturity `json:"maturity"`
	Description       string   `json:"description,omitempty"`
}

CommonProperties contains the metadata common to all categories of kinds.

type Custom

type Custom interface {
	Kind

	// TODO docs
	Def() Def[CustomProperties]
}

func BindCustom

func BindCustom(rt *thema.Runtime, def Def[CustomProperties], opts ...thema.BindOption) (Custom, error)

BindCustom creates a Custom-implementing type from a def, runtime, and opts

type CustomProperties

type CustomProperties struct {
	CommonProperties
	CurrentVersion thema.SyntacticVersion `json:"currentVersion"`
	IsCRD          bool                   `json:"isCRD"`
	Group          string                 `json:"group"`
	CRD            struct {
		Group         string  `json:"group"`
		Scope         string  `json:"scope"`
		GroupOverride *string `json:"groupOverride"`
	} `json:"crd"`
	Codegen struct {
		Frontend bool `json:"frontend"`
		Backend  bool `json:"backend"`
	} `json:"codegen"`
}

CustomProperties represents the static properties in the definition of a Custom kind that are representable with basic Go types. This excludes Thema schemas.

func (CustomProperties) Common

func (m CustomProperties) Common() CommonProperties

type Def

type Def[T KindProperties] struct {
	// V is the cue.Value containing the entire Kind definition.
	V cue.Value
	// Properties contains the kind's declarative non-schema properties.
	Properties T
}

Def represents a single kind definition, having been loaded and validated by a func such as [LoadCoreKindDef].

Its type parameter indicates the category of kind.

Thema lineages in the contained definition have not yet necessarily been validated.

func ToDef

func ToDef[T KindProperties](v cue.Value) (Def[T], error)

ToDef takes a cue.Value expected to represent a kind of the category specified by the type parameter and populates a Def from the CUE value. The cue.Value in Def.V will be the unified value of the parameter cue.Value and the kindsys CUE kind (Core, Custom, Composable).

func (Def[T]) Some

func (def Def[T]) Some() SomeDef

Some converts the typed Def to the equivalent typeless SomeDef.

type Kind

type Kind interface {
	// Props returns a [kindsys.SomeKindProps], representing the properties
	// of the kind as declared in the .cue source. The underlying type is
	// determined by the category of kind.
	//
	// This method is largely for convenience, as all actual kind categories are
	// expected to implement one of the other interfaces, each of which contain
	// a Def() method through which these same properties are accessible.
	Props() SomeKindProperties

	// TODO docs
	Lineage() thema.Lineage

	// TODO remove, unnecessary with Props()
	Name() string

	// TODO remove, unnecessary with Props()
	MachineName() string

	// TODO remove, unnecessary with Props()
	Maturity() Maturity // TODO unclear if we want maturity for raw kinds
}

Kind describes a Grafana kind object: a Go representation of the definition of one of Grafana's categories of kinds.

type KindProperties

type KindProperties interface {
	CustomProperties
}

KindProperties is a type parameter that comprises the base possible set of kind metadata configurations.

type Maturity

type Maturity string

TODO docs

const (
	MaturityMerged       Maturity = "merged"
	MaturityExperimental Maturity = "experimental"
	MaturityStable       Maturity = "stable"
	MaturityMature       Maturity = "mature"
)

func (Maturity) Less

func (m Maturity) Less(om Maturity) bool

func (Maturity) String

func (m Maturity) String() string

type SomeDef

type SomeDef struct {
	// V is the cue.Value containing the entire Kind definition.
	V cue.Value
	// Properties contains the kind's declarative non-schema properties.
	Properties SomeKindProperties
}

SomeDef represents a single kind definition, having been loaded and validated by a func such as [LoadCoreKindDef].

The underlying type of the Properties field indicates the category of kind.

func (SomeDef) BindKindLineage

func (def SomeDef) BindKindLineage(rt *thema.Runtime, opts ...thema.BindOption) (thema.Lineage, error)

BindKindLineage binds the lineage for the kind definition.

For kinds with a corresponding Go type, it is left to the caller to associate that Go type with the lineage returned from this function by a call to thema.BindType.

func (SomeDef) IsCustom

func (def SomeDef) IsCustom() bool

IsCustom indicates whether the represented kind is a custom kind.

type SomeKindProperties

type SomeKindProperties interface {
	Common() CommonProperties
}

SomeKindProperties is an interface type to abstract over the different kind property struct types: [CoreProperties], CustomProperties

It is the traditional interface counterpart to the generic type constraint KindProperties.