Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/isa-group/sla-wizard
NodeJS module for automated and dynamic configuration of API gateways using SLAs defined with SLA4OAS.
https://github.com/isa-group/sla-wizard
apigateway envoy haproxy nginx nodejs openapi traefik
Last synced: 10 days ago
JSON representation
NodeJS module for automated and dynamic configuration of API gateways using SLAs defined with SLA4OAS.
- Host: GitHub
- URL: https://github.com/isa-group/sla-wizard
- Owner: isa-group
- License: apache-2.0
- Created: 2022-03-02T10:33:43.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2023-11-24T13:01:38.000Z (12 months ago)
- Last Synced: 2024-04-24T10:39:32.415Z (7 months ago)
- Topics: apigateway, envoy, haproxy, nginx, nodejs, openapi, traefik
- Language: JavaScript
- Homepage:
- Size: 509 KB
- Stars: 1
- Watchers: 5
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SLA Wizard
Automated configuration of API rates and limits (specified in OpenAPI and SLA4OAI) for Envoy, HAProxy, NGinx and Traefik.
## How it works
1. The user provides to SLA Wizard an OpenAPI Specification v3 and one or more SLAs agreement.
2. SLA Wizard generates a proxy configuration file which includes the rate limiting indicated in the SLA(s). Refer to section [Creating proxy configurations](https://github.com/isa-group/sla-wizard/tree/master#creating-proxy-configurations) for details on this.
3. The obtained configuration is provided to the proxy server when launching it. The proxy can be one of: Envoy, HAProxy, Nginx or Traefik.
4. The API requests will be rate-limited according to the proxy configuratin file, which matches what the API SLA(s) indicate.
## Usage
Once the tool is published in npm, it will be possible to install it using `npm install sla-wizard` but until then, to get the tool clone the repository and install dependencies:
```bash
git clone https://github.com/isa-group/sla-wizard
cd sla-wizard
npm install
```
Displayed below is the output of the `-h` option of SLA Wizard CLI:
```bash
$ node src/index.js -h
Usage: sla-wizard
Options:
-h, --help display help for command
Commands:
config [options]
runTest [options] Run test with APIPecker.
help [command] display help for command
```
### Commands
SLA Wizard includes currently two commands:
| Command | Explanation |
| --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `config` | Takes an SLA document and generates a proxy configuration file which includes rate limiting as specified on the provided SLA. |
| `runTest` | Performs validation testing of the rate limiting defined on a proxy by an SLA Wizard-generated configuration file. |
To control log levels define the environment variable `LOGGER_LEVEL` prior to the run. The possible values are `error`, `warn`, `custom`, `info` and `debug`.
### Options
The following table describes all the options that SLA Wizard includes for its commands:
| Option/Argument | Command | Required | Explanation | Default Value |
| ----------------------------------- | -------------------- | -------- |-------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `proxy` | `config` | Yes | Proxy for which the configuration should be generated. (choices: "nginx", "haproxy", "traefik", "envoy") | - |
| `-o`, `--outFile ` | `config` | Yes | Config output file. | - |
| `--sla ` | `config` & `runTest` | No | One of: 1) single SLA, 2) folder containing SLAs, 3) URL returning an array of SLA objects. Note in the case of `runTest` the URL option is not supported. | _./specs/sla.yaml_ |
| `--oas ` | `config` & `runTest` | No | Path to an OAS v3 file. | _./specs/oas.yaml_ |
| `--customTemplate ` | `config` | No | Custom proxy configuration template. | - |
| `--authLocation ` | `config` | No | Where to look for the authentication parameter. | _header_ |
| `--authName ` | `config` | No | Name of the authentication parameter, for example "token" or "apikey". | _apikey_ |
| `--specs ` | `runTest` | No | Path to a test config file. | _./specs/testSpecs.yaml_ |
## Considerations
### SLA types
SLA Wizard only works with SLAs of type `agreement`. It validates the provided SLAs with the [SLA4OAI-Specification JSON schema](https://github.com/isa-group/SLA4OAI-Specification/blob/main/schemas/1.0.0-Draft.schema.json).
If any of the provided SLAs is not valid (does not conform to schema or is not of type agreement), the execution will stop. Additionally, duplicated SLAs will be ignored.
### API server reference in OAS
The API server must be indicated on the OAS document. While it is possible to specify multiple servers in the OAS' `servers` section, SLA Wizard will consider only the first one.
For instance, in the following example only `http://server1:8080` is considered:
```yaml
openapi: 3.0.0
servers:
- url: 'http://server1:8080'
- url: 'http://server2:8080'
- url: 'http://server3:8080'
...
```
### SLA reference
Both SLA Wizard functionalities provided by the commands `config` and `runTest` require an SLA document. While it is possible to reference the SLA directly in the OAS document (`info.x-sla.$ref`), the tool will not consider it. Instead, please use the commands' `--sla` option to indicate where the SLA document(s) can be found. This option can take a path to a single file, a folder containing multiple files or even a URL (note GET to the URL must receive an array, even if there's only one SLA).
### API Authentication
APIs support different authentication methods. When authenticating with an API key, generally, it is possible to provide it in different places of the request:
1. As a header
2. As a query parameter
3. As part of the URL
All the proxies supported by SLA Wizard allow using API keys on these three locations. When creating a proxy configuration file, the option `--authLocation` of SLA Wizard's `config` command should be used to set this, it can take the values `header`, `query` and `url`. In any case, the usage of the option is not compulsory, its default value is `header`.
SLA Wizard will need to know the set of possible API keys to be used on the API, the SLA must then include the property `context.apikeys`, containing a list of API keys valid for authentication of API calls.
## Creating proxy configurations
SLA Wizard can create configuration files from scratch for four different proxy technologies: Envoy, HAProxy, Nginx and Traefik. Also, it can modify an already existing configuration file, to add the SLA logic.
For more information on how to use the tool for each of the four proxies, refer to their specific docs:
- [Envoy](https://github.com/isa-group/sla-wizard/blob/master/docs/envoy.md)
- [HAProxy](https://github.com/isa-group/sla-wizard/blob/master/docs/haproxy.md)
- [Nginx](https://github.com/isa-group/sla-wizard/blob/master/docs/nginx.md)
- [Traefik](https://github.com/isa-group/sla-wizard/blob/master/docs/traefik.md)
## Testing
Perform the following steps to test SLA Wizard. For further testing we recommend making use of [sla-gateway-benchmark](https://github.com/isa-group/sla-gateway-benchmark).
### 1. Clone repo and install dependencies
```bash
git clone https://github.com/isa-group/sla-wizard
cd sla-wizard
npm install
```
### 2. Prepare test bed
The following command creates 4 SLAs, each with 2 apikeys and then creates a config file for Nginx, with rate limiting based on those 4 SLAs:
```bash
npm run prepare_test nginx 4 2
```
See the config file created by the previous command:
```bash
less /tmp/proxy-configuration-file
```
### 3. Create configuration file for the test
It must be a YAML file with the following variables:
- `authLocation`: Indicates how the apikeys should be sent to the proxy during the testing: as a header, as a query parameter or as part of the url. Possible values are `header`, `query` and `url`, respectively.
- `extraRequests`: An integer that will multiply the number of expected 200 HTTP responses for a given endpoint and will send that amount of requests. For example, if an SLA allows a user to make 10 requests per second, if this variable is set to 3, `npm test` will send 30 requests per second for a single user.
- `minutesToRun`: Minutes to run (this applies to endpoints that have "per minute" rate limiting).
- `secondsToRun`: Seconds to run (this applies to endpoints that have "per second" rate limiting).
```bash
cat > /tmp/sla-wizard-test-config.yaml <