README
¶
runtime
COSI Runtime contains core resource (state) and controller (operator) engine to build operating systems.
Design
Resources
A resource is a metadata plus opaque spec.
Metadata structure is strictly defined, while a spec is transparent to the runtime.
Metadata defines an address of the resource: (namespace, type, id, version) and additional fields (finalizers, owner, etc.)
Controllers
A controller is a task that runs as a single thread of execution. A controller has defined input and outputs. Outputs are static and should be defined at the registration time, while inputs are dynamic and might change during controller execution.
A controller is supposed to implement a reconcile loop: for each reconcile event (coming from the runtime) the controller wakes up, checks the inputs, performs any actions and modifies the outputs.
Controller inputs are resources which controller can read (it can't read resources that are not declared as inputs), and inputs are the resources controller gets notified about changes:
stronginputs are the inputs controller depends on in a strong way: it has to be notified when inputs are going to be destroyed via finalizer mechanism;weakinputs are the inputs controller watches, but it doesn't have to do any cleanup when weak inputs are being destroyed.
A controller can modify finalizers of strong controller inputs; any other modifications to the inputs are not permitted.
Controller outputs are resources which controller can write (create, destroy, update):
exclusiveoutputs are managed by only a single controller; no other controller can modify exclusive resourcessharedoutputs are resources that are created by multiple controllers, but each specific resource can only be modified by a controller which created that resource
Runtime verifies that only one controller has exclusive access to the resource.
Principles
- simple and structured: impose structure to make things simple.
- avoid conflicts by design: resources don't have multiple entities which can modify them.
- use controller structure as documentation: graph of dependencies between controllers and resources documents system design and current state.
Directories
¶
| Path | Synopsis |
|---|---|
|
api
|
|
|
v1alpha1
Package v1alpha1 is a reverse proxy.
|
Package v1alpha1 is a reverse proxy. |
|
cmd
|
|
|
runtime
Package main is the entrypoint for the controller runtime.
|
Package main is the entrypoint for the controller runtime. |
|
pkg
|
|
|
controller
Package controller defines common interfaces to be implemented by the controllers and controller runtime.
|
Package controller defines common interfaces to be implemented by the controllers and controller runtime. |
|
controller/conformance
Package conformance implements tests which verify conformance of the implementation with the spec.
|
Package conformance implements tests which verify conformance of the implementation with the spec. |
|
controller/generic
Package generic provides implementations of generic controllers.
|
Package generic provides implementations of generic controllers. |
|
controller/generic/cleanup
Package cleanup provides a generic implementation of controller which waits for and cleans up resources.
|
Package cleanup provides a generic implementation of controller which waits for and cleans up resources. |
|
controller/generic/destroy
Package destroy provides a generic implementation of controller which cleans up tearing down resources without finalizers.
|
Package destroy provides a generic implementation of controller which cleans up tearing down resources without finalizers. |
|
controller/generic/qtransform
Package qtransform implements a generic controller which transforms Input resources into Output resources based on QController.
|
Package qtransform implements a generic controller which transforms Input resources into Output resources based on QController. |
|
controller/generic/transform
Package transform provides a generic implementation of controller which transforms resources A into resources B.
|
Package transform provides a generic implementation of controller which transforms resources A into resources B. |
|
controller/runtime
Package runtime implements the controller runtime.
|
Package runtime implements the controller runtime. |
|
controller/runtime/internal/adapter
Package adapter provides common interface for controller adapters.
|
Package adapter provides common interface for controller adapters. |
|
controller/runtime/internal/cache
Package cache implements resource cache.
|
Package cache implements resource cache. |
|
controller/runtime/internal/controllerstate
Package controllerstate provides adapter which filters access to the resource state by controller inputs/outputs.
|
Package controllerstate provides adapter which filters access to the resource state by controller inputs/outputs. |
|
controller/runtime/internal/dependency
Package dependency implements controller dependency database.
|
Package dependency implements controller dependency database. |
|
controller/runtime/internal/qruntime
Package qruntime implements queue-based runtime for controllers.
|
Package qruntime implements queue-based runtime for controllers. |
|
controller/runtime/internal/qruntime/internal/containers
Package containers provides helper containers for qruntime.
|
Package containers provides helper containers for qruntime. |
|
controller/runtime/internal/qruntime/internal/queue
Package queue implements a concurrent queue of reconcile items.
|
Package queue implements a concurrent queue of reconcile items. |
|
controller/runtime/internal/qruntime/internal/timer
Package timer provides a resettable timer.
|
Package timer provides a resettable timer. |
|
controller/runtime/internal/reduced
Package reduced implements reducing resource metadata to a comparable value.
|
Package reduced implements reducing resource metadata to a comparable value. |
|
controller/runtime/internal/rruntime
Package rruntime implements runtime for Controllers (which reconcile full set of inputs on each iteration).
|
Package rruntime implements runtime for Controllers (which reconcile full set of inputs on each iteration). |
|
controller/runtime/metrics
Package metrics expose various controller runtime metrics using expvar.
|
Package metrics expose various controller runtime metrics using expvar. |
|
controller/runtime/options
Package options provides functional options for controller runtime.
|
Package options provides functional options for controller runtime. |
|
future
Package future provides a set of functions for observing the state of a running program.
|
Package future provides a set of functions for observing the state of a running program. |
|
keystorage
Package keystorage provides the key storage implementation.
|
Package keystorage provides the key storage implementation. |
|
logging
Package logging defines logging helpers.
|
Package logging defines logging helpers. |
|
resource
Package resource provides core resource definition.
|
Package resource provides core resource definition. |
|
resource/handle
Package handle provides a way to wrap "handle/descriptor-like" resources.
|
Package handle provides a way to wrap "handle/descriptor-like" resources. |
|
resource/internal/compare
Package compare implements term operation helpers.
|
Package compare implements term operation helpers. |
|
resource/internal/kv
Package kv implements core key-value type as a base for labels and annotations.
|
Package kv implements core key-value type as a base for labels and annotations. |
|
resource/kvutils
Package kvutils provides utilities to internal/kv package.
|
Package kvutils provides utilities to internal/kv package. |
|
resource/meta
Package meta provides definition of core metadata resources.
|
Package meta provides definition of core metadata resources. |
|
resource/meta/spec
Package spec contains resource specs for the meta resources.
|
Package spec contains resource specs for the meta resources. |
|
resource/protobuf
Package protobuf provides a bridge between resources and protobuf interface.
|
Package protobuf provides a bridge between resources and protobuf interface. |
|
resource/rtestutils
Package rtestutils provides utilities for testing with resource API.
|
Package rtestutils provides utilities for testing with resource API. |
|
resource/typed
Package typed generic based resource definition.
|
Package typed generic based resource definition. |
|
safe
Package safe provides a safe wrappers around the cosi runtime.
|
Package safe provides a safe wrappers around the cosi runtime. |
|
state
Package state describes interface of the core state manager/broker.
|
Package state describes interface of the core state manager/broker. |
|
state/conformance
Package conformance implements tests which verify conformance of the implementation with the spec.
|
Package conformance implements tests which verify conformance of the implementation with the spec. |
|
state/impl/inmem
Package inmem provides an implementation of state.State in memory.
|
Package inmem provides an implementation of state.State in memory. |
|
state/impl/namespaced
Package namespaced provides an implementation of state split by namespaces.
|
Package namespaced provides an implementation of state split by namespaces. |
|
state/impl/store
Package store provides support for in-memory backing store implementations.
|
Package store provides support for in-memory backing store implementations. |
|
state/impl/store/bolt
Package bolt implements inmem resource collection backing store in BoltDB (github.com/etcd-io/bbolt).
|
Package bolt implements inmem resource collection backing store in BoltDB (github.com/etcd-io/bbolt). |
|
state/impl/store/compression
Package compression provides compression support for [store.Marshaler].
|
Package compression provides compression support for [store.Marshaler]. |
|
state/impl/store/encryption
Package encryption provides encryption support for [store.Marshaler].
|
Package encryption provides encryption support for [store.Marshaler]. |
|
state/protobuf
Package protobuf provides wrappers/adapters between gRPC service and state.CoreState.
|
Package protobuf provides wrappers/adapters between gRPC service and state.CoreState. |
|
state/protobuf/client
Package client provides a wrapper around gRPC State client to provide state.CoreState.
|
Package client provides a wrapper around gRPC State client to provide state.CoreState. |
|
state/protobuf/server
Package server provides a wrapper around state.CoreState into gRPC server.
|
Package server provides a wrapper around state.CoreState into gRPC server. |
|
state/registry
Package registry provides registries for namespaces and resource definitions.
|
Package registry provides registries for namespaces and resource definitions. |
Click to show internal directories.
Click to hide internal directories.