app

package
v0.26.0 Latest Latest
Warning

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

 Go to latest Published: Dec 3, 2024 License: Apache-2.0 Imports: 15 Imported by: 4

Documentation

Index

Constants

View Source 
const (
	ManifestLocationFilePath          = ManifestLocationType("filepath")
	ManifestLocationAPIServerResource = ManifestLocationType("apiserver")
	ManifestLocationEmbedded          = ManifestLocationType("embedded")
)

Variables

View Source 
var (
	// ErrNotImplemented is an error that indicates that an App method is not implemented by the App implementation,
	// or the App method is not implemented for the provided Kind.
	// Typically, the App's ManifestData should indicate this as well.
	ErrNotImplemented = errors.New("not implemented")

	ErrCustomRouteNotFound = errors.New("custom route not found")
)
View Source 
var (
	ErrOtherRunStopped = errors.New("run stopped by another run call")
)
View Source 
var RunnableCollectorDefaultErrorHandler = func(ctx context.Context, err error) bool {
	logging.FromContext(ctx).Error("runner exited with error", "error", err)
	return true
}

Functions

This section is empty.

Types

type AdmissionCapabilities 

type AdmissionCapabilities struct {
	// Validation contains the validation capability details. If nil, the kind does not have a validation capability.
	Validation *ValidationCapability `json:"validation,omitempty" yaml:"validation,omitempty"`
	// Mutation contains the mutation capability details. If nil, the kind does not have a mutation capability.
	Mutation *MutationCapability `json:"mutation,omitempty" yaml:"mutation,omitempty"`
}

AdmissionCapabilities is the collection of admission capabilities of a kind

func (AdmissionCapabilities) SupportsAnyMutation 

func (c AdmissionCapabilities) SupportsAnyMutation() bool

SupportsAnyMutation returns true if the list of operations for mutation is not empty. This is a convenience method to avoid having to make several nil and length checks.

func (AdmissionCapabilities) SupportsAnyValidation 

func (c AdmissionCapabilities) SupportsAnyValidation() bool

SupportsAnyValidation returns true if the list of operations for validation is not empty. This is a convenience method to avoid having to make several nil and length checks.

type AdmissionOperation 

type AdmissionOperation string
const (
	AdmissionOperationAny     AdmissionOperation = "*"
	AdmissionOperationCreate  AdmissionOperation = "CREATE"
	AdmissionOperationUpdate  AdmissionOperation = "UPDATE"
	AdmissionOperationDelete  AdmissionOperation = "DELETE"
	AdmissionOperationConnect AdmissionOperation = "CONNECT"
)

type AdmissionRequest added in v0.22.0 

type AdmissionRequest resource.AdmissionRequest

type App added in v0.22.0 

type App interface {
	// Validate validates the incoming request, and returns an error if validation fails
	Validate(ctx context.Context, request *AdmissionRequest) error
	// Mutate runs mutation on the incoming request, responding with a MutatingResponse on success, or an error on failure
	Mutate(ctx context.Context, request *AdmissionRequest) (*MutatingResponse, error)
	// Convert converts the object based on the ConversionRequest, returning a RawObject which MUST contain
	// the converted bytes and encoding (Raw and Encoding respectively), and MAY contain the Object representation of those bytes.
	// It returns an error if the conversion fails, or if the functionality is not supported by the app.
	Convert(ctx context.Context, req ConversionRequest) (*RawObject, error)
	// CallResourceCustomRoute handles the call to a resource custom route, and returns a response to the request or an error.
	// If the route doesn't exist, the implementer MAY return ErrCustomRouteNotFound to signal to the runner,
	// or may choose to return a response with a not found status code and custom body.
	// It returns an error if the functionality is not supported by the app.
	CallResourceCustomRoute(ctx context.Context, request *ResourceCustomRouteRequest) (*ResourceCustomRouteResponse, error)
	// ManagedKinds returns a slice of Kinds which are managed by this App.
	// If there are multiple versions of a Kind, each one SHOULD be returned by this method,
	// as app runners may depend on having access to all kinds.
	ManagedKinds() []resource.Kind
	// Runner returns a Runnable with an app main loop. Any business logic that is not/can not be exposed
	// via other App interfaces should be contained within this method.
	// Runnable MAY be nil, in which case, the app has no main loop business logic.
	Runner() Runnable
}

App represents an app platform application logical structure. An App is typically run with a wrapper, such as simple.NewStandaloneOperator, which will present a runtime layer (such as kubernetes webhooks in the case of an operator), and translate those into calls to the App. The wrapper is typically also responsible for lifecycle management and running the Runnable provided by Runner(). Pre-built implementations of App exist in the simple package, but any type which implements App should be capable of being run by an app wrapper.

type Config added in v0.22.0 

type Config struct {
	// KubeConfig is a kubernetes rest.Config used to communicate with the API server where the App's Kinds are stored.
	KubeConfig rest.Config
	// ManifestData is the fetched ManifestData the runner is using for determining app kinds and capabilities.
	ManifestData ManifestData
	// SpecificConfig is app-specific config (as opposed to generic config)
	SpecificConfig SpecificConfig
}

Config is the app configuration used in a Provider for instantiating a new App. It contains kubernetes configuration for communicating with an API server, the App's ManifestData as fetched by the runner, and additional arbitrary configuration details that may be app-specific.

type ConversionRequest added in v0.22.0 

type ConversionRequest struct {
	SourceGVK schema.GroupVersionKind
	TargetGVK schema.GroupVersionKind
	Raw       RawObject
}

ConversionRequest is a request to convert a Kind from one version to another

type Manifest 

type Manifest struct {
	// ManifestData must be present if Location.Type == "embedded"
	ManifestData *ManifestData
	// Location indicates the place where the ManifestData should be loaded from
	Location ManifestLocation
}

Manifest is a type which represents the Location and Data in an App Manifest.

func NewAPIServerManifest 

func NewAPIServerManifest(resourceName string) Manifest

NewAPIServerManifest returns a Manifest which points to a resource in an API server to load the ManifestData from

func NewEmbeddedManifest 

func NewEmbeddedManifest(manifestData ManifestData) Manifest

NewEmbeddedManifest returns a Manifest which has the ManifestData embedded in it

func NewOnDiskManifest 

func NewOnDiskManifest(path string) Manifest

NewOnDiskManifest returns a Manifest which points to a path on-disk to load ManifestData from

type ManifestData 

type ManifestData struct {
	// AppName is the unique identifier for the App
	AppName string `json:"appName" yaml:"appName"`
	// Group is the group used for all kinds maintained by this app.
	// This is usually "<AppName>.ext.grafana.com"
	Group string `json:"group" yaml:"group"`
	// Kinds is a list of all Kinds maintained by this App
	Kinds []ManifestKind `json:"kinds,omitempty" yaml:"kinds,omitempty"`
}

ManifestData is the data in a Manifest, representing the Kinds and Capabilities of an App. NOTE: ManifestData is still experimental and subject to change

type ManifestKind 

type ManifestKind struct {
	// Kind is the name of the kind
	Kind string `json:"kind" yaml:"kind"`
	// Scope if the scope of the kind, typically restricted to "Namespaced" or "Cluster"
	Scope string `json:"scope" yaml:"scope"`
	// Versions is the set of versions for the kind. This list should be ordered as a series of progressively later versions.
	Versions []ManifestKindVersion `json:"versions" yaml:"versions"`
	// Conversion is true if the app has a conversion capability for this kind
	Conversion bool `json:"conversion" yaml:"conversion"`
}

ManifestKind is the manifest for a particular kind, including its Kind, Scope, and Versions

type ManifestKindVersion 

type ManifestKindVersion struct {
	// Name is the version string name, such as "v1"
	Name string `yaml:"name" json:"name"`
	// Admission is the collection of admission capabilities for this version.
	// If nil, no admission capabilities exist for the version.
	Admission *AdmissionCapabilities `json:"admission,omitempty" yaml:"admission,omitempty"`
	// Schema is the schema of this version, as an OpenAPI document.
	// This is currently an `any` type as implementation is incomplete.
	Schema *VersionSchema `json:"schema,omitempty" yaml:"schema,omitempty"`
	// SelectableFields are the set of JSON paths in the schema which can be used as field selectors
	SelectableFields []string `json:"selectableFields,omitempty" yaml:"selectableFields,omitempty"`
}

ManifestKindVersion contains details for a version of a kind in a Manifest

type ManifestLocation 

type ManifestLocation struct {
	Type ManifestLocationType
	// Path is the path to the manifest, based on location.
	// For "filepath", it is the path on disk. For "apiserver", it is the NamespacedName. For "embedded", it is empty.
	Path string
}

ManifestLocation contains information of where a Manifest's ManifestData can be found.

type ManifestLocationType 

type ManifestLocationType string

type MultiRunner added in v0.22.0 

type MultiRunner struct {
	Runners []Runnable
	// ErrorHandler is called if one of the Runners returns an error. If the function call returns true,
	// the context will be canceled and all other Runners will also be prompted to exit.
	// If ErrorHandler is nil, RunnableCollectorDefaultErrorHandler is used.
	ErrorHandler func(context.Context, error) bool
	// ExitWait is how long to wait for Runners to exit after ErrorHandler returns true or the context is canceled
	// before stopping execution and returning a timeout error instead of exiting gracefully.
	// If ExitWait is nil, Run execution will always block until all Runners have exited.
	ExitWait *time.Duration
}

MultiRunner implements Runnable for running multiple Runnable instances.

func NewMultiRunner added in v0.22.0 

func NewMultiRunner() *MultiRunner

NewMultiRunner creates a new MultiRunner with Runners as an empty slice and ErrorHandler set to RunnableCollectorDefaultErrorHandler

func (*MultiRunner) AddRunnable added in v0.22.0 

func (m *MultiRunner) AddRunnable(runnable Runnable)

AddRunnable adds the provided Runnable to the Runners slice. If the slice is nil, it will create it.

func (*MultiRunner) PrometheusCollectors added in v0.22.0 

func (m *MultiRunner) PrometheusCollectors() []prometheus.Collector

PrometheusCollectors implements metrics.Provider by returning prometheus collectors for all Runners that also implement metrics.Provider.

func (*MultiRunner) Run added in v0.22.0 

func (m *MultiRunner) Run(ctx context.Context) error

Run runs all Runners in separate goroutines, and calls ErrorHandler if any of them exits early with an error. If ErrorHandler returns true (or if there is no ErrorHandler), the other Runners are canceled and the error is returned.

type MutatingResponse added in v0.22.0 

type MutatingResponse resource.MutatingResponse

type MutationCapability 

type MutationCapability struct {
	// Operations is the list of operations that the mutation capability is used for.
	// If this list if empty or nil, this is equivalent to the app having no mutation capability.
	Operations []AdmissionOperation `json:"operations,omitempty" yaml:"operations,omitempty"`
}

MutationCapability is the details of a mutation capability for a kind's admission control

type Provider added in v0.22.0 

type Provider interface {
	// Manifest returns a Manifest, which may contain ManifestData or may point to a location where ManifestData can be fetched from.
	// The runner should use the ManifestData to determine app capabilities.
	Manifest() Manifest
	// SpecificConfig is any app-specific config that cannot be loaded by the runner that should be provided in NewApp
	SpecificConfig() SpecificConfig
	// NewApp creates a new App instance using the provided config, or returns an error if an App cannot be instantiated.
	NewApp(Config) (App, error)
}

Provider represents a type which can provide an app manifest, and create a new App when given a configuration. It should be used by runners to determine an app's capabilities and create an instance of the app to run.

type RawObject added in v0.22.0 

type RawObject struct {
	Raw      []byte                `json:",inline"`
	Object   resource.Object       `json:"-"`
	Encoding resource.KindEncoding `json:"-"`
}

RawObject represents the raw bytes of the object and its encoding, optionally with a decoded version of the object, which may be any valid resource.Object implementation.

type ResourceCustomRouteRequest added in v0.22.0 

type ResourceCustomRouteRequest struct {
	ResourceIdentifier resource.FullIdentifier
	SubresourcePath    string
	Method             string
	Headers            http.Header
	Body               []byte
}

ResourceCustomRouteRequest is a request to a custom subresource

type ResourceCustomRouteResponse added in v0.22.0 

type ResourceCustomRouteResponse struct {
	Headers    http.Header
	StatusCode int
	Body       []byte
}

type Runnable added in v0.22.0 

type Runnable interface {
	// Run runs the process and blocks until one of the following conditions are met:
	// * An unrecoverable error occurs, in which case it returns the error
	// * The provided context completes
	// * The process completes and does not need to run again
	Run(context.Context) error
}

Runnable represents a type which can be run until it errors or the provided channel is stopped (or receives a message)

type SingletonRunner added in v0.22.0 

type SingletonRunner struct {
	Wrapped Runnable
	// StopOnAny tells the SingletonRunner to stop all Run() calls if any one of them is stopped
	StopOnAny bool
	// contains filtered or unexported fields
}

SingletonRunner runs a single Runnable but allows for multiple distinct calls to Run() which cn have independent lifecycles

func NewSingletonRunner added in v0.22.0 

func NewSingletonRunner(runnable Runnable, stopOnAny bool) *SingletonRunner

func (*SingletonRunner) PrometheusCollectors added in v0.22.0 

func (s *SingletonRunner) PrometheusCollectors() []prometheus.Collector

PrometheusCollectors implements metrics.Provider by returning prometheus collectors for the wrapped Runnable if it implements metrics.Provider.

func (*SingletonRunner) Run added in v0.22.0 

func (s *SingletonRunner) Run(ctx context.Context) error

Run runs until the provided context.Context is closed, the underlying Runnable completes, or another call to Run is stopped and StopOnAny is set to true (in which case ErrOtherRunStopped is returned)

type SpecificConfig added in v0.22.0 

type SpecificConfig any

SpecificConfig is app-specific configuration which can vary from app to app TODO: better type than any

type ValidationCapability 

type ValidationCapability struct {
	// Operations is the list of operations that the validation capability is used for.
	// If this list if empty or nil, this is equivalent to the app having no validation capability.
	Operations []AdmissionOperation `json:"operations,omitempty" yaml:"operations,omitempty"`
}

ValidationCapability is the details of a validation capability for a kind's admission control

type VersionSchema added in v0.23.0 

type VersionSchema struct {
	// contains filtered or unexported fields
}

VersionSchema represents the schema of a KindVersion in a Manifest. It allows retrieval of the schema in a variety of ways, and can be unmarshaled from a CRD's version schema, an OpenAPI document for a kind, or from just the schemas component of an openAPI document. It marshals to the schemas component of an openAPI document. A Manifest VersionSchema does not contain a metadata object, as that is consistent between every app platform kind. This is modeled after kubernetes' behavior for describing a CRD schema.

func VersionSchemaFromMap added in v0.23.0 

func VersionSchemaFromMap(openAPISchema map[string]any) (*VersionSchema, error)

func (*VersionSchema) AsMap added in v0.23.0 

func (v *VersionSchema) AsMap() map[string]any

AsMap returns the schema as a map[string]any where each key is a top-level resource (ex. 'spec', 'status')

func (*VersionSchema) AsOpenAPI3 added in v0.23.0 

func (v *VersionSchema) AsOpenAPI3() (*openapi3.Components, error)

AsOpenAPI3 returns an openapi3.Components instance which contains the schema elements

func (*VersionSchema) MarshalJSON added in v0.23.0 

func (v *VersionSchema) MarshalJSON() ([]byte, error)

func (*VersionSchema) MarshalYAML added in v0.23.0 

func (v *VersionSchema) MarshalYAML() (any, error)

func (*VersionSchema) UnmarshalJSON added in v0.23.0 

func (v *VersionSchema) UnmarshalJSON(data []byte) error

func (*VersionSchema) UnmarshalYAML added in v0.23.0 

func (v *VersionSchema) UnmarshalYAML(unmarshal func(any) error) error

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.