devbennett7/goma-gateway
1
0
Fork 0
Code Pull Requests Activity

docs: update operator deployment

Browse Source
This commit is contained in:
Jonas Kaninda
2024-12-02 07:50:42 +01:00
parent 015906b009
commit bca392ce1c
25 changed files with 281 additions and 292 deletions
Download Patch File Download Diff File Expand all files Collapse all files

125
docs/usermanual/extra-route.md Normal file
View File

@@ -0,0 +1,125 @@
---
title: Extra Routes
layout: default
parent: User Manual
nav_order: 3
---
## Extra Routes
The Extra Routes feature allows you to define additional routes by using .yml or .yaml files stored in a specified directory.
This approach helps you avoid the complexity of managing all routes in a single file.
When dealing with many routes, maintaining them in one file can quickly become unwieldy. With this feature, you can organize your routes into separate files, making them easier to manage and maintain.
Example of an extra route
Defined an extra route path in `gateway` section as shown below.
```yaml
version: 1.0
gateway:
...
## Add additional routes
extraRoutes:
# path
directory: /etc/goma/extra
watch: false
routes:
- path: /
name: example
```
## Routes Configuration
Below is an example of configuring routes for the Gateway, defining service paths, methods, backends, health checks, and other settings.
Create a file in `/etc/goma/extra` using `yaml` or `.yaml` extension.
```yaml
routes:
- path: /order
name: order-service
hosts: []
rewrite: /
methods:
- GET
- PUT
backends:
- http://order-service:8080
- http://order-service2:8080
- http://order-service3:8080
healthCheck:
path: /
interval: 30s
timeout: 10s
healthyStatuses:
- 200
- 404
cors:
origins: []
headers: {}
rateLimit: 60
disableHostFording: true
interceptErrors: [404,401]
blockCommonExploits: false
middlewares:
- auth-middleware
- path: /cart
name: cart-service
hosts: []
rewrite: /
methods:
- GET
- PUT
- POST
destination: http://cart-service:8080
healthCheck:
path: /
interval: 30s
timeout: 10s
healthyStatuses:
- 200
- 404
cors:
origins: []
headers: {}
rateLimit: 60
disableHostFording: true
interceptErrors: [404,401]
blockCommonExploits: false
## List of middleware
middlewares:
- auth-middleware
```
## Extra Middlewares
Create a file in `/etc/goma/extra` using `yaml` or `.yaml` extension.
```yaml
##### Extra Middlewares
middlewares:
# Enable Basic auth authorization based
- name: extra-basic-auth
# Authentication types | jwt, basic, OAuth
type: basic
paths:
- /user
- /admin
- /account
rule:
username: admin
password: admin
# The server will return 403
- name: extra-api-forbidden-paths
type: access
## prevents access paths
paths:
- /swagger-ui/*
- /v2/swagger-ui/*
- /api-docs/*
- /internal/*
- /actuator/*
```

93
docs/usermanual/gateway.md Normal file
View File

@@ -0,0 +1,93 @@
---
title: Gateway
layout: default
parent: User Manual
nav_order: 1
---
# Gateway
The Gateway serves as the entry point to the server. This section provides options to configure the proxy server, define routes, and specify additional routes.
These settings enable precise control over traffic flow and routing within your deployment.
## Configuration Options
- **`tlsCertFile`** (`string`): Path to the TLS certificate file.
- **`tlsKeyFile`** (`string`): Path to the TLS certificate private key file.
- **`redis`**: Redis configuration settings.
- **`writeTimeout`** (`integer`): Timeout for writing responses (in seconds).
- **`readTimeout`** (`integer`): Timeout for reading requests (in seconds).
- **`idleTimeout`** (`integer`): Timeout for idle connections (in seconds).
- **`rateLimit`** (`integer`): Global rate limiting for the proxy.
- **`blockCommonExploits`** (`boolean`): Enable or disable blocking of common exploits.
- **`accessLog`** (`string`, default: `/dev/stdout`): Path for access logs.
- **`errorLog`** (`string`, default: `/dev/stderr`): Path for error logs.
- **`logLevel`** (`string`): Log verbosity level (e.g., `info`, `debug`, `error`).
- **`disableHealthCheckStatus`** (`boolean`): Enable or disable exposing the health check route status.
- **`disableRouteHealthCheckError`** (`boolean`): Enable or disable returning health check error responses for routes.
- **`disableDisplayRouteOnStart`** (`boolean`): Enable or disable displaying routes during server startup.
- **`disableKeepAlive`** (`boolean`): Enable or disable `keepAlive` for the proxy.
- **`enableMetrics`** (`boolean`): Enable or disable server metrics collection.
- **`interceptErrors`** (`array of integers`): List of HTTP status codes to intercept for custom handling.
### CORS Configuration
Customize Cross-Origin Resource Sharing (CORS) settings for the proxy:
- **`origins`** (`array of strings`): List of allowed origins.
- **`headers`** (`map[string]string`): Custom headers to include in responses.
### Additional Routes
Define custom routes for additional flexibility:
- **`directory`** (`string`): Directory path for serving extra routes.
- **`watch`** (`boolean`): Watch the directory for changes and update routes dynamically.
### Routes
Define the main routes for the Gateway, enabling routing logic for incoming requests.
---
## Example Configuration
```yaml
version: 1.0
gateway:
sslCertFile: /etc/goma/cert.pem
sslKeyFile: /etc/goma/key.pem
writeTimeout: 15
readTimeout: 15
idleTimeout: 30
# Rate limiting
rateLimit: 0
accessLog: /dev/Stdout
errorLog: /dev/stderr
logLevel: info
disableRouteHealthCheckError: false
disableDisplayRouteOnStart: false
disableKeepAlive: false
disableHealthCheckStatus: false
blockCommonExploits: true
# Intercept backend errors
interceptErrors:
- 500
- 405
cors:
origins:
- http://localhost:8080
- https://example.com
headers:
X-Custom-Header: "Value"
Access-Control-Allow-Credentials: "true"
Access-Control-Allow-Headers: Origin, Authorization, Accept, Content-Type, Access-Control-Allow-Headers, X-Client-Id, X-Session-Id
Access-Control-Max-Age: "1728000"
## Add additional routes
extraRoutes:
# path
directory: /etc/goma/extra
watch: true
routes: []
```

72
docs/usermanual/healthcheck.md Normal file
View File

@@ -0,0 +1,72 @@
---
title: Healthcheck
layout: default
parent: User Manual
nav_order: 4
---
# Healthcheck
The proxy includes built-in health check routes, which can be easily enabled or disabled based on your requirements.
These routes allow you to monitor the health and availability of your services.
```yaml
version: 1.0
gateway:
routes:
- path: /cart
name: example route
rewrite: /
methods: []
healthCheck:
path: "/health/live"
interval: 30s
timeout: 10s
healthyStatuses: [200,404] # Healthy statuses
```
- Goma Gateway health check:
- `/readyz`
- `/healthz`
- Routes health check: `health/routes`
### Gateway healthcheck response:
```json
{
"name": "Service Gateway",
"status": "healthy",
"error": ""
}
```
### Routes healthcheck response:
```json
{
"status": "healthy",
"routes": [
{
"name": "order-service",
"status": "healthy",
"error": ""
},
{
"name": "notification-service",
"status": "healthy",
"error": ""
},
{
"name": "store-service",
"status": "healthy",
"error": ""
},
{
"name": "account-service",
"status": "healthy",
"error": ""
}
]
}
```

8
docs/usermanual/index.md Normal file
View File

@@ -0,0 +1,8 @@
---
title: User Manual
layout: default
nav_order: 3
has_children: true
---
## User Manual

192
docs/usermanual/route.md Normal file
View File

@@ -0,0 +1,192 @@
---
title: Route
layout: default
parent: User Manual
nav_order: 2
---
# Route
The Route allows you to match on HTTP traffic and direct it to the backend.
## Configuration Options
This section outlines the available configuration options for defining routes in the Gateway.
### Route Configuration
- **`path`** (`string`): The route path (e.g., `/api/v1/resource`).
- **`name`** (`string`): A unique name for the route.
- **`hosts`** (`list of strings`): A list of allowed hostnames for the route.
- **`rewrite`** (`string`): Rewrites the incoming route path to a new path.
- **`methods`** (`array of strings`): A list of allowed HTTP methods (e.g., `GET`, `POST`).
- **`destination`** (`string`): The backend endpoint for the route.
- **`backends`** (`list of strings`): A list of backend services for load balancing.
- **`insecureSkipVerify`** (`boolean`): Disables backend TLS certificate verification.
## Health Check Configuration
- **`healthCheck`**:
- **`path`** (`string`): The health check path (e.g., `/health`).
- **`interval`** (`string`, default: `30s`): The interval between health checks.
- **`timeout`** (`string`, default: `10s`): The maximum time to wait for a health check response.
- **`healthyStatuses`** (`array of integers`): A list of HTTP status codes considered healthy.
## CORS Configuration
- **`cors`**:
- **`origins`** (`array of strings`): A list of allowed origins for Cross-Origin Resource Sharing (CORS).
- **`headers`** (`array of strings`): A list of custom headers to include in responses.
## Additional Options
- **`rateLimit`** (`integer`): The maximum number of requests allowed per minute.
- **`disableHostFording`** (`boolean`): Disables proxy host forwarding for improved security.
- **`interceptErrors`** (`array of integers`): A list of backend error status codes to intercept for custom handling.
- **`blockCommonExploits`** (`boolean`): Enables or disables blocking of common exploits.
- **`middlewares`** (`array of strings`): A list of middleware names applied to the route.
---
### Simple route
```yaml
version: 1.0
gateway:
...
routes:
- name: Example
path: /store/cart
rewrite: /cart
destination: http://cart-service:8080
cors: {}
```
### Route with limited HTTP methods
The proxy will allow all HTTP methods if there's no defined method.
Example of route with limited HTTP methods allowed for a particular route.
```yaml
version: 1.0
gateway:
...
routes:
- name: Example
path: /store/cart
rewrite: /cart
destination: http://cart-service:8080
methods: [PATCH, GET]
cors: {}
middlewares:
- api-forbidden-paths
- jwt-auth
```
### Route with healthcheck
Example of route with backend health check.
```yaml
version: 1.0
gateway:
...
routes:
- name: Example
path: /store/cart
rewrite: /cart
destination: http://cart-service:8080
methods: [PATCH, GET]
healthCheck:
path: "/health/live"
interval: 0
timeout: 0
healthyStatuses: [200,404]
cors: {}
```
### Route with middleware
Example of route with backend health check.
```yaml
version: 1.0
gateway:
...
routes:
- name: Example
path: /store/cart
rewrite: /cart
destination: http://cart-service:8080
methods: []
healthCheck:
path: "/health/live"
interval: 0
timeout: 0
healthyStatuses: [200,404]
cors: {}
## Middleware
middlewares:
- api-forbidden-paths
- jwt-auth
```
### Route with backend errors interceptor
Example of route with backend errors interceptor.
```yaml
version: 1.0
gateway:
...
routes:
- name: Example
path: /store/cart
rewrite: /cart
destination: http://cart-service:8080
methods: []
healthCheck:
path: "/health/live"
interval: 0
timeout: 0
healthyStatuses: [200,404]
interceptErrors: [403,500]
blockCommonExploits: false
cors: {}
## Middleware
middlewares:
- api-forbidden-paths
- jwt-auth
```
### Route with enabled load balancing
Example of route with load balancing enabled.
```yaml
version: 1.0
gateway:
...
routes:
- name: Example
path: /store/cart
rewrite: /cart
## destination: will be override by backends
destination: ""
backends:
- https://example.com
- https://example2.com
- https://example4.com
insecureSkipVerify: true
methods: []
healthCheck:
path: "/health/live"
interval: 0
timeout: 0
healthyStatuses: [200,404]
interceptErrors: [403,500]
blockCommonExploits: false
cors: {}
## Middleware
middlewares:
- api-forbidden-paths
- jwt-auth
```

19
docs/usermanual/tls.md Normal file
View File

@@ -0,0 +1,19 @@
---
title: TLS Certificate
layout: default
parent: User Manual
nav_order: 5
---
# TLS Certificate
```yaml
version: 1.0
gateway:
tlsCertFile: cert.pem
tlsKeyFile: key.pem
```