[FEATURE] Plugin Architecture

[iwilltry42]

Goal

• plugin architecture for k3d, e.g. to add new nouns (like registry)

Let's use this issue to discuss potential solutions.

Notes

• k3d plugin install
  • k3d includes a plugin manager itself, so it can download, save and register plugins
• lifecycle hooks
  • some plugins may introduce new entities, managed by k3d which are tightly coupled to others
  • when a cluster is being created/deleted, such plugins have to react (e.g. by removing their own leftovers)
• Plugins can be "callables" or pure "lifecycle hooks"
  • callable like: k3d <plugin>
  • lifecycle hook like: k3d cluster create triggers <plugin> after creating the cluster
• k3d <plugin> FLAGS ARGS will call the plugin
  • ... and pass it all the flags and args
  • plugin can use/modify the flags and args
  • ... and pass a modified set of flags and args back to k3d
  • ... or exit without calling back to k3d

Example Installation Process

• k3d plugin install <user>/<repo>
  • downloads the latest release
  • optionally unpacks it if it's an archive
  • stores it in e.g. ~/.k3d/plugins/<user>/<repo>
  • fetches the plugin metadata
    • ... by calling it via <plugin> metadata
    • ... by extracting it from the archive
    • "registers" the plugins lifecycle hooks based on the metadata
      • e.g. by putting the respective code snippet in a file in a hook directory

@inercia

[inercia]

Some ideas borrowed from the CNI plugins spec:

• k3d could interact with plugins by executing them with the right environment variables set. The main entrypoint would be the K3D_COMMAND env variable, containing the operation invoked on the plugin. It could be:
  • INFO: the plugin would return a YAML with a short and long description, capabilities, hooks...
  • EXEC: k3d invokes the plugin because one of the hooks has been triggered. The name of the hook would be in the K3D_EVENT env var (ie, post-cluster-create)
• Some other environment variable that could be present are:
  • K3D_CLUSTER: (optional) the name of the cluster
  • K3D_DOCKER_NETWORK: (optional) the name of the docker network.
  • K3D_DOCKER_CONTROL: (optional) list of control plane containers. Alphanumeric key-value pairs separated by semicolons.
  • K3D_DOCKER_AGENTS: (optional) list of agent containers. Alphanumeric key-value pairs separated by semicolons.
  • some other env variables with information about k3d (ie, version, installation path...)
  • ...

Plugins would be supposed to be independent of each other and to have no invocation order.

Example:

For a post-cluster-create hook. The k3d would look for all the plugins interested in this event and, for each one, run the k3d-<plugin> with, for example, K3D_CLUSTER=k3d-cluster-1, K3D_EVENT=post-cluster-create, K3D_DOCKER_NETWORK=k3d-k3s-cluster-1, etc... In the case of the registry plugin, it would create the registry container and connect it to the K3D_NETWORK

[iwilltry42]

#333 brings us the simplest way of using plugin executables and follows the same principles as kubectl does.
Basically it tries to invoke plugin executables named k3d-plugin_name from the PATH if the used k3d command does not exist.
This checks off the "callables" part of the plugin architecture described in the issue description.

[FedericoAntoniazzi]

I started PR 714 without analyzing how other programs implemented their plugin system so I decided to take a step back, analyze better the problem and others implementations, discuss on #741 and then implement. Every idea is highly appreciated so feel free to reply to the discussion 😄