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
main is the entrypoint for the controller runtime.
|
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/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/protobuf
Package protobuf provides wrappers/adapters between gRPC service and runtime.Engine.
|
Package protobuf provides wrappers/adapters between gRPC service and runtime.Engine. |
|
controller/protobuf/client
Package client provides a wrapper around gRPC Runtime client to present it as controller.Engine interface.
|
Package client provides a wrapper around gRPC Runtime client to present it as controller.Engine interface. |
|
controller/protobuf/server
Package server provides a wrapper around controller.Runtime over gRPC.
|
Package server provides a wrapper around controller.Runtime over gRPC. |
|
controller/runtime
Package runtime implements the controller runtime.
|
Package runtime implements the controller runtime. |
|
controller/runtime/dependency
Package dependency implements the dependency handling database.
|
Package dependency implements the dependency handling database. |
|
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. |
|
internal/xutil
Package xutil provides type-safe wrappers around sync.Map.
|
Package xutil provides type-safe wrappers around sync.Map. |
|
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/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.