From b2ae3cf0a5472f8d426c04842b9e12d6190c5d3a Mon Sep 17 00:00:00 2001 From: Jonas Kaninda Date: Sun, 10 Nov 2024 17:47:05 +0100 Subject: [PATCH] Docs: update configuration and deployment --- README.md | 5 +- docs/install/docker.md | 8 + docs/quickstart/healthcheck.md | 14 ++ docs/quickstart/loadbalanging.md | 25 ++++ docs/quickstart/monitoring.md | 21 +++ docs/quickstart/route.md | 250 ++++++++++++++----------------- 6 files changed, 184 insertions(+), 139 deletions(-) create mode 100644 docs/quickstart/monitoring.md diff --git a/README.md b/README.md index 3e29a56..36aae9c 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,8 @@ It's designed to be straightforward and efficient, offering features, like: - Custom Headers - Backend Errors interceptor - Logging +- Metrics +- Supports Load Balancing, round-robin algorithm - Support TLS - Block common exploits middleware - Patterns to detect SQL injection attempts @@ -58,11 +60,8 @@ It's designed to be straightforward and efficient, offering features, like: - Limit HTTP methods allowed for a particular route. ### Todo: - - [x] Support Load Balancing, round-robin algorithm - [ ] Load Balancing Healthcheck, disable unavailable servers - [ ] Blocklist IP address middleware - - [ ] Tracing - - [ ] Metrics - [ ] Distributed Rate Limiting for In-Memory client IP based across multiple instances using Redis ---- diff --git a/docs/install/docker.md b/docs/install/docker.md index 2823813..9939168 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -21,6 +21,14 @@ docker run --rm --name goma-gateway \ -v "${PWD}/config:/etc/goma/" \ jkaninda/goma-gateway config init --output /etc/goma/config.yml ``` +## 2. Check configuration + +```shell +docker run --rm --name goma-gateway \ + -v "${PWD}/config:/etc/goma/" \ + -p 8080:8080 \ + jkaninda/goma-gateway config config check --config /etc/goma/config.yml +``` ### 3. Start server with a custom config ```shell diff --git a/docs/quickstart/healthcheck.md b/docs/quickstart/healthcheck.md index a78792c..9bbe394 100644 --- a/docs/quickstart/healthcheck.md +++ b/docs/quickstart/healthcheck.md @@ -10,6 +10,20 @@ nav_order: 5 Goma comes with routes healthcheck, that can be enabled and disabled. +```yaml +version: 1.0 +gateway: + routes: + - path: /cart + name: example route + rewrite: / + methods: [] + healthCheck: + path: "/health/live" + interval: 30 # in Seconds + timeout: 10 # in Seconds + healthyStatuses: [200,404] # Healthy statuses +``` - Goma Gateway healthcheck: `/health/live` - Routes health check: `health/routes` diff --git a/docs/quickstart/loadbalanging.md b/docs/quickstart/loadbalanging.md index 05bd477..2a36c0a 100644 --- a/docs/quickstart/loadbalanging.md +++ b/docs/quickstart/loadbalanging.md @@ -8,5 +8,30 @@ nav_order: 4 # Load Balancing +Goma Gateway supports rund robim load blancing +```yaml +version: 1.0 +gateway: + routes: + - path: / + name: example route + hosts: + - example.com + - example.localhost + rewrite: / + methods: [] + healthCheck: + path: "/" + interval: 0 + timeout: 0 + healthyStatuses: [200,404] + ## destination: will be override by backends + destination: "" + backends: + - https://example.com + - https://example2.com + - https://example4.com + cors: +``` diff --git a/docs/quickstart/monitoring.md b/docs/quickstart/monitoring.md new file mode 100644 index 0000000..c8c770b --- /dev/null +++ b/docs/quickstart/monitoring.md @@ -0,0 +1,21 @@ +--- +title: Monitoring +layout: default +parent: Quickstart +nav_order: 6 +--- + + +# Monitoring + +Goma collects and exports metrics + +To enable metrics, you need to set `enableMetrics` to `true` and the metrics are available at `/metrics` + +```yaml +version: 1.0 +gateway: + enableMetrics: true + ... +``` + diff --git a/docs/quickstart/route.md b/docs/quickstart/route.md index 333a843..92dda32 100644 --- a/docs/quickstart/route.md +++ b/docs/quickstart/route.md @@ -10,164 +10,142 @@ nav_order: 2 The Route allows you to match on HTTP traffic and direct it to the backend. -### Example of a route +### Simple route ```yaml version: 1.0 gateway: + ... routes: - name: Example path: /store/cart rewrite: /cart destination: http://cart-service:8080 - methods: [POST, PUT, GET] - healthCheck: '' + 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 ``` -### Full example of routes and middlewares +### Route with healthcheck + +Example of route with backend health check. ```yaml - # Goma Gateway configurations +version: 1.0 gateway: - # Proxy write timeout - writeTimeout: 15 - # Proxy read timeout - readTimeout: 15 - # Proxy idle timeout - idleTimeout: 60 - ## SSL Certificate file - sslCertFile: '' #cert.pem - ## SSL Private Key file - sslKeyFile: ''#key.pem - # Proxy rate limit, it's In-Memory IP based - rateLimit: 0 - accessLog: "/dev/Stdout" - errorLog: "/dev/stderr" - ## Enable, disable routes health check - disableHealthCheckStatus: false - ## Returns backend route healthcheck errors - disableRouteHealthCheckError: false - # Disable display routes on start - disableDisplayRouteOnStart: false - # disableKeepAlive allows enabling and disabling KeepALive server - disableKeepAlive: false - # interceptErrors intercepts backend errors based on defined the status codes - interceptErrors: - - 405 - - 500 - # - 400 - # Proxy Global HTTP Cors - cors: - # Global routes cors for all routes - origins: - - http://localhost:8080 - - https://example.com - # Global routes cors headers for all routes - headers: - Access-Control-Allow-Headers: 'Origin, Authorization, Accept, Content-Type, Access-Control-Allow-Headers, X-Client-Id, X-Session-Id' - Access-Control-Allow-Credentials: 'true' - Access-Control-Max-Age: 1728000 - ##### Define routes + ... routes: - # Example of a route | 1 - - name: Public - # host Domain/host based request routing - host: "" # Host is optional - path: /public - ## Rewrite a request path - # e.g rewrite: /store to / - rewrite: / - destination: https://example.com - methods: [GET] - #DisableHeaderXForward Disable X-forwarded header. - # [X-Forwarded-Host, X-Forwarded-For, Host, Scheme ] - # It will not match the backend route, by default, it's disabled - disableHeaderXForward: false - # Internal health check - healthCheck: '' #/internal/health/ready - # Route Cors, global cors will be overridden by route - cors: - # Route Origins Cors, route will override global cors origins - origins: - - https://dev.example.com - - http://localhost:3000 - - https://example.com - # Route Cors headers, route will override global cors headers - headers: - Access-Control-Allow-Methods: 'GET' - Access-Control-Allow-Headers: 'Origin, Authorization, Accept, Content-Type, Access-Control-Allow-Headers, X-Client-Id, X-Session-Id' - Access-Control-Allow-Credentials: 'true' - Access-Control-Max-Age: 1728000 - ##### Apply middlewares to the route - ## The name must be unique - ## List of middleware name - middlewares: - - api-forbidden-paths - # Example of a route | 2 - - name: Basic auth - path: /protected - rewrite: / - destination: https://example.com + - 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 - - basic-auth + - jwt-auth +``` +### Route with backend errors interceptor -#Defines proxy middlewares -# middleware name must be unique -middlewares: - # Enable Basic auth authorization based - - name: basic-auth - # Authentication types | jwt, basic, OAuth - type: basic - paths: - - /user - - /admin - - /account - rule: - username: admin - password: admin - #Enables JWT authorization based on the result of a request and continues the request. - - name: google-auth - # Authentication types | jwt, basic, OAuth - # jwt authorization based on the result of backend's response and continue the request when the client is authorized - type: jwt - # Paths to protect - paths: - - /protected-access - - /example-of-jwt - #- /* or wildcard path - rule: - # This is an example URL - url: https://www.googleapis.com/auth/userinfo.email - # Required headers, if not present in the request, the proxy will return 403 - requiredHeaders: - - Authorization - # You can also get headers from the authentication request result and inject them into the next request header or params. - # In case you want to get headers from the authentication service and inject them into the next request headers. - # Set the request variable to the given value after the authorization request completes. - # In case you want to get headers from the authentication service and inject them into the next request headers. - # Key is authentication request response header Key. Value is the next Request header Key. - headers: - userId: Auth-UserId - userCountryId: Auth-UserCountryId - # In case you want to get headers from the Authentication service and inject them to the next request params. - #Key is authentication request response header Key. Value is the next Request parameter Key. - params: - userCountryId: countryId -# The server will return 403 - - name: api-forbidden-paths - type: access - ## prevents access paths - paths: - - /swagger-ui/* - - /v2/swagger-ui/* - - /api-docs/* - - /internal/* - - /actuator/* +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 + 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 ``` \ No newline at end of file