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
• WASM

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:

1. 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.

2. 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.

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 ResourceDefinitions and exposing them through the cup API.

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.

TemplateControllerSpec

WASMControllerSpec