Plugin Architecture

.github/workflows/test.yml

@@ -51,6 +51,7 @@ jobs:
  - signet_test.py
  - scenarios_test.py
  - namespace_admin_test.py
+ - simln_test.py
  steps:
  - uses: actions/checkout@v4
  - uses: azure/setup-helm@v4.2.0

README.md

@@ -17,6 +17,7 @@ Monitor and analyze the emergent behaviors of Bitcoin networks.
 - [Installation](/docs/install.md)
 - [CLI Commands](/docs/warnet.md)
 - [Network configuration with yaml files](/docs/config.md)
+- [Plugins](/docs/plugins.md)
 - [Scenarios](/docs/scenarios.md)
 - [Monitoring](/docs/logging_monitoring.md)
 - [Snapshots](/docs/snapshots.md)

docs/plugins.md

@@ -0,0 +1,72 @@
+# Plugins
+
+Plugins extend Warnet. Plugin authors can import commands from Warnet and interact with the kubernetes cluster, and plugin users can run plugins from the command line or from the `network.yaml` file.
+
+## Activating plugins from `network.yaml`
+
+You can activate a plugin command by placing it in the `plugins` section at the bottom of each `network.yaml` file like so:
+
+````yaml
+nodes:
+ <<snip>>
+
+plugins: # This marks the beginning of the plugin section
+ preDeploy: # This is a hook. This particular hook will call plugins before deploying anything else.
+ hello: # This is the name of the plugin.
+ entrypoint: "../plugins/hello" # Every plugin must specify a path to its entrypoint.
+ podName: "hello-pre-deploy" # Plugins can have their own particular configurations, such as how to name a pod.
+ helloTo: "preDeploy!" # This configuration tells the hello plugin who to say "hello" to.
+````
+
+## Many kinds of hooks
+There are many hooks to the Warnet `deploy` command. The example below specifies them:
+
+````yaml
+nodes:
+ <<snip>>
+
+plugins:
+ preDeploy: # Plugins will run before any other `deploy` code.
+ hello:
+ entrypoint: "../plugins/hello"
+ podName: "hello-pre-deploy"
+ helloTo: "preDeploy!"
+ postDeploy: # Plugins will run after all the `deploy` code has run.
+ simln:
+ entrypoint: "../plugins/simln"
+ activity: '[{"source": "tank-0003-ln", "destination": "tank-0005-ln", "interval_secs": 1, "amount_msat": 2000}]'
+ hello:
+ entrypoint: "../plugins/hello"
+ podName: "hello-post-deploy"
+ helloTo: "postDeploy!"
+ preNode: # Plugins will run before `deploy` launches a node (once per node).
+ hello:
+ entrypoint: "../plugins/hello"
+ helloTo: "preNode!"
+ postNode: # Plugins will run after `deploy` launches a node (once per node).
+ hello:
+ entrypoint: "../plugins/hello"
+ helloTo: "postNode!"
+ preNetwork: # Plugins will run before `deploy` launches the network (essentially between logging and when nodes are deployed)
+ hello:
+ entrypoint: "../plugins/hello"
+ helloTo: "preNetwork!"
+ podName: "hello-pre-network"
+ postNetwork: # Plugins will run after the network deploy threads have been joined.
+ hello:
+ entrypoint: "../plugins/hello"
+ helloTo: "postNetwork!"
+ podName: "hello-post-network"
+````
+
+Warnet will execute these plugin commands during each invocation of `warnet deploy`.
+
+
+
+## A "hello" example
+
+To get started with an example plugin, review the `README` of the `hello` plugin found in any initialized Warnet directory:
+
+1. `warnet init`
+2. `cd plugins/hello/`
+

resources/networks/hello/network.yaml

@@ -0,0 +1,87 @@
+nodes:
+ - name: tank-0000
+ addnode:
+ - tank-0001
+ ln:
+ lnd: true
+
+ - name: tank-0001
+ addnode:
+ - tank-0002
+ ln:
+ lnd: true
+
+ - name: tank-0002
+ addnode:
+ - tank-0000
+ ln:
+ lnd: true
+
+ - name: tank-0003
+ addnode:
+ - tank-0000
+ ln:
+ lnd: true
+ lnd:
+ config: |
+ bitcoin.timelockdelta=33
+ channels:
+ - id:
+ block: 300
+ index: 1
+ target: tank-0004-ln
+ capacity: 100000
+ push_amt: 50000
+
+ - name: tank-0004
+ addnode:
+ - tank-0000
+ ln:
+ lnd: true
+ lnd:
+ channels:
+ - id:
+ block: 300
+ index: 2
+ target: tank-0005-ln
+ capacity: 50000
+ push_amt: 25000
+
+ - name: tank-0005
+ addnode:
+ - tank-0000
+ ln:
+ lnd: true
+
+plugins: # Each plugin section has a number of hooks available (preDeploy, postDeploy, etc)
+ preDeploy: # For example, the preDeploy hook means it's plugin will run before all other deploy code
+ hello:
+ entrypoint: "../../plugins/hello" # This entrypoint path is relative to the network.yaml file
+ podName: "hello-pre-deploy"
+ helloTo: "preDeploy!"
+ postDeploy:
+ hello:
+ entrypoint: "../../plugins/hello"
+ podName: "hello-post-deploy"
+ helloTo: "postDeploy!"
+ simln: # You can have multiple plugins per hook
+ entrypoint: "../../plugins/simln"
+ activity: '[{"source": "tank-0003-ln", "destination": "tank-0005-ln", "interval_secs": 1, "amount_msat": 2000}]'
+ preNode: # preNode plugins run before each node is deployed
+ hello:
+ entrypoint: "../../plugins/hello"
+ helloTo: "preNode!"
+ postNode:
+ hello:
+ entrypoint: "../../plugins/hello"
+ helloTo: "postNode!"
+ preNetwork:
+ hello:
+ entrypoint: "../../plugins/hello"
+ helloTo: "preNetwork!"
+ podName: "hello-pre-network"
+ postNetwork:
+ hello:
+ entrypoint: "../../plugins/hello"
+ helloTo: "postNetwork!"
+ podName: "hello-post-network"

resources/networks/hello/node-defaults.yaml

@@ -0,0 +1,8 @@
+image:
+ repository: bitcoindevproject/bitcoin
+ pullPolicy: IfNotPresent
+ tag: "27.0"
+
+lnd:
+ defaultConfig: |
+ color=#000000

resources/plugins/hello/README.md

@@ -0,0 +1,124 @@
+# Hello Plugin
+
+## Hello World!
+*Hello* is an example plugin to demonstrate the features of Warnet's plugin architecture. It uses each of the hooks available in the `warnet deploy` command (see the example below for details).
+
+## Usage
+In your python virtual environment with Warnet installed and setup, create a new Warnet user folder (follow the prompts):
+
+`$ warnet new user_folder`
+
+`$ cd user_folder`
+
+Deploy the *hello* network.
+
+`$ warnet deploy networks/hello`
+
+While that is launching, take a look inside the `networks/hello/network.yaml` file. You can also see the copy below which includes commentary on the structure of plugins in the `network.yaml` file.
+
+Also, take a look at the `plugins/hello/plugin.py` file to see how plugins work and to find out how to author your own plugin.
+
+Once `deploy` completes, view the pods of the *hello* network by invoking `kubectl get all -A`.
+
+To view the various "Hello World!" messages, run `kubectl logs pod/POD_NAME`
+
+### A `network.yaml` example
+When you initialize a new Warnet network, Warnet will create a new `network.yaml` file. You can modify these files to fit your needs.
+
+For example, the `network.yaml` file below includes the *hello* plugin, lightning nodes, and the *simln* plugin.
+
+<details>
+<summary>network.yaml</summary>
+
+````yaml
+nodes:
+ - name: tank-0000
+ addnode:
+ - tank-0001
+ ln:
+ lnd: true
+
+ - name: tank-0001
+ addnode:
+ - tank-0002
+ ln:
+ lnd: true
+
+ - name: tank-0002
+ addnode:
+ - tank-0000
+ ln:
+ lnd: true
+
+ - name: tank-0003
+ addnode:
+ - tank-0000
+ ln:
+ lnd: true
+ lnd:
+ config: |
+ bitcoin.timelockdelta=33
+ channels:
+ - id:
+ block: 300
+ index: 1
+ target: tank-0004-ln
+ capacity: 100000
+ push_amt: 50000
+
+ - name: tank-0004
+ addnode:
+ - tank-0000
+ ln:
+ lnd: true
+ lnd:
+ channels:
+ - id:
+ block: 300
+ index: 2
+ target: tank-0005-ln
+ capacity: 50000
+ push_amt: 25000
+
+ - name: tank-0005
+ addnode:
+ - tank-0000
+ ln:
+ lnd: true
+
+plugins: # Each plugin section has a number of hooks available (preDeploy, postDeploy, etc)
+ preDeploy: # For example, the preDeploy hook means it's plugin will run before all other deploy code 
+ hello:
+ entrypoint: "../../plugins/hello" # This entrypoint path is relative to the network.yaml file
+ podName: "hello-pre-deploy"
+ helloTo: "preDeploy!"
+ postDeploy:
+ hello:
+ entrypoint: "../../plugins/hello"
+ podName: "hello-post-deploy"
+ helloTo: "postDeploy!"
+ simln: # You can have multiple plugins per hook
+ entrypoint: "../../plugins/simln"
+ activity: '[{"source": "tank-0003-ln", "destination": "tank-0005-ln", "interval_secs": 1, "amount_msat": 2000}]' 
+ preNode: # preNode plugins run before each node is deployed
+ hello:
+ entrypoint: "../../plugins/hello"
+ helloTo: "preNode!"
+ postNode:
+ hello:
+ entrypoint: "../../plugins/hello"
+ helloTo: "postNode!"
+ preNetwork:
+ hello:
+ entrypoint: "../../plugins/hello"
+ helloTo: "preNetwork!"
+ podName: "hello-pre-network"
+ postNetwork:
+ hello:
+ entrypoint: "../../plugins/hello"
+ helloTo: "postNetwork!"
+ podName: "hello-post-network"
+````
+
+</details>
+

resources/plugins/hello/charts/hello/Chart.yaml

@@ -0,0 +1,5 @@
+apiVersion: v2
+name: hello-chart
+description: A Helm chart for a hello Pod
+version: 0.1.0
+appVersion: "1.0"

resources/plugins/hello/charts/hello/templates/pod.yaml

@@ -0,0 +1,15 @@
+apiVersion: v1
+kind: Pod
+metadata:
+ name: {{ .Values.podName }}
+ labels:
+ app: {{ .Chart.Name }}
+spec:
+ restartPolicy: Never
+ containers:
+ - name: {{ .Values.podName }}-container
+ image: alpine:latest
+ command: ["sh", "-c"]
+ args:
+ - echo "Hello {{ .Values.helloTo }}";
+ resources: {}

resources/plugins/hello/charts/hello/values.yaml

@@ -0,0 +1,2 @@
+podName: hello-pod
+helloTo: "world"