You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: developing-plugins/grpc-api-reference.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
1
---
2
-
last_modified_date: 2024-04-16 09:21:37
2
+
last_modified_date: 2024-05-11 20:53:27
3
3
layout: default
4
4
title: gRPC API Reference
5
5
description: GatewayD exposes a gRPC API that can be used to interact with the GatewayD plugin system. This API can be used by the GatewayD plugins and is available in the GatewayD SDK.
Copy file name to clipboardExpand all lines: developing-plugins/plugin-developers-guide.md
+46-36Lines changed: 46 additions & 36 deletions
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
1
---
2
-
last_modified_date: 2024-04-16 09:21:36
2
+
last_modified_date: 2024-05-11 21:33:25
3
3
layout: default
4
4
title: Plugin Developers Guide
5
5
description: Plugin developers' guide of GatewayD
@@ -15,30 +15,29 @@ The usage of plugin from the user perspective is described [here](/using-plugins
15
15
16
16
Follow these steps to create a plugin:
17
17
18
-
1. Use the [GatewayD plugin template for Go](https://github.com/gatewayd-io/plugin-template-go) repository to create a new repository for your plugin.
19
-
2. Clone the repository and start developing your plugin.
20
-
3. Update the `gatewayd_plugins.yml` file with the correct information.
21
-
4. Test your plugin locally using the `make run` target of GatewayD.
22
-
5. Test your plugin in the CI pipeline.
23
-
6. Test your plugin using this [`test.yaml`](https://github.com/gatewayd-io/gatewayd-plugin-cache/blob/main/.github/workflows/test.yaml) workflow.
24
-
7. Publish your plugin to GitHub using this [`release.yaml`](https://github.com/gatewayd-io/gatewayd-plugin-cache/blob/main/.github/workflows/release.yaml) workflow and this [`Makefile`](https://github.com/gatewayd-io/gatewayd-plugin-cache/blob/main/Makefile).
25
-
8. Publish your plugin.
26
-
27
-
{: .note }
28
-
> You can also use the [GatewayD plugin template for Python](https://github.com/gatewayd-io/plugin-template-python) repository to create a new repository for your plugin. The project is not as mature as the Go template and might have some rough edges.
18
+
1. Generate a plugin scaffold using the `gatewayd plugin scaffold` command.
19
+
2. Update the `gatewayd_plugins.yml` file with the correct information.
20
+
3. Test your plugin locally using the `make run` target of GatewayD.
21
+
4. Test your plugin in the CI pipeline.
22
+
5. Test your plugin using this [`test.yaml`](https://github.com/gatewayd-io/gatewayd-plugin-cache/blob/main/.github/workflows/test.yaml) workflow.
23
+
6. Publish your plugin to GitHub using this [`release.yaml`](https://github.com/gatewayd-io/gatewayd/blob/main/plugin/.template/project/%7B%7B%20plugin_name%20%7D%7D/.github/workflows/release.yaml) workflow and this [`Makefile`](https://github.com/gatewayd-io/gatewayd/blob/main/plugin/.template/project/%7B%7B%20plugin_name%20%7D%7D/Makefile).
29
24
30
25
In the following sections, each step is described in more detail.
31
26
32
-
## Step 1: Use the GatewayD plugin template
27
+
## Step 1: Generate a plugin scaffold
33
28
34
-
The [GatewayD plugin template for Go](https://github.com/gatewayd-io/plugin-template-go)repository contains a template for a plugin. You can use this template to create a new repository for your plugin. As a concrete example, the [cache plugin](https://github.com/gatewayd-io/gatewayd-plugin-cache)contains a `Makefile` and a GitHub workflow to test and release your plugin.
29
+
The `gatewayd plugin scaffold` command generates a plugin scaffold for you. You can use the scaffolds, which is based on the [GatewayD plugin template for Go](https://github.com/gatewayd-io/plugin-template-go)project, to create your own plugin. The generated scaffold contains all the hooks you can use with typical message payloads, which you can safely remove. The scaffold contains all the necessary workflows, `Makefile` and metadata files to get you started quickly.
35
30
36
-
You can always start from scratch, but it is recommended to use the template to get started quickly.
31
+
{: .note}
32
+
> Previously, the [GatewayD plugin template for Go](https://github.com/gatewayd-io/plugin-template-go) project could be used to create a plugin. This project is now deprecated and the `gatewayd plugin scaffold` command should be used instead.
37
33
38
-
This is the structure of the template:
34
+
This is the structure of the generated directory with the scaffold command:
39
35
40
36
```bash
41
37
.
38
+
├── .github/workflows/
39
+
│ ├── commits-signed.yaml # Check if commits are signed
40
+
│ └── release.yaml # Release workflow
42
41
├── gatewayd_plugin.yaml # Metadata
43
42
├── go.mod # Dependencies
44
43
├── go.sum
@@ -53,11 +52,24 @@ This is the structure of the template:
53
52
└── README.md # Documentation
54
53
```
55
54
56
-
## Step 2: Clone the repository and start developing your plugin
55
+
To run the command, you need to have an `input.yaml` file that contains the following information. This file is used to scaffold the plugin, which you can find an example [here](https://raw.githubusercontent.com/gatewayd-io/gatewayd/main/plugin/.template/input.example.yaml).
After you have created the `input.yaml` file, run the following command to generate the plugin scaffold:
57
67
58
-
After you have created a new repository for your plugin, clone it and start developing your plugin. The template contains a `Makefile` with targets to build the plugin, create checksum and update dependencies. You can use these targets to build your plugin.
## Step 3: Update the `gatewayd_plugins.yml` file with the correct information
72
+
## Step 2: Update the `gatewayd_plugins.yml` file with the correct information
61
73
62
74
The `gatewayd_plugins.yml` file contains the metadata of your plugin. This file is used by GatewayD to load your plugin. The following fields are required:
63
75
@@ -71,12 +83,15 @@ The following fields are optional:
71
83
- `args`: The arguments that are passed to the plugin.
72
84
- `checksum`: The checksum of the plugin binary.
73
85
74
-
These two environment variables with their exact values are required. They must be passed to the [HandshakeConfig](https://github.com/gatewayd-io/plugin-template-go/blob/c103e739467a9814086508e1e8257871c00932e4/main.go#L44-L45) of the plugin. These pieces of information are used by GatewayD to verify and load the plugin:
86
+
{: .note }
87
+
> Use the `./gatewayd run --dev` command to disable plugin checksum verification when developing a plugin. Otherwise, the plugin will not be loaded or you must change the checksum every time you make a change to the plugin. **This is not recommended for production.**
88
+
89
+
These two environment variables with their exact values are required. They must be passed to the [HandshakeConfig](https://github.com/gatewayd-io/gatewayd/blob/1709235b0629fc591b29473551f8f623926662cb/plugin/.template/project/%7B%7B%20plugin_name%20%7D%7D/main.go#L44-L45) of the plugin. These pieces of information are used by GatewayD to verify and load the plugin:
## Step 4: Test your plugin locally using the `make run` target of GatewayD
94
+
## Step 3: Test your plugin locally using the `make run` target of GatewayD
80
95
81
96
You can test your plugin locally by running GatewayD CLI in development mode. The development mode lets your test your plugin without checksum verification. For more information, see GatewayD [CLI](/using-gatewayd/CLI).
82
97
@@ -90,32 +105,27 @@ You can test your plugin locally by running GatewayD CLI in development mode. Th
90
105
{: .note }
91
106
> It is recommended to use the `trace` log level to see the logs of your plugin. For more information, see [loggers](/using-gatewayd/global-configuration/loggers).
92
107
93
-
## Step 5: Test your plugin in the CI pipeline
108
+
## Step 4: Test your plugin in the CI pipeline
94
109
95
110
Copy the [`test-plugin`](https://github.com/gatewayd-io/gatewayd/blob/213ba09fbf20f0b3923d246d4320dab46fdf8be3/.github/workflows/test.yaml#L61-L144) job of the GatewayD CI pipeline into the `.github/workflows/test.yaml` file. This job will test your plugin using the [GatewayD CLI](/using-gatewayd/CLI) in development mode.
96
111
97
-
## Step 6: Test your plugin using this `test.yaml` workflow
112
+
## Step 5: Test your plugin using this `test.yaml` workflow
98
113
99
114
If you have written tests for your plugin, you can use the following workflow to test your plugin. Copy the [`test.yaml`](https://github.com/gatewayd-io/gatewayd-plugin-cache/blob/main/.github/workflows/test.yaml) workflow into the `.github/workflows/` directory of your plugin. This workflow will test your plugin using the [GatewayD CLI](/using-gatewayd/CLI) in development mode.
100
115
101
-
## Step 7: Publish your plugin to GitHub using this `release.yaml` workflow and this `Makefile`
102
-
103
-
If you want to publish your plugin to GitHub, you can use the following workflow and `Makefile` to release your plugin. Copy the [`release.yaml`](https://github.com/gatewayd-io/gatewayd-plugin-cache/blob/main/.github/workflows/release.yaml) workflow and this [`Makefile`](https://github.com/gatewayd-io/gatewayd-plugin-cache/blob/main/Makefile) into the `.github/workflows/` and the root directory of your plugin. This workflow will release your plugin to GitHub.
104
-
105
-
{: .note }
106
-
> You must modify the example `Makefile`, `release.yaml` and `test.yaml` files to match your plugin.
116
+
## Step 6: Publish your plugin to GitHub
107
117
108
-
## Step 8: Publish your plugin
118
+
If you want to publish your plugin to GitHub, you can use the `release.yaml` workflow and `Makefile` that are generated as part of the scaffold files in the `.github/workflows` directory. All you have to do is to push your changes to your desired GitHub repository and create a release with the tag, for example v0.1.0. The workflow will [build](https://github.com/gatewayd-io/gatewayd/blob/51bb3a48edd783ff623234c8c34c4bfa335ae045/plugin/.template/project/%7B%7B%20plugin_name%20%7D%7D/Makefile#L25-L32) your plugin for three platforms and two CPU architectures, create a release with the given tag, and upload the plugin binaries (as archive files) and `checksums.txt` as release assets, just like [this](https://github.com/gatewayd-io/gatewayd-plugin-cache/releases/latest).
109
119
110
-
If you want GatewayD to install your plugin from GitHub, you must adhere to the following rules:
120
+
Now, if you want GatewayD to install your plugin from GitHub, you must adhere to the following rules:
111
121
112
122
1. The plugin binary must be named as the repository name, aka. the plugin name.
113
123
2. The plugin binary must be placed in the root directory of the release asset.
114
-
3.The checksums should be generated using sha256sum, published as release assets and named `checksums.txt`.
115
-
4. The release assets must be published as `tar.gz` archives.
116
-
5. The release assets must follow the naming convention: `plugin-name-$GOOS-$GOARCH-version.tar.gz`.
117
-
6. The releases must follow semantic versioning and prefixed with `v`.
118
-
7. The `latest` release must point to the latest release, otherwise the plugin will not be installed if the version is not specified.
124
+
3. Each published release asset that contains a plugin binary must also have a `checksum.txt` file next to the plugin binary in the archive file containing the checksum of the plugin binary.
125
+
4. The checksums of all the release assets should be generated using sha256sum, and published as release assets, and named `checksums.txt`.
126
+
5. The release assets must be published as `tar.gz` or `.zip` archives.
127
+
6. The release assets must follow the naming convention: `plugin-name-$GOOS-$GOARCH-version.tar.gz`. For example, `gatewayd-plugin-cache-linux-amd64-v0.1.0.tar.gz`.
128
+
7. The name of the archive files in the release assets must follow semantic versioning and prefixed with `v`.
119
129
120
130
<!-- ## Step 9: Publish your plugin to the GatewayD plugin registry
0 commit comments