Merge pull request #144 from jkaninda/docs

docs: update operator deployment

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

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/*
-```

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.
+The JWT middleware restricts access to routes, similar to BasicAuth, by authorizing users based on JSON Web Tokens (JWTs).
-It implements client authorization based on the result of a request using JSON Web Tokens.
 
-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
+1. **Authorization Logic**  
-```conf
+   The middleware determines access based on the HTTP response from an authentication service:
-location /private/ {
+    - **200 (OK)**: Access is granted.
-    auth_request /auth;
+    - **401 (Unauthorized)** or **403 (Forbidden)**: Access is denied with the corresponding error code.
-    ...
+    - **Other Response Codes**: Treated as errors.
-}
 
-location = /auth {
+2. **Backend Dependency**  
-    proxy_pass ...
+   The middleware relies on a backend authentication service to validate requests.
-    proxy_pass_request_body off;
+
-    proxy_set_header Content-Length "";
+3. **Nginx Inspiration**  
-    proxy_set_header X-Original-URI $request_uri;
+   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.
+1. **Injecting Headers**
-
+Add headers to the next request after a successful authorization:
-Key is authentication request response header Key. Value is the next Request header Key.
 
 ```yaml
-     headers:
+headers:
-       ## Key Authentication request header key and value is next request header key
+  # Key: Auth request header key | Value: Next request header key
-       userId: X-Auth-UserId
+  userId: X-Auth-UserId
-       userCountryId: X-Auth-UserCountryId
+  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:
-     params:
+  # Key: Auth request header key | Value: Next request parameter key
-       userId: userId
+  userId: userId
-       userCountryId: countryId
+  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: jwt-auth
-   - name: google-auth
+    type: jwt
-     # jwt authorization based on the result of backend's response and continue the request when the client is authorized
+    # Paths to protect
-     type: jwt
+    paths:
-     # Paths to protect
+      - /protected-access
-     paths:
+      - /example-of-jwt
-       - /protected-access
+      # - /* for wildcard paths
-       - /example-of-jwt
+    rule:
-       #- /* or wildcard path
+      # URL of the backend authentication service
-     rule:
+      url: https://www.example.com/auth/access
-       # This is an example URL
+      # Headers required in the incoming request
-       url: https://www.example.com/auth/access
+      requiredHeaders:
-       # Required headers, if not present in the request, the proxy will return 403
+        - Authorization
-       requiredHeaders:
+      # Headers to include in the next request
-         - Authorization
+      headers:
-       #Set the request variable to the given value after the authorization request completes.
+        userId: X-Auth-UserId
-       #
+        userCountryId: X-Auth-UserCountryId
-       # Add header to the next request from AuthRequest header, depending on your requirements
+      # Parameters to include in the next request
-       # Key is AuthRequest's response header Key, and value is Request's header Key
+      params:
-       # In case you want to get headers from the authentication service and inject them into the next request header or parameters,
+        userId: userId
-       #Set the request variable to the given value after completing the authorization request.
+        userCountryId: countryId
-       #
+
-       # 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
 ```
+
+### 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.

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

docs/middleware/rate-limit.md

@@ -51,7 +51,7 @@ kind: Middleware
 metadata:
   name: ratelimit-middleware-sample
 spec:
-    type: basic
+    type: ratelimit
     paths:
       - /*
     rule:

docs/monitoring/distrubuted-intance.md

@@ -1,8 +1,8 @@
 ---
 title: Distributed instances
 layout: default
-parent: Quickstart
+parent: Monitoring and Performance
-nav_order: 5
+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
+  tlsCertFile: cert.pem
-  sslKeyFile: key.pem
+  tlsKeyFile: key.pem
   writeTimeout: 15
   readTimeout: 15
   idleTimeout: 30

docs/monitoring/index.md

@@ -0,0 +1,8 @@
+---
+title: Monitoring and Performance
+layout: default
+nav_order: 5
+has_children: true
+---
+
+## Monitoring and Performance

docs/monitoring/loadbalanging.md

@@ -1,8 +1,8 @@
 ---
 title: Load Balancing
 layout: default
-parent: Quickstart
+parent: Monitoring and Performance
-nav_order: 4
+nav_order: 3
 ---
 
 

docs/monitoring/logging.md

@@ -1,8 +1,8 @@
 ---
 title: Logging
 layout: default
-parent: Quickstart
+parent: Monitoring and Performance
-nav_order: 6
+nav_order: 2
 ---
 
 

docs/monitoring/monitoring.md

@@ -1,8 +1,8 @@
 ---
 title: Monitoring
 layout: default
-parent: Quickstart
+parent: Monitoring and Performance
-nav_order: 6
+nav_order: 1
 ---
 
 

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
+
+```

docs/operator-manual/gateway.md

@@ -1,24 +1,10 @@
 ---
-title: Kubernetes Advanced deployment
+title: Gateway
 layout: default
-parent: Installation
+parent: Operator Manual
-nav_order: 5
+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.
 
@@ -100,81 +86,3 @@ 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
-
-```

docs/operator-manual/index.md

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

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

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/*
+```

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
+```

docs/upgrade/index.md

@@ -1,7 +1,7 @@
 ---
 title: Upgrade Notes
 layout: default
-nav_order: 5
+nav_order: 7
 has_children: true
 ---
 

docs/usermanual/extra-route.md

@@ -1,7 +1,7 @@
 ---
 title: Extra Routes
 layout: default
-parent: Quickstart
+parent: User Manual
 nav_order: 3
 ---
 

docs/usermanual/gateway.md

@@ -1,7 +1,7 @@
 ---
 title: Gateway
 layout: default
-parent: Quickstart
+parent: User Manual
 nav_order: 1
 ---
 
@@ -91,47 +91,3 @@ gateway:
     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: {}
-```

docs/usermanual/healthcheck.md

@@ -1,8 +1,8 @@
 ---
 title: Healthcheck
 layout: default
-parent: Quickstart
+parent: User Manual
-nav_order: 5
+nav_order: 4
 ---
 
 

docs/usermanual/index.md

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

docs/usermanual/route.md

@@ -1,7 +1,7 @@
 ---
 title: Route
 layout: default
-parent: Quickstart
+parent: User Manual
 nav_order: 2
 ---
 
@@ -190,36 +190,3 @@ gateway:
         - 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
-```

docs/usermanual/tls.md

@@ -1,7 +1,7 @@
 ---
 title: TLS Certificate
 layout: default
-parent: Quickstart
+parent: User Manual
 nav_order: 5
 ---
 

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.
+        # Key: Auth request header key | Value: Next request header key
-        #  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: Auth request header key | Value: Next request parameter key
-        #Key is authentication request response header Key. Value is the next Request parameter Key.
         params:
           userCountryId: countryId
       # The server will return 403

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.
+    # Key: Auth request header key | Value: Next request header key
-    #  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: Auth request header key | Value: Next request parameter key
-    #Key is authentication request response header Key. Value is the next Request parameter Key.
     params:
       userCountryId: countryId
 # The server will return 403