Skip to content

Commit f4c8def

Browse files
fabriziofioruccifabriziofiorucci
authored
Version 3.1.0 - API Gateway support and bugfixes (#2)
* OpenAPI integration work in progress * API Gateway updates * API Gateway support - beta release * README updated * README updated * README updated * README updated * README updated
1 parent cdc3147 commit f4c8def

16 files changed

+731
-83
lines changed

‎README.md‎

Lines changed: 22 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -45,27 +45,20 @@ sequenceDiagram
4545
4646
title GitOps with NGINX Instance Manager
4747
48-
User ->> GitLab: Push policy update
49-
NGINX Declarative API ->> GitLab: Check for updates
50-
GitLab ->> NGINX Declarative API: Latest timestamp
48+
User ->> Source of truth: Commit object updates
49+
NGINX Declarative API ->> Source of truth: Check for updates
50+
Source of truth ->> NGINX Declarative API: Latest timestamp
5151
5252
NGINX Declarative API->> NGINX Declarative API: If updates available
53-
NGINX Declarative API->> GitLab: Fetch updated policies
54-
GitLab ->> NGINX Declarative API : Updated policies
53+
NGINX Declarative API->> Source of truth: Pull updated objects
54+
Source of truth ->> NGINX Declarative API : Updated objects
5555
5656
NGINX Declarative API->> NGINX Declarative API: Build staged config
5757
NGINX Declarative API->> NGINX Instance Manager: POST staged config to instance group
5858
5959
NGINX Instance Manager ->> NGINX: Publish config to NGINX instances
6060
```
6161

62-
## Branches
63-
64-
Two branches are currently available:
65-
66-
- [Python](https://github.com/fabriziofiorucci/NGINX-Declarative-API/tree/main) - Main branch, actively developed
67-
- [Node.js](https://github.com/fabriziofiorucci/NGINX-Declarative-API/tree/nodejs) - Not actively developed, kept here for archival purposes
68-
6962
## Input formats
7063

7164
- [X] Declarative REST API
@@ -80,19 +73,20 @@ Two branches are currently available:
8073

8174
## Supported NGINX Plus features
8275

83-
| Feature | API v3 | Notes |
84-
|----------------------------| ---------------------------|-----------------------------------------------------------------------------------------------|
85-
| Upstreams | CRUD | Snippets supported: static and from source of truth |
86-
| HTTP servers | CRUD | Snippets supported (`http`, `servers`, `locations`, `upstreams`: static and from source of truth |
87-
| TCP/UDP servers | CRUD | Snippets supported (`streams`, `servers`, `upstreams`: static and from source of truth |
88-
| TLS | CRUD | Certificates and keys can be dynamically fetched from source of truth |
89-
| mTLS | CRUD | Certificates and keys can be dynamically fetched from source of truth |
90-
| Rate limiting | X | |
91-
| Active healthchecks | X | |
92-
| Cookie-based stickiness | X | |
93-
| Maps | X | |
94-
| NGINX Plus REST API access | X | |
95-
| NGINX App Protect WAF | Per-policy CRUD at `server` and `location` level with dataplane-based bundle compilation | Security policies can be dynamically fetched from source of truth |
76+
| Feature | API v3 | Notes |
77+
|----------------------------|-----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
78+
| Upstreams | CRUD | Snippets supported: static and from source of truth |
79+
| HTTP servers | CRUD | Snippets supported (`http`, `servers`, `locations`, `upstreams`: static and from source of truth |
80+
| TCP/UDP servers | CRUD | Snippets supported (`streams`, `servers`, `upstreams`: static and from source of truth |
81+
| TLS | CRUD | Certificates and keys can be dynamically fetched from source of truth |
82+
| mTLS | CRUD | Certificates and keys can be dynamically fetched from source of truth |
83+
| Rate limiting | X | |
84+
| Active healthchecks | X | |
85+
| Cookie-based stickiness | X | |
86+
| Maps | X | |
87+
| NGINX Plus REST API access | X | |
88+
| NGINX App Protect WAF | Per-policy CRUD at `server` and `location` level with dataplane-based bundle compilation | Security policies can be dynamically fetched from source of truth |
89+
| API Gateway | Swagger and OpenAPI YAML and JSON schema support | Automated configuration, HTTP methods and rate limiting enforcement |
9690

9791
## How to use
9892

@@ -131,20 +125,13 @@ $ docker build -t nginx-declarative-api:latest -f contrib/docker/Dockerfile .
131125
$ docker run --name nginx-declarative-api -d -p 5000:5000 nginx-declarative-api:latest
132126
```
133127

134-
Pre-built docker images are available on Docker Hub and can be run using:
128+
Pre-built docker images are available on Docker Hub at https://hub.docker.com/repository/docker/fiorucci/nginx-declarative-api/general and can be run using:
135129

136130
```
137-
$ docker run --name nginx-declarative-api -d -p 5000:5000 <IMAGE_NAME>
131+
$ docker run --rm --name nginx-declarative-api -d -p 5000:5000 <IMAGE_NAME>
138132
```
139133

140-
Available images are:
141-
142-
| Image name | Architecture | API version | Notes |
143-
|---------------------------------------| ------------ |-------------|------------|
144-
| fiorucci/nginx-declarative-api:3.0.0 | linux/amd64 | v3 | Current |
145-
| fiorucci/nginx-declarative-api:latest | linux/amd64 | v3 | Current |
146-
147-
Pre-built images are configured to access the redis instance on host:port `redis:6379`. This can be changed by mounting a custom `config.toml` file on the nginx-dapi container.
134+
Pre-built images are configured to access the redis instance on host:port `127.0.0.1:6379`. This can be changed by mounting a custom `config.toml` file on the `nginx-declarative-api` container.
148135

149136
## REST API documentation
150137

‎USAGE-v3.md‎

Lines changed: 98 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,97 @@ Locations `.declaration.http.servers[].locations[].uri` match modifiers in `.dec
5151
- *iregex* - case insensitive regex matching
5252
- *best* - case sensitive regex matching that halts any other location matching once a match is made
5353

54+
### API Gateway ###
55+
56+
Swagger files and OpenAPI schemas can be used to automatically configure NGINX as an API Gateway.
57+
58+
Declaration path `.declaration.http.servers[].locations[].apigateway` defines the API Gateway configuration:
59+
60+
- `openapi_schema` - the base64-encoded schema, or the schema URL. YAML and JSON are supported
61+
- `strip_uri` - removes the `.declaration.http.servers[].locations[].uri` part of the URI before forwarding requests to the upstream
62+
- `server_url` - the base URL of the upstream server
63+
- `rate_limit` - optional, used to enforce rate limiting at the API Gateway level
64+
65+
A sample API Gateway declaration to publish the `https://petstore.swagger.io` REST API and enforce:
66+
67+
- REST API endpoint URIs
68+
- HTTP Methods
69+
- Rate limiting
70+
71+
is:
72+
73+
```commandline
74+
{
75+
"output": {
76+
"type": "nms",
77+
"nms": {
78+
"url": "{{nim_host}}",
79+
"username": "{{nim_username}}",
80+
"password": "{{nim_password}}",
81+
"instancegroup": "{{nim_instancegroup}}",
82+
"synctime": 0,
83+
"modules": [
84+
"ngx_http_js_module",
85+
"ngx_stream_js_module"
86+
]
87+
}
88+
},
89+
"declaration": {
90+
"http": {
91+
"servers": [
92+
{
93+
"name": "Petstore API",
94+
"names": [
95+
"apigw.nginx.lab"
96+
],
97+
"resolver": "8.8.8.8",
98+
"listen": {
99+
"address": "80"
100+
},
101+
"log": {
102+
"access": "/var/log/nginx/apigw.nginx.lab-access_log",
103+
"error": "/var/log/nginx/apigw.nginx.lab-error_log"
104+
},
105+
"locations": [
106+
{
107+
"uri": "/petstore",
108+
"urimatch": "prefix",
109+
"apigateway": {
110+
"openapi_schema": "https://petstore.swagger.io/v2/swagger.json",
111+
"strip_uri": true,
112+
"server_url": "https://petstore.swagger.io/v2",
113+
"rate_limit": {
114+
"profile": "petstore_ratelimit",
115+
"httpcode": 429,
116+
"burst": 0,
117+
"delay": 0
118+
},
119+
"log": {
120+
"access": "/var/log/nginx/petstore-access_log",
121+
"error": "/var/log/nginx/petstore-error_log"
122+
}
123+
}
124+
}
125+
]
126+
}
127+
],
128+
"rate_limit": [
129+
{
130+
"name": "petstore_ratelimit",
131+
"key": "$binary_remote_addr",
132+
"size": "10m",
133+
"rate": "2r/s"
134+
}
135+
]
136+
}
137+
}
138+
}
139+
```
140+
141+
It can be tested using:
142+
143+
curl -iH "Host: apigw.nginx.lab" http://<NGINX_INSTANCE_IP_ADDRESS>/petstore/store/inventory
144+
54145
### Maps ###
55146

56147
Map entries `.declaration.maps[].entries.keymatch` can be:
@@ -59,7 +150,6 @@ Map entries `.declaration.maps[].entries.keymatch` can be:
59150
- *regex* - case sensitive regex matching
60151
- *iregex* - case insensitive regex matching
61152

62-
63153
### Snippets ###
64154

65155
Snippets for http, upstream, server and location can be specified as:
@@ -68,21 +158,21 @@ Snippets for http, upstream, server and location can be specified as:
68158

69159
### Methods ###
70160

71-
- `POST /v2/config/` - Publish a new declaration
72-
- `PATCH /v2/config/{config_uid}` - Update an existing declaration
161+
- `POST /v3/config/` - Publish a new declaration
162+
- `PATCH /v3/config/{config_uid}` - Update an existing declaration
73163
- Per-HTTP server CRUD
74164
- Per-HTTP upstream CRUD
75165
- Per-Stream server CRUD
76166
- Per-Stream upstream CRUD
77167
- Per-NGINX App Protect WAF policy CRUD
78-
- `GET /v2/config/{config_uid}` - Retrieve an existing declaration
79-
- `DELETE /v2/config/{config_uid}` - Delete an existing declaration
80-
81-
A sample Postman collection is available [here](/postman)
168+
- `GET /v3/config/{config_uid}` - Retrieve an existing declaration
169+
- `DELETE /v3/config/{config_uid}` - Delete an existing declaration
82170

83171
### Sample declaration ###
84172

85-
A sample declaration (to be POSTed to /v2/config) is:
173+
A sample Postman collection is available [here](/contrib/postman)
174+
175+
A declaration example (to be POSTed to /v3/config) is:
86176

87177
```
88178
{

0 commit comments

Comments
 (0)