Merge pull request #670 from mplsgrant/2024-11-plugins

Plugin Architecture

.github/workflows/test.yml

@@ -49,6 +49,7 @@ jobs:
           - rpc_test.py
           - services_test.py
           - signet_test.py
+          - simln_test.py
           - scenarios_test.py
           - namespace_admin_test.py
     steps:

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"