diff --git a/docs/install/kubernetes.md b/docs/install/kubernetes.md index b6cd8be..8459564 100644 --- a/docs/install/kubernetes.md +++ b/docs/install/kubernetes.md @@ -7,6 +7,11 @@ nav_order: 4 # Kubernetes Installation +Goma Gateway has two types of installations: simple and advanced. + +## 1. Simple Deployment + +Simple deployment is to deploy Goma Gateway using Kubernetes deployment resources. Details about how to use Goma in Kubernetes can be found on the hub.docker.com repo hosting the image: Goma. We also have some cool examples with [Kubernetes deployment template](https://github.com/jkaninda/goma-gateway/tree/main/examples) with built-in orchestration and scalability. @@ -84,3 +89,8 @@ spec: name: goma-config ``` +## 2. Advanced Deployment + +Advanced deployment is to deploy Goma Gateway using its Kubernetes Operator. + +See Operator Manuel diff --git a/docs/middleware/access.md b/docs/middleware/access.md index e9cb211..b072f7a 100644 --- a/docs/middleware/access.md +++ b/docs/middleware/access.md @@ -38,20 +38,3 @@ Example of access middleware middlewares: - api-forbidden-paths ``` -## Advanced Kubernetes deployment - -```yaml -apiVersion: gomaproj.github.io/v1beta1 -kind: Middleware -metadata: - name: access-middleware-sample -spec: - type: access - ## prevents access paths - paths: - - /swagger-ui/* - - /v2/swagger-ui/* - - /api-docs/* - - /internal/* - - /actuator/* -``` \ No newline at end of file diff --git a/docs/middleware/jwt.md b/docs/middleware/jwt.md index 76af83f..7628510 100644 --- a/docs/middleware/jwt.md +++ b/docs/middleware/jwt.md @@ -1,93 +1,103 @@ --- -title: JWT auth +title: JWT Middleware layout: default parent: Middleware nav_order: 4 --- -### JWT middleware +### JWT Middleware -As BasicAuth, JWT middleware grants also access to route to authorized users only. -It implements client authorization based on the result of a request using JSON Web Tokens. +The JWT middleware restricts access to routes, similar to BasicAuth, by authorizing users based on JSON Web Tokens (JWTs). -If the request returns a 200 response code, access is allowed. -If it returns 401 or 403, the access is denied with the corresponding error code. Any other response code returned by the request is considered an error. +--- -It depends on an authentication service on the backend. +#### How It Works -It works as `ngx_http_auth_request_module` on Nginx -```conf -location /private/ { - auth_request /auth; - ... -} +1. **Authorization Logic** + The middleware determines access based on the HTTP response from an authentication service: + - **200 (OK)**: Access is granted. + - **401 (Unauthorized)** or **403 (Forbidden)**: Access is denied with the corresponding error code. + - **Other Response Codes**: Treated as errors. -location = /auth { - proxy_pass ... - proxy_pass_request_body off; - proxy_set_header Content-Length ""; - proxy_set_header X-Original-URI $request_uri; -} +2. **Backend Dependency** + The middleware relies on a backend authentication service to validate requests. + +3. **Nginx Inspiration** + Its behavior is comparable to `ngx_http_auth_request_module` in Nginx. + +Here's an example Nginx configuration: + +``` + location /private/ { + auth_request /auth; + ... + } + + location = /auth { + proxy_pass ...; + proxy_pass_request_body off; + proxy_set_header Content-Length ""; + proxy_set_header X-Original-URI $request_uri; + } ``` -You can also get headers from the authentication request result and inject them into the next request header or params. +### Header and Parameter Injection -In case you want to get headers from the authentication service and inject them into the next request headers. +The middleware supports extracting headers from the authentication response and injecting them into the next request’s headers or parameters. -Set the request variable to the given value after the authorization request completes. - -Key is authentication request response header Key. Value is the next Request header Key. +1. **Injecting Headers** +Add headers to the next request after a successful authorization: ```yaml - headers: - ## Key Authentication request header key and value is next request header key - userId: X-Auth-UserId - userCountryId: X-Auth-UserCountryId +headers: + # Key: Auth request header key | Value: Next request header key + userId: X-Auth-UserId + userCountryId: X-Auth-UserCountryId ``` -The second example, is in case you want to get headers from the authentication request and inject them into the next request parameters. -Key is authentication request response header Key. Value is the next Request parameter Key. -See the example below. +2. **Injecting Parameters** + +Add parameters to the next request from the authentication response headers: ```yaml - # Key Authentication request header key and value is next request parameter key - params: - userId: userId - userCountryId: countryId +params: + # Key: Auth request header key | Value: Next request parameter key + userId: userId + userCountryId: countryId ``` -Example of JWT middleware + +### Example Configuration + +Below is a complete example of JWT middleware configuration: + ```yaml middlewares: - #Enables JWT authorization based on the result of a request and continues the request. - - name: google-auth - # 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.example.com/auth/access - # Required headers, if not present in the request, the proxy will return 403 - requiredHeaders: - - Authorization - #Set the request variable to the given value after the authorization request completes. - # - # Add header to the next request from AuthRequest header, depending on your requirements - # Key is AuthRequest's response header Key, and value is Request's header Key - # In case you want to get headers from the authentication service and inject them into the next request header or parameters, - #Set the request variable to the given value after completing the authorization request. - # - # Add header to the next request from AuthRequest header, depending on your requirements - # Key is AuthRequest's response header Key, and value is next request header Key - # In case you want to get headers from the authentication service and inject them into the next request headers. - headers: - userId: X-Auth-UserId - userCountryId: X-Auth-UserCountryId - # In case you want to get headers from the Authentication service and inject them to the next request params. - params: - userCountryId: countryId -``` \ No newline at end of file + - name: jwt-auth + type: jwt + # Paths to protect + paths: + - /protected-access + - /example-of-jwt + # - /* for wildcard paths + rule: + # URL of the backend authentication service + url: https://www.example.com/auth/access + # Headers required in the incoming request + requiredHeaders: + - Authorization + # Headers to include in the next request + headers: + userId: X-Auth-UserId + userCountryId: X-Auth-UserCountryId + # Parameters to include in the next request + params: + userId: userId + userCountryId: countryId + +``` + +### Notes + +- Use this middleware to secure endpoints by delegating authorization to a backend service. +- Properly configure the rule section to match your authentication service requirements. \ No newline at end of file diff --git a/docs/middleware/oauth.md b/docs/middleware/oauth.md index cbcfa40..6208c16 100644 --- a/docs/middleware/oauth.md +++ b/docs/middleware/oauth.md @@ -83,7 +83,7 @@ kind: Middleware metadata: name: oauth-middleware-sample spec: - type: basic + type: oauth paths: - /protected - /example-of-oauth diff --git a/docs/middleware/rate-limit.md b/docs/middleware/rate-limit.md index 5f8b492..35eec6a 100644 --- a/docs/middleware/rate-limit.md +++ b/docs/middleware/rate-limit.md @@ -51,7 +51,7 @@ kind: Middleware metadata: name: ratelimit-middleware-sample spec: - type: basic + type: ratelimit paths: - /* rule: diff --git a/docs/quickstart/distrubuted-intance.md b/docs/monitoring/distrubuted-intance.md similarity index 88% rename from docs/quickstart/distrubuted-intance.md rename to docs/monitoring/distrubuted-intance.md index 2c0657f..db33eeb 100644 --- a/docs/quickstart/distrubuted-intance.md +++ b/docs/monitoring/distrubuted-intance.md @@ -1,8 +1,8 @@ --- title: Distributed instances layout: default -parent: Quickstart -nav_order: 5 +parent: Monitoring and Performance +nav_order: 4 --- @@ -15,8 +15,8 @@ By leveraging Redis, the Gateway ensures high-performance request throttling and ```yaml version: "1.0" gateway: - sslCertFile: cert.pem - sslKeyFile: key.pem + tlsCertFile: cert.pem + tlsKeyFile: key.pem writeTimeout: 15 readTimeout: 15 idleTimeout: 30 diff --git a/docs/monitoring/index.md b/docs/monitoring/index.md new file mode 100644 index 0000000..0fe2581 --- /dev/null +++ b/docs/monitoring/index.md @@ -0,0 +1,8 @@ +--- +title: Monitoring and Performance +layout: default +nav_order: 5 +has_children: true +--- + +## Monitoring and Performance diff --git a/docs/quickstart/loadbalanging.md b/docs/monitoring/loadbalanging.md similarity index 94% rename from docs/quickstart/loadbalanging.md rename to docs/monitoring/loadbalanging.md index 3c55a45..ab7558c 100644 --- a/docs/quickstart/loadbalanging.md +++ b/docs/monitoring/loadbalanging.md @@ -1,8 +1,8 @@ --- title: Load Balancing layout: default -parent: Quickstart -nav_order: 4 +parent: Monitoring and Performance +nav_order: 3 --- diff --git a/docs/quickstart/logging.md b/docs/monitoring/logging.md similarity index 93% rename from docs/quickstart/logging.md rename to docs/monitoring/logging.md index 231a3b8..469b083 100644 --- a/docs/quickstart/logging.md +++ b/docs/monitoring/logging.md @@ -1,8 +1,8 @@ --- title: Logging layout: default -parent: Quickstart -nav_order: 6 +parent: Monitoring and Performance +nav_order: 2 --- diff --git a/docs/quickstart/monitoring.md b/docs/monitoring/monitoring.md similarity index 84% rename from docs/quickstart/monitoring.md rename to docs/monitoring/monitoring.md index c8c770b..de8c808 100644 --- a/docs/quickstart/monitoring.md +++ b/docs/monitoring/monitoring.md @@ -1,8 +1,8 @@ --- title: Monitoring layout: default -parent: Quickstart -nav_order: 6 +parent: Monitoring and Performance +nav_order: 1 --- diff --git a/docs/operator-manual/Uninstallation.md b/docs/operator-manual/Uninstallation.md new file mode 100644 index 0000000..e357b2b --- /dev/null +++ b/docs/operator-manual/Uninstallation.md @@ -0,0 +1,25 @@ +--- +title: Uninstall +layout: default +parent: Operator Manual +nav_order: 5 +--- + +# Uninstall + +```sh +kubectl delete -f https://raw.githubusercontent.com/jkaninda/goma-operator/main/dist/install.yaml +``` + +### Force Gateway deletion + +```shell +kubectl patch gateways.gomaproj.github.io (gatewayName) -p '{"metadata":{"finalizers":[]}}' --type=merge +``` + +### Force gateway crd deletion + +```shell +kubectl patch crd gateways.gomaproj.github.io -p '{"metadata":{"finalizers":[]}}' --type=merge + +``` \ No newline at end of file diff --git a/docs/install/kuberntes-advanced.md b/docs/operator-manual/gateway.md similarity index 54% rename from docs/install/kuberntes-advanced.md rename to docs/operator-manual/gateway.md index 89f5dcb..a0f3978 100644 --- a/docs/install/kuberntes-advanced.md +++ b/docs/operator-manual/gateway.md @@ -1,24 +1,10 @@ --- -title: Kubernetes Advanced deployment +title: Gateway layout: default -parent: Installation -nav_order: 5 +parent: Operator Manual +nav_order: 2 --- -# Kubernetes Advanced deployment using CRDs and an Operator - -**Install the CRDs and Operator into the cluster:** - -```sh -kubectl apply -f https://raw.githubusercontent.com/jkaninda/goma-operator/main/dist/install.yaml -``` - -## Resources - -- Gateway -- Route -- Middleware - ## Gateway The **Gateway** serves as the entry point to the server, handling and routing incoming traffic. @@ -99,82 +85,4 @@ Or ```shell kubectl delete gateways.gomaproj.github.io (gatewayName) -``` - -## Middleware - -A simple example of middleware - -```yaml -apiVersion: gomaproj.github.io/v1beta1 -kind: Middleware -metadata: - name: basic-middleware-sample -spec: - type: basic - paths: - - /admin/* - rule: - username: admin - password: admin -``` - -## Route - -A simple example of route - -```yaml -apiVersion: gomaproj.github.io/v1beta1 -kind: Route -metadata: - labels: {} - name: route-sample -spec: - gateway: gateway-sample - path: / - hosts: [] - rewrite: / - methods: - - GET - - POST - - PUT - destination: https://example.com - backends: [] - insecureSkipVerify: false - healthCheck: - path: / - interval: 10s - timeout: 10s - healthyStatuses: - - 200 - - 404 - cors: - origins: [] - headers: {} - rateLimit: 15 - disableHostFording: true - interceptErrors: [] - blockCommonExploits: false - ## Middleware names - middlewares: - - basic-middleware-sample -``` - -## Uninstall - -```sh -kubectl delete -f https://raw.githubusercontent.com/jkaninda/goma-operator/main/dist/install.yaml -``` - -### Force Gateway deletion - -```shell -kubectl patch gateways.gomaproj.github.io (gatewayName) -p '{"metadata":{"finalizers":[]}}' --type=merge -``` - -### Force gateway crd deletion - -```shell -kubectl patch crd gateways.gomaproj.github.io -p '{"metadata":{"finalizers":[]}}' --type=merge - ``` \ No newline at end of file diff --git a/docs/operator-manual/index.md b/docs/operator-manual/index.md new file mode 100644 index 0000000..a07d95b --- /dev/null +++ b/docs/operator-manual/index.md @@ -0,0 +1,8 @@ +--- +title: Operator Manual +layout: default +nav_order: 6 +has_children: true +--- + +## Operator Manual \ No newline at end of file diff --git a/docs/operator-manual/installation.md b/docs/operator-manual/installation.md new file mode 100644 index 0000000..36af40d --- /dev/null +++ b/docs/operator-manual/installation.md @@ -0,0 +1,28 @@ +--- +title: Installation +layout: default +parent: Operator Manual +nav_order: 1 +--- + +# Installation + +## Kubernetes Advanced deployment using CRDs and an Operator + +**Install the CRDs and Operator into the cluster:** + +```sh +kubectl apply -f https://raw.githubusercontent.com/jkaninda/goma-operator/main/dist/install.yaml +``` + +### Resources + +- Gateway +- Middleware +- Route + +### Resources order + +- Gateway +- Middleware +- Route \ No newline at end of file diff --git a/docs/operator-manual/middlware.md b/docs/operator-manual/middlware.md new file mode 100644 index 0000000..a9e8a51 --- /dev/null +++ b/docs/operator-manual/middlware.md @@ -0,0 +1,49 @@ +--- +title: Middleware +layout: default +parent: Operator Manual +nav_order: 3 +--- + +# Middleware + +### Basic-auth + +A simple example of middleware + +```yaml +apiVersion: gomaproj.github.io/v1beta1 +kind: Middleware +metadata: + name: basic-middleware-sample +spec: + type: basic + paths: + - /admin/* + rule: + username: admin + password: admin +``` +### JWT-auth + +```yaml + +``` + +### Access + +```yaml +apiVersion: gomaproj.github.io/v1beta1 +kind: Middleware +metadata: + name: access-middleware-sample +spec: + type: access + ## prevents access paths + paths: + - /swagger-ui/* + - /v2/swagger-ui/* + - /api-docs/* + - /internal/* + - /actuator/* +``` diff --git a/docs/operator-manual/route.md b/docs/operator-manual/route.md new file mode 100644 index 0000000..5a7ae04 --- /dev/null +++ b/docs/operator-manual/route.md @@ -0,0 +1,47 @@ +--- +title: Route +layout: default +parent: Operator Manual +nav_order: 4 +--- + +# Route + +A simple example of route + +```yaml +apiVersion: gomaproj.github.io/v1beta1 +kind: Route +metadata: + labels: {} + name: route-sample +spec: + gateway: gateway-sample + path: / + hosts: [] + rewrite: / + methods: + - GET + - POST + - PUT + destination: https://example.com + backends: [] + insecureSkipVerify: false + healthCheck: + path: / + interval: 10s + timeout: 10s + healthyStatuses: + - 200 + - 404 + cors: + origins: [] + headers: {} + rateLimit: 15 + disableHostFording: true + interceptErrors: [] + blockCommonExploits: false + ## Middleware names + middlewares: + - basic-middleware-sample +``` \ No newline at end of file diff --git a/docs/upgrade/index.md b/docs/upgrade/index.md index 34ecb13..267e449 100644 --- a/docs/upgrade/index.md +++ b/docs/upgrade/index.md @@ -1,7 +1,7 @@ --- title: Upgrade Notes layout: default -nav_order: 5 +nav_order: 7 has_children: true --- diff --git a/docs/quickstart/extra-route.md b/docs/usermanual/extra-route.md similarity index 99% rename from docs/quickstart/extra-route.md rename to docs/usermanual/extra-route.md index f6826b1..438573a 100644 --- a/docs/quickstart/extra-route.md +++ b/docs/usermanual/extra-route.md @@ -1,7 +1,7 @@ --- title: Extra Routes layout: default -parent: Quickstart +parent: User Manual nav_order: 3 --- diff --git a/docs/quickstart/gateway.md b/docs/usermanual/gateway.md similarity index 76% rename from docs/quickstart/gateway.md rename to docs/usermanual/gateway.md index 612c804..42b62dd 100644 --- a/docs/quickstart/gateway.md +++ b/docs/usermanual/gateway.md @@ -1,7 +1,7 @@ --- title: Gateway layout: default -parent: Quickstart +parent: User Manual nav_order: 1 --- @@ -90,48 +90,4 @@ gateway: directory: /etc/goma/extra watch: true routes: [] -``` - -## Advanced Kubernetes deployment - -```yaml -apiVersion: gomaproj.github.io/v1beta1 -kind: Gateway -metadata: - labels: {} - name: gateway-sample -spec: - # The version of Goma Gateway - # See: https://github.com/jkaninda/goma-gateway/releases - gatewayVersion: latest - server: - # Kubernetes tls secret name - tlsSecretName: '' #Optional, tls-secret - #Redis configs for distributed rate limiting across multiple instances - redis: - addr: '' #Optional, redis:6379 - password: '' #Optional, password - writeTimeout: 10 - readTimeout: 15 - idleTimeout: 35 - logLevel: info - disableHealthCheckStatus: true - disableKeepAlive: false - enableMetrics: true - # Replicas count - replicaCount: 1 - resources: - limits: - cpu: 250m - memory: 512Mi - requests: - cpu: 100m - memory: 128Mi - autoScaling: - enabled: true - minReplicas: 2 - maxReplicas: 5 - targetCPUUtilizationPercentage: 80 - targetMemoryUtilizationPercentage: 80 - affinity: {} ``` \ No newline at end of file diff --git a/docs/quickstart/healthcheck.md b/docs/usermanual/healthcheck.md similarity index 97% rename from docs/quickstart/healthcheck.md rename to docs/usermanual/healthcheck.md index bb97e2a..cedfb7f 100644 --- a/docs/quickstart/healthcheck.md +++ b/docs/usermanual/healthcheck.md @@ -1,8 +1,8 @@ --- title: Healthcheck layout: default -parent: Quickstart -nav_order: 5 +parent: User Manual +nav_order: 4 --- diff --git a/docs/quickstart/index.md b/docs/usermanual/index.md similarity index 63% rename from docs/quickstart/index.md rename to docs/usermanual/index.md index 9e420b5..2a553ff 100644 --- a/docs/quickstart/index.md +++ b/docs/usermanual/index.md @@ -1,8 +1,8 @@ --- -title: Quickstart +title: User Manual layout: default nav_order: 3 has_children: true --- -## Quickstart \ No newline at end of file +## User Manual \ No newline at end of file diff --git a/docs/quickstart/route.md b/docs/usermanual/route.md similarity index 89% rename from docs/quickstart/route.md rename to docs/usermanual/route.md index 0336a4b..7c120c3 100644 --- a/docs/quickstart/route.md +++ b/docs/usermanual/route.md @@ -1,7 +1,7 @@ --- title: Route layout: default -parent: Quickstart +parent: User Manual nav_order: 2 --- @@ -189,37 +189,4 @@ gateway: middlewares: - api-forbidden-paths - jwt-auth -``` -## Advanced Kubernetes deployment - -```yaml -apiVersion: gomaproj.github.io/v1beta1 -kind: Route -metadata: - labels: {} - name: route-sample -spec: - gateway: gateway-sample - path: / - hosts: [] - rewrite: /g - methods: [GET] - destination: https://example.com - backends: [] - insecureSkipVerify: true - healthCheck: - path: / - interval: 10s - timeout: 10s - healthyStatuses: - - 200 - - 404 - cors: - origins: [] - headers: {} - disableHostFording: true - blockCommonExploits: true - middlewares: - - basic-middleware-sample - - ratelimit ``` \ No newline at end of file diff --git a/docs/quickstart/tls.md b/docs/usermanual/tls.md similarity index 89% rename from docs/quickstart/tls.md rename to docs/usermanual/tls.md index c1c3150..b99fc40 100644 --- a/docs/quickstart/tls.md +++ b/docs/usermanual/tls.md @@ -1,7 +1,7 @@ --- title: TLS Certificate layout: default -parent: Quickstart +parent: User Manual nav_order: 5 --- diff --git a/examples/configMap.yaml b/examples/configMap.yaml index 8f3aee5..976a6bd 100644 --- a/examples/configMap.yaml +++ b/examples/configMap.yaml @@ -135,16 +135,11 @@ data: # 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. + # Key: Auth request header key | Value: 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. + # Key: Auth request header key | Value: Next request parameter key params: userCountryId: countryId # The server will return 403 diff --git a/examples/goma.yml b/examples/goma.yml index e9e2821..e2b41e6 100644 --- a/examples/goma.yml +++ b/examples/goma.yml @@ -136,16 +136,11 @@ middlewares: # 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. + # Key: Auth request header key | Value: 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. + # Key: Auth request header key | Value: Next request parameter key params: userCountryId: countryId # The server will return 403