Plugin System - Plugin Management

[FedericoAntoniazzi]

K3d plugin system

Why this discussion

This discussion has been created after trying to implement the plugin system in #714 for the first time but I decided to rewrite it for a better code organization, implementing some cool ideas and having a feedback from the community. In fact, every comment in this discussion will be considered and added to the final realization! 😃

I would like to use this discussion as a draft for the documentation so every hint, improvements on ideas even about English grammar or lexicon is highly appreciated.

Roadmap

Here is a basic roadmap for this feature, once one step has been implemented and tested, we'll move to the next one.

1. Plugin Management (this discussion)
2. Callables
3. Lifecycle hooks

References

• Original issue: [FEATURE] Plugin Architecture #304
• Old Pull Request: [FEATURE] Plugin System #714
• New Pull Request: Feature: Add plugin system - plugin execution #1040
• Existing implementations:
  • Krew: https://github.com/kubernetes-sigs/krew
  • Helm: https://github.com/helm/helm

Features

Plugins

A plugin is an executable file that could be either a binary or a script (e.g sh) that can be downloaded using HTTP from any VCS like GitHub Release and GitLab Release or directly if a http endpoint is provided.

Every plugin needs to have a manifest i.e a yaml file that describes the plugin and maybe contain some info for runtime, variables and so on...
An example of a manifest could be:

name: pluginName
version: v0.0.0
short_description: Manifest Example
description: |-
    This is an example of a manifest file for a k3d plugin

Install

Usage

k3d plugin install PLUGIN [PLUGIN...]
k3d plugin install < plugins.txt

Description

Resolves its command-line or stdin arguments to packages at specific module versions and downloads the compatible artifact in the releases section into $HOME/.k3d/plugins/ folder.

To download a plugin or replace it to its latest version:
k3d plugin install example.com/user/repository
To download a plugin or replace it to a specific version:
k3d plugin install example.com/user/[email protected]

List

Usage

k3d plugin list
k3d plugin ls

Description

Lists all plugins in the $HOME/.k3d/plugins folder with their corresponding version and short description.

Plugin information is read from the manifest.

Remove

Usage

k3d plugin remove PLUGIN [PLUGIN...]
k3d plugin rm PLUGIN [PLUGIN...]

Description

Removes the given plugin(s) folder from $HOME/.k3d/plugins.

Filesystem organization

This feature will add a folder dedicated to plugins: $HOME/.k3d/plugins and it's structure is inspired by golang modules so $HOME/.k3d/plugins will have a folder for the source (e.g github.com) and every source will have a folder for the plugin executable and its manifest.

Here's an example:

.k3d/plugins
  github.com/
    federicoantoniazzi/
      plugin1/
        plugin
        manifest.yml
    user/
      plugin2/
        plugin
        manifest.yml

[FedericoAntoniazzi]

A plugin is an executable file that could be either a binary or a script (e.g sh) that can be downloaded using HTTP from any VCS like GitHub Release and GitLab Release or directly if a http endpoint is provided.

I noticed something wrong with this statement: How k3d can download a plugin by using a single http URL if it should download at least the plugin and the manifest?

The first solution that came in my mind is downloading an archive (e.g zip, tarball) that contains the plugin and others files, do you know another alternative or any suggestions?

[iwilltry42]

I think Helm does this in a great way: either from VCS or from a tarball (see https://helm.sh/docs/topics/plugins/#helm) 🤔

[FedericoAntoniazzi]

Helm handles its plugins by downloading the whole project (for VCS seems to be literally a git clone) and using git to set the versions and upgrades. Even though I like the way the helm team has organized the code, I think this doesn't support running compiled binaries except if you pack the binary and the manifest in a tarball.

When I first saw iwilltry42/k3d-test-plugin and #304 I thought you were looking for a solution that uses a binary file so I went for this option.

Adding the manifest brings us more flexibility therefore we can merge the two ideas and define some rules for downloading the plugin:

• If the user specifies an http endpoint of a tarball, download the tarball and extract it
• If a Release is found: download the release and the manifest
• Else: clone the git repository

This implies 2 things:

1. the manifest has to describe even the entrypoint (exactly how helm does)
2. There are 2 different ways to update the plugin
   • From VCS: just git pull updates
   • From Releases or tarball: replace the plugin files with updated ones (e.g. by removing the dir and re-extracting the new tarball)

What do you think about this idea?

[iwilltry42]

Yeah, I guess back then I was inspired by the simplicity of how kubectl handles plugins: just something with a defined naming-scheme somewhere in the $PATH, which is super simple.
But then there's the separate krew project which handles all the rest of the plugin ecosystem/logic for kubectl. There you have to submit your plugin manifest to a central krew plugin index repository so it's discoverable, which I feel could be overkill and too high of an entry burden for k3d plugins. (see https://krew.sigs.k8s.io/docs/developer-guide/ for info on how plugins are built for krew)
The points listed in your comment make total sense to me 👍

[FedericoAntoniazzi]

I noticed Helm installs local plugins by creating a symlink of the specified directory (e.g. the plugin repo you are working on) in the plugin folder. This could be an idea for installing local plugins and identifying the type

[FedericoAntoniazzi]

Another idea I would improve is changing the filesystem structure by ignoring if they have been downloaded from github, gitlab or any other host and using a simpler solution (like helm does): creating a folder with the name of the plugin.

This was the original idea and was implemented in #714

What do you think?

[iwilltry42]

The simpler the better I guess 👍

[FedericoAntoniazzi]

Hi everyone! I'm back! 😄

I'm re-analyzing the problem and looked at how helm and Hashicorp have implemented plugins in their platforms. Those examples implements two different methodologies, in fact the first one uses shell scripts meanwhile Hashicorp has its own way based on gRPC communication between the main process and other plugins.

In the past, we discussed about using Helm plugin system as a reference for implementing plugins in k3d so I tried to briefly sum up the concept:

• Plugins are stored in a dedicated folder (e.g. $HOME/.k3d/plugins)
• Installing a plugin means unpacking an archive (e.g. tar.gz) into the plugin folder
• Every plugin has a manifest that specifies its metadata. The plugin also specifies the command to use when invoking the plugin executable
• (Future improvement) Shell autocompletion

This is a quick overview about how I would implement plugins in k3d (and how helm does), what do you think?

[iwilltry42]

Welcome Back aboard :)

Without diving too deep into it, your proposal sounds simple yet solid 👍

[FedericoAntoniazzi]

Hello there, I tried implementing few solutions about plugin versioning but it's hard to think about a system for maintaining compatibility even with k3d versions.

Here's what I tried to add to a manifest of a plugin:

apiVersion: plugins.k3d.io/v1
name: ...
...

This means that k3d has to check if plugins.k3d.io/v1 version is supported, deprecated or out-of-support while keeping a compatibility layer with internal APIs.

Do you have any suggestions?

Reference: #1040

[iwilltry42]

Sounds like it's the same way that the configfile is handled.
But apiVersion is about the plugin manifest structure that k3d knows, right? Not about the version of the plugin, right?