Skip to content

Commit 80dade1

Browse files
pinheadmzpinheadmz
authored
Merge pull request #670 from mplsgrant/2024-11-plugins
Plugin Architecture
2 parents 5039591 + 7311bc2 commit 80dade1

30 files changed

+1257
-24
lines changed

‎.github/workflows/test.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ jobs:
4949
- rpc_test.py
5050
- services_test.py
5151
- signet_test.py
52+
- simln_test.py
5253
- scenarios_test.py
5354
- namespace_admin_test.py
5455
steps:

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Monitor and analyze the emergent behaviors of Bitcoin networks.
1717
- [Installation](/docs/install.md)
1818
- [CLI Commands](/docs/warnet.md)
1919
- [Network configuration with yaml files](/docs/config.md)
20+
- [Plugins](/docs/plugins.md)
2021
- [Scenarios](/docs/scenarios.md)
2122
- [Monitoring](/docs/logging_monitoring.md)
2223
- [Snapshots](/docs/snapshots.md)

‎docs/plugins.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Plugins
2+
3+
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.
4+
5+
## Activating plugins from `network.yaml`
6+
7+
You can activate a plugin command by placing it in the `plugins` section at the bottom of each `network.yaml` file like so:
8+
9+
````yaml
10+
nodes:
11+
<<snip>>
12+
13+
plugins: # This marks the beginning of the plugin section
14+
preDeploy: # This is a hook. This particular hook will call plugins before deploying anything else.
15+
hello: # This is the name of the plugin.
16+
entrypoint: "../plugins/hello" # Every plugin must specify a path to its entrypoint.
17+
podName: "hello-pre-deploy" # Plugins can have their own particular configurations, such as how to name a pod.
18+
helloTo: "preDeploy!" # This configuration tells the hello plugin who to say "hello" to.
19+
````
20+
21+
## Many kinds of hooks
22+
There are many hooks to the Warnet `deploy` command. The example below specifies them:
23+
24+
````yaml
25+
nodes:
26+
<<snip>>
27+
28+
plugins:
29+
preDeploy: # Plugins will run before any other `deploy` code.
30+
hello:
31+
entrypoint: "../plugins/hello"
32+
podName: "hello-pre-deploy"
33+
helloTo: "preDeploy!"
34+
postDeploy: # Plugins will run after all the `deploy` code has run.
35+
simln:
36+
entrypoint: "../plugins/simln"
37+
activity: '[{"source": "tank-0003-ln", "destination": "tank-0005-ln", "interval_secs": 1, "amount_msat": 2000}]'
38+
hello:
39+
entrypoint: "../plugins/hello"
40+
podName: "hello-post-deploy"
41+
helloTo: "postDeploy!"
42+
preNode: # Plugins will run before `deploy` launches a node (once per node).
43+
hello:
44+
entrypoint: "../plugins/hello"
45+
helloTo: "preNode!"
46+
postNode: # Plugins will run after `deploy` launches a node (once per node).
47+
hello:
48+
entrypoint: "../plugins/hello"
49+
helloTo: "postNode!"
50+
preNetwork: # Plugins will run before `deploy` launches the network (essentially between logging and when nodes are deployed)
51+
hello:
52+
entrypoint: "../plugins/hello"
53+
helloTo: "preNetwork!"
54+
podName: "hello-pre-network"
55+
postNetwork: # Plugins will run after the network deploy threads have been joined.
56+
hello:
57+
entrypoint: "../plugins/hello"
58+
helloTo: "postNetwork!"
59+
podName: "hello-post-network"
60+
````
61+
62+
Warnet will execute these plugin commands during each invocation of `warnet deploy`.
63+
64+
65+
66+
## A "hello" example
67+
68+
To get started with an example plugin, review the `README` of the `hello` plugin found in any initialized Warnet directory:
69+
70+
1. `warnet init`
71+
2. `cd plugins/hello/`
72+

‎resources/networks/hello/network.yaml

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
nodes:
2+
- name: tank-0000
3+
addnode:
4+
- tank-0001
5+
ln:
6+
lnd: true
7+
8+
- name: tank-0001
9+
addnode:
10+
- tank-0002
11+
ln:
12+
lnd: true
13+
14+
- name: tank-0002
15+
addnode:
16+
- tank-0000
17+
ln:
18+
lnd: true
19+
20+
- name: tank-0003
21+
addnode:
22+
- tank-0000
23+
ln:
24+
lnd: true
25+
lnd:
26+
config: |
27+
bitcoin.timelockdelta=33
28+
channels:
29+
- id:
30+
block: 300
31+
index: 1
32+
target: tank-0004-ln
33+
capacity: 100000
34+
push_amt: 50000
35+
36+
- name: tank-0004
37+
addnode:
38+
- tank-0000
39+
ln:
40+
lnd: true
41+
lnd:
42+
channels:
43+
- id:
44+
block: 300
45+
index: 2
46+
target: tank-0005-ln
47+
capacity: 50000
48+
push_amt: 25000
49+
50+
- name: tank-0005
51+
addnode:
52+
- tank-0000
53+
ln:
54+
lnd: true
55+
56+
plugins: # Each plugin section has a number of hooks available (preDeploy, postDeploy, etc)
57+
preDeploy: # For example, the preDeploy hook means it's plugin will run before all other deploy code
58+
hello:
59+
entrypoint: "../../plugins/hello" # This entrypoint path is relative to the network.yaml file
60+
podName: "hello-pre-deploy"
61+
helloTo: "preDeploy!"
62+
postDeploy:
63+
hello:
64+
entrypoint: "../../plugins/hello"
65+
podName: "hello-post-deploy"
66+
helloTo: "postDeploy!"
67+
simln: # You can have multiple plugins per hook
68+
entrypoint: "../../plugins/simln"
69+
activity: '[{"source": "tank-0003-ln", "destination": "tank-0005-ln", "interval_secs": 1, "amount_msat": 2000}]'
70+
preNode: # preNode plugins run before each node is deployed
71+
hello:
72+
entrypoint: "../../plugins/hello"
73+
helloTo: "preNode!"
74+
postNode:
75+
hello:
76+
entrypoint: "../../plugins/hello"
77+
helloTo: "postNode!"
78+
preNetwork:
79+
hello:
80+
entrypoint: "../../plugins/hello"
81+
helloTo: "preNetwork!"
82+
podName: "hello-pre-network"
83+
postNetwork:
84+
hello:
85+
entrypoint: "../../plugins/hello"
86+
helloTo: "postNetwork!"
87+
podName: "hello-post-network"

‎resources/networks/hello/node-defaults.yaml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
image:
2+
repository: bitcoindevproject/bitcoin
3+
pullPolicy: IfNotPresent
4+
tag: "27.0"
5+
6+
lnd:
7+
defaultConfig: |
8+
color=#000000

‎resources/plugins/__init__.py

Whitespace-only changes.

‎resources/plugins/hello/README.md

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Hello Plugin
2+
3+
## Hello World!
4+
*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).
5+
6+
## Usage
7+
In your python virtual environment with Warnet installed and setup, create a new Warnet user folder (follow the prompts):
8+
9+
`$ warnet new user_folder`
10+
11+
`$ cd user_folder`
12+
13+
Deploy the *hello* network.
14+
15+
`$ warnet deploy networks/hello`
16+
17+
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.
18+
19+
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.
20+
21+
Once `deploy` completes, view the pods of the *hello* network by invoking `kubectl get all -A`.
22+
23+
To view the various "Hello World!" messages, run `kubectl logs pod/POD_NAME`
24+
25+
### A `network.yaml` example
26+
When you initialize a new Warnet network, Warnet will create a new `network.yaml` file. You can modify these files to fit your needs.
27+
28+
For example, the `network.yaml` file below includes the *hello* plugin, lightning nodes, and the *simln* plugin.
29+
30+
<details>
31+
<summary>network.yaml</summary>
32+
33+
````yaml
34+
nodes:
35+
- name: tank-0000
36+
addnode:
37+
- tank-0001
38+
ln:
39+
lnd: true
40+
41+
- name: tank-0001
42+
addnode:
43+
- tank-0002
44+
ln:
45+
lnd: true
46+
47+
- name: tank-0002
48+
addnode:
49+
- tank-0000
50+
ln:
51+
lnd: true
52+
53+
- name: tank-0003
54+
addnode:
55+
- tank-0000
56+
ln:
57+
lnd: true
58+
lnd:
59+
config: |
60+
bitcoin.timelockdelta=33
61+
channels:
62+
- id:
63+
block: 300
64+
index: 1
65+
target: tank-0004-ln
66+
capacity: 100000
67+
push_amt: 50000
68+
69+
- name: tank-0004
70+
addnode:
71+
- tank-0000
72+
ln:
73+
lnd: true
74+
lnd:
75+
channels:
76+
- id:
77+
block: 300
78+
index: 2
79+
target: tank-0005-ln
80+
capacity: 50000
81+
push_amt: 25000
82+
83+
- name: tank-0005
84+
addnode:
85+
- tank-0000
86+
ln:
87+
lnd: true
88+
89+
plugins: # Each plugin section has a number of hooks available (preDeploy, postDeploy, etc)
90+
preDeploy: # For example, the preDeploy hook means it's plugin will run before all other deploy code
91+
hello:
92+
entrypoint: "../../plugins/hello" # This entrypoint path is relative to the network.yaml file
93+
podName: "hello-pre-deploy"
94+
helloTo: "preDeploy!"
95+
postDeploy:
96+
hello:
97+
entrypoint: "../../plugins/hello"
98+
podName: "hello-post-deploy"
99+
helloTo: "postDeploy!"
100+
simln: # You can have multiple plugins per hook
101+
entrypoint: "../../plugins/simln"
102+
activity: '[{"source": "tank-0003-ln", "destination": "tank-0005-ln", "interval_secs": 1, "amount_msat": 2000}]'
103+
preNode: # preNode plugins run before each node is deployed
104+
hello:
105+
entrypoint: "../../plugins/hello"
106+
helloTo: "preNode!"
107+
postNode:
108+
hello:
109+
entrypoint: "../../plugins/hello"
110+
helloTo: "postNode!"
111+
preNetwork:
112+
hello:
113+
entrypoint: "../../plugins/hello"
114+
helloTo: "preNetwork!"
115+
podName: "hello-pre-network"
116+
postNetwork:
117+
hello:
118+
entrypoint: "../../plugins/hello"
119+
helloTo: "postNetwork!"
120+
podName: "hello-post-network"
121+
````
122+
123+
</details>
124+

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
apiVersion: v2
2+
name: hello-chart
3+
description: A Helm chart for a hello Pod
4+
version: 0.1.0
5+
appVersion: "1.0"

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
apiVersion: v1
2+
kind: Pod
3+
metadata:
4+
name: {{ .Values.podName }}
5+
labels:
6+
app: {{ .Chart.Name }}
7+
spec:
8+
restartPolicy: Never
9+
containers:
10+
- name: {{ .Values.podName }}-container
11+
image: alpine:latest
12+
command: ["sh", "-c"]
13+
args:
14+
- echo "Hello {{ .Values.helloTo }}";
15+
resources: {}

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
podName: hello-pod
2+
helloTo: "world"

0 commit comments

Comments
 (0)