diff --git a/developing-plugins/grpc-api-reference.md b/developing-plugins/grpc-api-reference.md index 3f6d6c2..fe6e184 100644 --- a/developing-plugins/grpc-api-reference.md +++ b/developing-plugins/grpc-api-reference.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: gRPC API Reference 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. diff --git a/developing-plugins/index.md b/developing-plugins/index.md index 3b197c5..d74b3b3 100644 --- a/developing-plugins/index.md +++ b/developing-plugins/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Developing Plugins nav_order: 4 diff --git a/developing-plugins/plugin-developers-guide.md b/developing-plugins/plugin-developers-guide.md index 198757e..96333a9 100644 --- a/developing-plugins/plugin-developers-guide.md +++ b/developing-plugins/plugin-developers-guide.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:36 +last_modified_date: 2024-05-11 21:33:25 layout: default title: Plugin Developers Guide description: Plugin developers' guide of GatewayD @@ -15,30 +15,29 @@ The usage of plugin from the user perspective is described [here](/using-plugins Follow these steps to create a plugin: -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. -2. Clone the repository and start developing your plugin. -3. Update the `gatewayd_plugins.yml` file with the correct information. -4. Test your plugin locally using the `make run` target of GatewayD. -5. Test your plugin in the CI pipeline. -6. Test your plugin using this [`test.yaml`](https://github.com/gatewayd-io/gatewayd-plugin-cache/blob/main/.github/workflows/test.yaml) workflow. -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). -8. Publish your plugin. - -{: .note } -> 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. +1. Generate a plugin scaffold using the `gatewayd plugin scaffold` command. +2. Update the `gatewayd_plugins.yml` file with the correct information. +3. Test your plugin locally using the `make run` target of GatewayD. +4. Test your plugin in the CI pipeline. +5. Test your plugin using this [`test.yaml`](https://github.com/gatewayd-io/gatewayd-plugin-cache/blob/main/.github/workflows/test.yaml) workflow. +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). In the following sections, each step is described in more detail. -## Step 1: Use the GatewayD plugin template +## Step 1: Generate a plugin scaffold -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. +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. -You can always start from scratch, but it is recommended to use the template to get started quickly. +{: .note} +> 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. -This is the structure of the template: +This is the structure of the generated directory with the scaffold command: ```bash . +├── .github/workflows/ +│ ├── commits-signed.yaml # Check if commits are signed +│ └── release.yaml # Release workflow ├── gatewayd_plugin.yaml # Metadata ├── go.mod # Dependencies ├── go.sum @@ -53,11 +52,24 @@ This is the structure of the template: └── README.md # Documentation ``` -## Step 2: Clone the repository and start developing your plugin +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). + +```yaml +remote_url: https://github.com/me/gatewayd-plugin-test +version: 0.0.1 +description: This is test plugin +license: Apache-2.0 +authors: + - Me <me@example.com> +``` + +After you have created the `input.yaml` file, run the following command to generate the plugin scaffold: -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. +```bash +gatewayd plugin scaffold --input-file input.yaml --output-dir gatewayd-plugin-test +``` -## Step 3: Update the `gatewayd_plugins.yml` file with the correct information +## Step 2: Update the `gatewayd_plugins.yml` file with the correct information 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: @@ -71,12 +83,15 @@ The following fields are optional: - `args`: The arguments that are passed to the plugin. - `checksum`: The checksum of the plugin binary. -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: +{: .note } +> 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.** + +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: - `MAGIC_COOKIE_KEY=GATEWAYD_PLUGIN` - `MAGIC_COOKIE_VALUE=5712b87aa5d7e9f9e9ab643e6603181c5b796015cb1c09d6f5ada882bf2a1872` -## Step 4: Test your plugin locally using the `make run` target of GatewayD +## Step 3: Test your plugin locally using the `make run` target of GatewayD 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). @@ -90,32 +105,27 @@ You can test your plugin locally by running GatewayD CLI in development mode. Th {: .note } > 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). -## Step 5: Test your plugin in the CI pipeline +## Step 4: Test your plugin in the CI pipeline 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. -## Step 6: Test your plugin using this `test.yaml` workflow +## Step 5: Test your plugin using this `test.yaml` workflow 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. -## Step 7: Publish your plugin to GitHub using this `release.yaml` workflow and this `Makefile` - -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. - -{: .note } -> You must modify the example `Makefile`, `release.yaml` and `test.yaml` files to match your plugin. +## Step 6: Publish your plugin to GitHub -## Step 8: Publish your plugin +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). -If you want GatewayD to install your plugin from GitHub, you must adhere to the following rules: +Now, if you want GatewayD to install your plugin from GitHub, you must adhere to the following rules: 1. The plugin binary must be named as the repository name, aka. the plugin name. 2. The plugin binary must be placed in the root directory of the release asset. -3. The checksums should be generated using sha256sum, published as release assets and named `checksums.txt`. -4. The release assets must be published as `tar.gz` archives. -5. The release assets must follow the naming convention: `plugin-name-$GOOS-$GOARCH-version.tar.gz`. -6. The releases must follow semantic versioning and prefixed with `v`. -7. The `latest` release must point to the latest release, otherwise the plugin will not be installed if the version is not specified. +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. +4. The checksums of all the release assets should be generated using sha256sum, and published as release assets, and named `checksums.txt`. +5. The release assets must be published as `tar.gz` or `.zip` archives. +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`. +7. The name of the archive files in the release assets must follow semantic versioning and prefixed with `v`. <!-- ## Step 9: Publish your plugin to the GatewayD plugin registry diff --git a/developing-plugins/sdk-reference.md b/developing-plugins/sdk-reference.md index 53995bd..45619e1 100644 --- a/developing-plugins/sdk-reference.md +++ b/developing-plugins/sdk-reference.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: SDK Reference description: The GatewayD plugin SDK provides a number of interfaces, structs and methods to help you build your plugin. diff --git a/developing-plugins/template-projects.md b/developing-plugins/template-projects.md index c6c865c..c5d82ac 100644 --- a/developing-plugins/template-projects.md +++ b/developing-plugins/template-projects.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:36 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Template Projects description: Template projects can be used to quickly get started with developing plugins. diff --git a/getting-started/index.md b/getting-started/index.md index 1c4cad2..ae4b7e8 100644 --- a/getting-started/index.md +++ b/getting-started/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:36 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Getting Started nav_order: 1 diff --git a/getting-started/installation.md b/getting-started/installation.md index 520ee11..ea5b0d3 100644 --- a/getting-started/installation.md +++ b/getting-started/installation.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:36 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Installation description: How to install GatewayD and its plugins on different platforms and how to build it from source. diff --git a/getting-started/running-gatewayd.md b/getting-started/running-gatewayd.md index 90ea055..3c7f88f 100644 --- a/getting-started/running-gatewayd.md +++ b/getting-started/running-gatewayd.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:36 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Running GatewayD description: How to run GatewayD and test it with psql diff --git a/getting-started/welcome.md b/getting-started/welcome.md index f8fab85..cfe01de 100644 --- a/getting-started/welcome.md +++ b/getting-started/welcome.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 15:00:31 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Welcome description: Introduction to GatewayD and its key features diff --git a/miscellaneous/glossary.md b/miscellaneous/glossary.md index 86365b2..40d3e1f 100644 --- a/miscellaneous/glossary.md +++ b/miscellaneous/glossary.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Glossary description: Glossary of GatewayD terms diff --git a/miscellaneous/index.md b/miscellaneous/index.md index 65d721f..76caa20 100644 --- a/miscellaneous/index.md +++ b/miscellaneous/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Miscellaneous nav_order: 6 diff --git a/miscellaneous/telemetry-and-usage-report.md b/miscellaneous/telemetry-and-usage-report.md index 23e5280..eaa2992 100644 --- a/miscellaneous/telemetry-and-usage-report.md +++ b/miscellaneous/telemetry-and-usage-report.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Telemetry and Usage Report description: Telemetry and usage report of GatewayD diff --git a/plugins/gatewayd-plugin-cache.md b/plugins/gatewayd-plugin-cache.md index 3f2233a..b3b26f5 100644 --- a/plugins/gatewayd-plugin-cache.md +++ b/plugins/gatewayd-plugin-cache.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: gatewayd-plugin-cache description: GatewayD plugin for caching query results in Redis. diff --git a/plugins/gatewayd-plugin-js.md b/plugins/gatewayd-plugin-js.md index d4c3c87..04bc6c1 100644 --- a/plugins/gatewayd-plugin-js.md +++ b/plugins/gatewayd-plugin-js.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: gatewayd-plugin-js description: GatewayD plugin for running JS functions as hooks. diff --git a/plugins/index.md b/plugins/index.md index 5a5da13..62cb705 100644 --- a/plugins/index.md +++ b/plugins/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Plugins nav_order: 5 diff --git a/using-gatewayd/API.md b/using-gatewayd/API.md index a840e69..ecaf755 100644 --- a/using-gatewayd/API.md +++ b/using-gatewayd/API.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: API description: GatewayD exposes a gRPC API with an HTTP gateway for querying and managing the `gatewayd` process and its plugins. diff --git a/using-gatewayd/Act.md b/using-gatewayd/Act.md index 972cb86..14b61d5 100644 --- a/using-gatewayd/Act.md +++ b/using-gatewayd/Act.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Act description: Act is a policy engine that supports signals, policies and actions. It is used to automate the execution of business rules. diff --git a/using-gatewayd/CLI.md b/using-gatewayd/CLI.md index 977cfe3..e687483 100644 --- a/using-gatewayd/CLI.md +++ b/using-gatewayd/CLI.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: CLI description: GatewayD is a CLI application that runs on Windows, Linux-based distributions and macOS. @@ -11,20 +11,21 @@ parent: Using GatewayD GatewayD is a CLI application that runs on Windows, Linux-based distributions and macOS. The application has many subcommands that are explained below: -| Subcommand | Description | Flags/Example | -| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `completion` | generates the autocompletion script for the specified shell | - `bash`<br/>- `fish`<br/>- `powershell`<br/>- `zsh` | -| `config` | manages GatewayD global configuration | | -| `config init` | generates a global configuration file | - `-c`, `--config` global config file (default "gatewayd.yaml")<br/>- `-f`, `--force`: overwrites the existing config file<br/>- `--sentry`: Enable Sentry for error reporting (default `true`) | -| `config lint` | validates global configuration file | - `-c`, `--config` global config file (default "gatewayd.yaml") <br/>- `--sentry`: Enable Sentry for error reporting (default `true`) | -| `help` | shows help about any subcommand | The `-h` or `--help` flag can be used to get more information about a specific subcommand. | -| `plugin` | manages GatewayD plugins and their configurations | | -| `plugin init` | generates a plugins configuration file | - `-p`, `--plugin-config`: plugins config file (default "gatewayd_plugins.yaml")<br/>- `-f`, `--force`: overwrites the existing config file<br/>- `--sentry`: Enable Sentry for error reporting (default `true`) | -| `plugin install` | installs one or more plugins from:<br/>- CLI arguments (GitHub URL or a locally downloaded archive file)<br/>- the plugins configuration file | - `-p`, `--plugin-config`: plugins config file (default "gatewayd_plugins.yaml")<br/>- `-o`, `--output-dir`: output directory of the plugin, where the plugin is extracted (default "./plugins")<br/>- `-n`, `--name`: Name of the plugin (only for installing from archive files)<br/>- `--pull-only`: only pull the plugin, don't install it<br/>- `--cleanup`: Clean up the downloaded and extracted files after installing the plugin (except the plugin binary) (default `true`)<br/> - `--update`: Update the plugin if it already exists (default `false`)<br/>- `--backup`: Backup the plugins configuration file before installing the plugin (default `false`)<br/>- `--overwrite-config`: Overwrite the existing plugins configuration file (overrides `--update`, only used for installing from the plugins configuration file)<br/>- `--no-prompt`: Do not prompt for user input (default `true`)<br/>- `--skip-path-slip-verification`: Skip the path slip verification (default `false`). Use it only if you're using an absolute path for `--output-dir` in an isolated environment like Docker and you trust the source of the plugin<br/>- `--sentry`: Enable Sentry for error reporting (default `true`) | -| `plugin lint` | validates plugins configuration file | - `-p`, `--plugin-config`: plugins config file (default "gatewayd_plugins.yaml")<br/>- `--sentry`: Enable Sentry for error reporting (default `true`) | -| `plugin list` | lists all installed plugins | - `-p`, `--plugin-config`: plugins config file (default "gatewayd_plugins.yaml")<br/>- `-e`, `--only-enabled`: Only list enabled plugins<br/>- `--sentry`: Enable Sentry for error reporting (default `true`) | -| `run` | runs an instance of `gatewayd` with the specified configuration files | - `-c`, `--config`: global config file (default `"gatewayd.yaml"`)<br/>- `-p`, `--plugin-config`: plugin config file (default `"gatewayd_plugins.yaml"`)<br/>- `--tracing`: Enable tracing with OpenTelemetry via gRPC<br/>- `--collector-url string`: Collector URL of OpenTelemetry gRPC endpoint (default `"localhost:4317"`)<br/>- `--sentry`: Enable Sentry for error reporting (default `true`)<br/>- `--lint`: Enable linting of configuration files (default `true`)<br/>- `--dev`: Enable development mode for plugin development<br/>- `--usage-report`: Enable usage report (default `true`) | -| `version` | shows version information | `GatewayD v0.6.0 (2023-03-12T22:22:55+0000/ae469dc, go1.20.1, linux/amd64)` | +| Subcommand | Description | Flags/Example | +| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `completion` | generates the autocompletion script for the specified shell | - `bash`<br/>- `fish`<br/>- `powershell`<br/>- `zsh` | +| `config` | manages GatewayD global configuration | | +| `config init` | generates a global configuration file | - `-c`, `--config` global config file (default "gatewayd.yaml")<br/>- `-f`, `--force`: overwrites the existing config file<br/>- `--sentry`: Enable Sentry for error reporting (default `true`) | +| `config lint` | validates global configuration file | - `-c`, `--config` global config file (default "gatewayd.yaml") <br/>- `--sentry`: Enable Sentry for error reporting (default `true`) | +| `help` | shows help about any subcommand | The `-h` or `--help` flag can be used to get more information about a specific subcommand. | +| `plugin` | manages GatewayD plugins and their configurations | | +| `plugin init` | generates a plugins configuration file | - `-p`, `--plugin-config`: plugins config file (default "gatewayd_plugins.yaml")<br/>- `-f`, `--force`: overwrites the existing config file<br/>- `--sentry`: Enable Sentry for error reporting (default `true`) | +| `plugin install` | installs one or more plugins from:<br/>- CLI arguments (GitHub URL or a locally downloaded archive file)<br/>- the plugins configuration file | - `-p`, `--plugin-config`: plugins config file (default "gatewayd_plugins.yaml")<br/>- `-o`, `--output-dir`: output directory of the plugin, where the plugin is extracted (default "./plugins")<br/>- `-n`, `--name`: Name of the plugin (only for installing from archive files)<br/>- `--pull-only`: only pull the plugin, don't install it<br/>- `--cleanup`: Clean up the downloaded and extracted files after installing the plugin (except the plugin binary) (default `true`)<br/> - `--update`: Update the plugin if it already exists (default `false`)<br/>- `--backup`: Backup the plugins configuration file before installing the plugin (default `false`)<br/>- `--overwrite-config`: Overwrite the existing plugins configuration file (overrides `--update`, only used for installing from the plugins configuration file)<br/>- `--no-prompt`: Do not prompt for user input (default `true`)<br/>- `--skip-path-slip-verification`: Skip the path slip verification (default `false`). Use it only if you're using an absolute path for `--output-dir` in an isolated environment like Docker and you trust the source of the plugin<br/>- `--sentry`: Enable Sentry for error reporting (default `true`) | +| `plugin lint` | validates plugins configuration file | - `-p`, `--plugin-config`: plugins config file (default "gatewayd_plugins.yaml")<br/>- `--sentry`: Enable Sentry for error reporting (default `true`) | +| `plugin list` | lists all installed plugins | - `-p`, `--plugin-config`: plugins config file (default "gatewayd_plugins.yaml")<br/>- `-e`, `--only-enabled`: Only list enabled plugins<br/>- `--sentry`: Enable Sentry for error reporting (default `true`) | +| `plugin scaffold` | generates a plugin scaffold for plugin development and stores the files into a directory | - `-i`, `--input-file`: plugin scaffold input file (default "input.yaml")<br/>- `-o`, `--output-dir`: utput directory for the scaffold (default "./plugins") | +| `run` | runs an instance of `gatewayd` with the specified configuration files | - `-c`, `--config`: global config file (default `"gatewayd.yaml"`)<br/>- `-p`, `--plugin-config`: plugin config file (default `"gatewayd_plugins.yaml"`)<br/>- `--tracing`: Enable tracing with OpenTelemetry via gRPC<br/>- `--collector-url string`: Collector URL of OpenTelemetry gRPC endpoint (default `"localhost:4317"`)<br/>- `--sentry`: Enable Sentry for error reporting (default `true`)<br/>- `--lint`: Enable linting of configuration files (default `true`)<br/>- `--dev`: Enable development mode for plugin development<br/>- `--usage-report`: Enable usage report (default `true`) | +| `version` | shows version information | `GatewayD v0.6.0 (2023-03-12T22:22:55+0000/ae469dc, go1.20.1, linux/amd64)` | {: .note } > Please visit the [telemetry and usage report](/miscellaneous/telemetry-and-usage-report) page for more information on which pieces of data are collected by the service. diff --git a/using-gatewayd/clients.md b/using-gatewayd/clients.md index d9164da..30f4e96 100644 --- a/using-gatewayd/clients.md +++ b/using-gatewayd/clients.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Clients description: Client object is a client that can connect to the database servers over TCP, UDP and Unix Domain Socket. diff --git a/using-gatewayd/configuration.md b/using-gatewayd/configuration.md index 2a55024..4cc432a 100644 --- a/using-gatewayd/configuration.md +++ b/using-gatewayd/configuration.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Configuration description: GatewayD is fully configurable via various sources, including default values, YAML config files, environment variables, CLI flags and plugins. diff --git a/using-gatewayd/connection-lifecycle.md b/using-gatewayd/connection-lifecycle.md index 1d0ccfb..2f5a427 100644 --- a/using-gatewayd/connection-lifecycle.md +++ b/using-gatewayd/connection-lifecycle.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Connection Lifecycle description: Connection Lifecycle of GatewayD diff --git a/using-gatewayd/global-configuration/api.md b/using-gatewayd/global-configuration/api.md index 6e69c7b..6e5d4fe 100644 --- a/using-gatewayd/global-configuration/api.md +++ b/using-gatewayd/global-configuration/api.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: API description: GatewayD gRPC API configuration diff --git a/using-gatewayd/global-configuration/clients.md b/using-gatewayd/global-configuration/clients.md index aeda6f0..d85332a 100644 --- a/using-gatewayd/global-configuration/clients.md +++ b/using-gatewayd/global-configuration/clients.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Clients description: GatewayD client configuration diff --git a/using-gatewayd/global-configuration/index.md b/using-gatewayd/global-configuration/index.md index 8770703..106caa1 100644 --- a/using-gatewayd/global-configuration/index.md +++ b/using-gatewayd/global-configuration/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Global Configuration nav_order: 2 diff --git a/using-gatewayd/global-configuration/loggers.md b/using-gatewayd/global-configuration/loggers.md index 500b9c7..f90b7e6 100644 --- a/using-gatewayd/global-configuration/loggers.md +++ b/using-gatewayd/global-configuration/loggers.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Loggers description: GatewayD logger configuration diff --git a/using-gatewayd/global-configuration/metrics.md b/using-gatewayd/global-configuration/metrics.md index 6b27964..1792adf 100644 --- a/using-gatewayd/global-configuration/metrics.md +++ b/using-gatewayd/global-configuration/metrics.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Metrics description: GatewayD metrics configuration diff --git a/using-gatewayd/global-configuration/pools.md b/using-gatewayd/global-configuration/pools.md index 146f64f..06fc347 100644 --- a/using-gatewayd/global-configuration/pools.md +++ b/using-gatewayd/global-configuration/pools.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Pools description: GatewayD pool configuration diff --git a/using-gatewayd/global-configuration/proxies.md b/using-gatewayd/global-configuration/proxies.md index 17d978c..8afd62d 100644 --- a/using-gatewayd/global-configuration/proxies.md +++ b/using-gatewayd/global-configuration/proxies.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Proxies description: GatewayD proxy configuration diff --git a/using-gatewayd/global-configuration/servers.md b/using-gatewayd/global-configuration/servers.md index 23f500c..5a65043 100644 --- a/using-gatewayd/global-configuration/servers.md +++ b/using-gatewayd/global-configuration/servers.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Servers description: GatewayD server configuration diff --git a/using-gatewayd/index.md b/using-gatewayd/index.md index fb040cf..0a40515 100644 --- a/using-gatewayd/index.md +++ b/using-gatewayd/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Using GatewayD nav_order: 2 diff --git a/using-gatewayd/observability.md b/using-gatewayd/observability.md index cf1a9f4..df9cb08 100644 --- a/using-gatewayd/observability.md +++ b/using-gatewayd/observability.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Observability description: Observability is a first-class citizen of GatewayD. It generates logs, metrics and traces to make it easier to see what is going on inside. diff --git a/using-gatewayd/plugins-configuration/general-configurations.md b/using-gatewayd/plugins-configuration/general-configurations.md index bbf602a..22dd733 100644 --- a/using-gatewayd/plugins-configuration/general-configurations.md +++ b/using-gatewayd/plugins-configuration/general-configurations.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: General configurations description: General configurations for plugins diff --git a/using-gatewayd/plugins-configuration/index.md b/using-gatewayd/plugins-configuration/index.md index f5cffbb..1ec9a9a 100644 --- a/using-gatewayd/plugins-configuration/index.md +++ b/using-gatewayd/plugins-configuration/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Plugins Configuration nav_order: 3 diff --git a/using-gatewayd/plugins-configuration/plugins-configuration.md b/using-gatewayd/plugins-configuration/plugins-configuration.md index 29c39f1..45206f4 100644 --- a/using-gatewayd/plugins-configuration/plugins-configuration.md +++ b/using-gatewayd/plugins-configuration/plugins-configuration.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Plugins configuration description: GatewayD plugins configuration diff --git a/using-gatewayd/pools.md b/using-gatewayd/pools.md index 00ec4b6..f133fd3 100644 --- a/using-gatewayd/pools.md +++ b/using-gatewayd/pools.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Pools description: GatewayD has a generic internal pool object that is used to manage plugins and connections. diff --git a/using-gatewayd/protocols.md b/using-gatewayd/protocols.md index a0b0d29..12918be 100644 --- a/using-gatewayd/protocols.md +++ b/using-gatewayd/protocols.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Protocols description: GatewayD is application layer protocol-agnostic. This means that GatewayD *can* practically support any protocol in the application layer, or L7. diff --git a/using-gatewayd/proxies.md b/using-gatewayd/proxies.md index 2f0a4a3..e676546 100644 --- a/using-gatewayd/proxies.md +++ b/using-gatewayd/proxies.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Proxies description: Proxy object is used to create a binding between incoming connections from the database clients to the database servers. diff --git a/using-gatewayd/servers.md b/using-gatewayd/servers.md index 028cb42..51533a8 100644 --- a/using-gatewayd/servers.md +++ b/using-gatewayd/servers.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Servers description: Server is an object that listens on an address:port pair and accepts connections from database clients. diff --git a/using-plugins/hook-registry.md b/using-plugins/hook-registry.md index fc1ab84..c5460ca 100644 --- a/using-plugins/hook-registry.md +++ b/using-plugins/hook-registry.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Hook registry description: The hook registry is a central place where all hooks are registered and executed. It is used by the plugin registry to register and execute plugin hooks. diff --git a/using-plugins/hooks.md b/using-plugins/hooks.md index e1cd889..c6e9809 100644 --- a/using-plugins/hooks.md +++ b/using-plugins/hooks.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Hooks description: Plugins can be used to modify the connection lifecycle. Each step in the connection lifecycle is represented by one or more plugin hook(s). Plugins can register themselves to be called when a specific hook is triggered. diff --git a/using-plugins/index.md b/using-plugins/index.md index b85e36e..1a04d42 100644 --- a/using-plugins/index.md +++ b/using-plugins/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Using Plugins nav_order: 3 diff --git a/using-plugins/plugin-registry.md b/using-plugins/plugin-registry.md index 54df651..b4499a9 100644 --- a/using-plugins/plugin-registry.md +++ b/using-plugins/plugin-registry.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Plugin registry description: The plugin registry is a central place where all plugins are loaded, configured and executed, and also the main entry point for all plugins. diff --git a/using-plugins/plugin-types.md b/using-plugins/plugin-types.md index 91d22cb..8cd3322 100644 --- a/using-plugins/plugin-types.md +++ b/using-plugins/plugin-types.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Plugin types description: > diff --git a/using-plugins/plugins.md b/using-plugins/plugins.md index 29a737f..440a84b 100644 --- a/using-plugins/plugins.md +++ b/using-plugins/plugins.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Plugins description: Plugins play a very important role in GatewayD for adding support for different databases. They are the building blocks of GatewayD, and they are responsible for the majority of the functionality of GatewayD. diff --git a/using-plugins/proposals.md b/using-plugins/proposals.md index f9aafe7..6d11d41 100644 --- a/using-plugins/proposals.md +++ b/using-plugins/proposals.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-04-16 09:21:37 +last_modified_date: 2024-05-11 20:53:27 layout: default title: Proposals description: GatewayD proposals are used to propose new ideas and features for GatewayD.