Controllers
Controllers are the engines that drive reading and writing changes to target configuration sources (directories, repositories etc.). Internally, Cup abstracts away the details of Git repositories, commits, trees, and pull requests. Controllers focus on handling individual actions over a mounted target directory.
These actions currently include:
- get
- list
- put
- delete
Each controller is configured via a JSON file in the -api-resources
directory.
There are currently two types of controller configurable in Cup:
Template
Is a simple, built-in controller which uses Go's text/template
to perform 1:1 API resource to file in repo mappings.
There exist two templates:
- Directory Template
This is used during list
operations to map a namespace onto a target directory exclusively containing files that each represent a single resource instance.
It can be configured with glob syntax to further constrain, which files in a target directory are considered resources.
- Path Template
This is used during get
, put
, and delete
operations to identify the particular file the resource should be read from, written to, or deleted respectively.
{
"apiVersion": "cup.flipt.io/v1alpha1",
"kind": "Controller",
"metadata": {
"name": "some-template-controller"
},
"spec": {
"type": "template",
"spec": {
"directory_template": "{{ .Namespace }}/*.json",
"path_template": "{{ .Namespace }}/{{ .Group }}-{{ .Version }}-{{ .Kind }}-{{ .Name }}.json"
}
}
}
WASM
The WASM controller is an extension point that opens Cup up to the full power of languages which can be compiled to WASM with the WASIP1 extensions. Given your controller can be expressed as a command-line tool, conforming to Cup's well-defined set of sub-commands and standard I/O expectations, implemented in a language compiled to WASM with WASIP1, then it can be used in Cup.
To learn more about the binary API required for a Cup WASM controller, check out the Design document in this repo. Cup is a very early prototype and this design is likely to change and open to suggestions.
Given your resulting controller WASM binary is present and reachable on the filesystem by cupd
, then it can be leveraged by Cup to handle your particular resource management needs.
The Controller resource specification includes a single field path
which should point to where the WASM implementation exists on disk.
This path will resolve relative to the -api-resources
directory.
{
"apiVersion": "cup.flipt.io/v1alpha1",
"kind": "Controller",
"metadata": {
"name": "flipt"
},
"spec": {
"type": "wasm",
"spec": {
"path": "flipt.wasm"
}
}
}
Specification
Resource
Each controller resource definition has the following top-level fields.
Both apiVersion
and kind
are fixed constants, but metadata
and spec
can be configured accordingly.
Key | Value |
---|---|
apiVersion | "cup.flipt.io/v1alpha1" |
kind | "Controller" |
metadata | <Metadata> |
spec | <ControllerSpec> |
Metadata
Controllers have a single metadata string field name
.
Each configured controller should be uniquely named.
These names are referenced in APIBinding
resources when associating them with ResourceDefinition
s and exposing them through the cup API.
Key | Value |
---|---|
name | string |
ControllerSpec
The controller specification contains an initial type
field which signifies the type of the controller.
Depending on the type
field value, the spec
field will contain the corresponding specification for the controller type.
Key | Value |
---|---|
type | ["template" | "wasm"] |
spec | <TemplateControllerSpec> | <WASMControllerSpec> |
TemplateControllerSpec
Key | Value | Description |
---|---|---|
directory_template | string | Go text/template string which is rendered on list operations to identify where to source resource files. The result can be a glob syntax to further narrow the selection criteria. |
path_template | string | Go text/template string which is rendered on get , put and delete operations to identify a specific resource by apiVersion, kind, namespace and name. |
WASMControllerSpec
Key | Value | Description |
---|---|---|
path | string | Path on disk (relative to the -api-resources directory configuration flag) to the controllers WASM binary file. |