Update docs for GPTS 0.7.2

Icikowski · Jan 12, 2022 · 397e4ec · 397e4ec
1 parent f0a25c8
commit 397e4ec
Show file tree

Hide file tree

Showing 7 changed files with 122 additions and 81 deletions.
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -1,5 +1,21 @@
 # Project changelog
 
+## GPTS 0.7.2
+
+- Updated chart definition
+    - Added startup probe
+    - Changed default values of `failureThreshold` and `periodSeconds` of all probes
+    - Added `overrides` section to override name, fullname, image repository, image name & image tag
+    - Added reference for GPTS' documentation for charts' values
+    - Added metadata to Chart.yaml
+- Added support for configurable configuration endpoint's address
+- Upgraded project's dependencies
+- Changed default handler's response structure
+    - Headers' values are now returned as single comma-separated string instead of list
+    - Added query values logging
+- Updated OpenAPI specification
+- Updated documentation
+
 ## GPTS 0.7.1
 
 - Upgraded project's dependencies

diff --git a/docs/installation/docker.md b/docs/installation/docker.md
@@ -51,7 +51,7 @@ You can use one of following commands in order to get the application up and run
 
     ???- summary "Example command execution & output"
         ```bash
-        docker run --rm -it -p 80:80 -p 8000:8000 ghcr.io/icikowski/gpts:0.1.0
+        docker run --rm -it -p 80:80 -p 8000:8000 ghcr.io/icikowski/gpts:0.6.2
         ```
         ```
         Unable to find image 'ghcr.io/icikowski/gpts:0.6.2' locally
@@ -89,6 +89,7 @@ services:
     # environment:
     #  - GPTS_SERVICE_PORT=80
     #  - GPTS_HEALTHCHECKS_PORT=8081
+    #  - GPTS_CONFIG_ENDPOINT=/config
     #  - GPTS_DEFAULT_CONFIG_ON_STARTUP=false
     #  - GPTS_LOG_LEVEL=info
     #  - GPTS_PRETTY_LOG=false

diff --git a/docs/installation/k8s.md b/docs/installation/k8s.md
@@ -28,7 +28,7 @@ After repository is successfully added, you can check for available versions of
     ???- summary "Example command output"
         ```
         NAME            CHART VERSION   APP VERSION     DESCRIPTION
-        icikowski/gpts  0.6.2           0.6.2           GPTS - General Purpose Test Service
+        icikowski/gpts  0.7.2           0.7.2           GPTS - General Purpose Test Service
         ```
 === "All versions"
     ```bash
@@ -37,11 +37,9 @@ After repository is successfully added, you can check for available versions of
     ???- summary "Example command output"
         ```
         NAME            CHART VERSION   APP VERSION     DESCRIPTION
-        icikowski/gpts  0.6.2           0.6.2           GPTS - General Purpose Test Service
-        icikowski/gpts  0.6.1           0.6.1           GPTS - General Purpose Test Service
-        icikowski/gpts  0.6.0           0.6.0           GPTS - General Purpose Test Service
-        icikowski/gpts  0.5.1           0.5.1           GPTS - General Purpose Test Service
-        icikowski/gpts  0.5.0           0.5.0           GPTS - General Purpose Test Service
+        icikowski/gpts  0.7.2           0.7.2           GPTS - General Purpose Test Service
+        icikowski/gpts  0.7.1           0.7.1           GPTS - General Purpose Test Service
+        icikowski/gpts  0.7.0           0.7.0           GPTS - General Purpose Test Service
         ```
 
 In order to fetch chart, execute one of following commands:
@@ -56,13 +54,13 @@ In order to fetch chart, execute one of following commands:
     ```
 === "Fetch particular version as .tgz"
     ```bash
-    # For example: chart version 0.6.0
-    helm fetch icikowski/gpts --version 0.6.0
+    # For example: chart version 0.7.2
+    helm fetch icikowski/gpts --version 0.7.2
     ```
 === "Fetch particular version and unpack it"
     ```bash
-    # For example: chart version 0.6.0
-    helm fetch icikowski/gpts --version 0.6.0 --untar
+    # For example: chart version 0.7.2
+    helm fetch icikowski/gpts --version 0.7.2 --untar
     ```
 
 !!! info "Downloading chart directly"
@@ -72,34 +70,31 @@ In order to fetch chart, execute one of following commands:
 
 **GPTS** settings are configured with environment variables [described here](../usage/flags.md) and can be set using following values:
 
-| Chart value | Environment variable | Default value |
-|-|-|-|
-| `gpts.servicePort` | `GPTS_SERVICE_PORT` | `8080` |
-| `gpts.healthchecksPort` | `GPTS_HEALTHCHECKS_PORT` | `8081` |
-| `gpts.defaultConfigOnStartup` | `GPTS_DEFAULT_CONFIG_ON_STARTUP` | `false` |
-| `gpts.logLevel` | `GPTS_LOG_LEVEL` | `info` |
-| `gpts.prettyLog` | `GPTS_PRETTY_LOG` | `false` |
+| Option name | Chart value | Environment variable | Default value |
+|-|-|-|-|
+| [Service port](../usage/flags.md#service-port) | `gpts.servicePort` | `GPTS_SERVICE_PORT` | `8080` |
+| [Healthchecks port](../usage/flags.md#healthchecks-port) | `gpts.healthchecksPort` | `GPTS_HEALTHCHECKS_PORT` | `8081` |
+| [Configuration endpoint](../usage/flags.md#configuration-endpoint) | `gpts.configEndpoint` | `GPTS_CONFIG_ENDPOINT` | `/config` |
+| [Default configuration on startup](../usage/flags.md#default-configuration-on-startup) | `gpts.defaultConfigOnStartup` | `GPTS_DEFAULT_CONFIG_ON_STARTUP` | `false` |
+| [Log level](../usage/flags.md#log-level) | `gpts.logLevel` | `GPTS_LOG_LEVEL` | `info` |
+| [Pretty logging](../usage/flags.md#pretty-logging) | `gpts.prettyLog` | `GPTS_PRETTY_LOG` | `false` |
 
 ???- example "Example contents of _gpts_ section in values.yaml"
-    ```yaml linenums="11"
+    ```yaml linenums="15"
     gpts:
       servicePort: 8080
       healthchecksPort: 8081
+      configEndpoint: /config
       defaultConfigOnStartup: false
       logLevel: info
-      # Available log levels: 
-      # debug, info, warn, error, fatal, panic, trace
-
-      # Enabling pretty log can make the logs more user-friendly
-      # but is NOT RECOMMENDED as it impacts the performance a lot
       prettyLog: false
     ```
 
 In order to configure chart before deployment (eg. enable ingress, change service type), you need to change values in `values.yaml` file inside chart's directory.
 
 ???- example "Example: enabling ingress for NGINX ingress class"
     === "Default values"
-        ```yaml linenums="23" hl_lines="2 3 4 7"
+        ```yaml linenums="31" hl_lines="2 3 4 7"
         ingress:
           enabled: false
           annotations: {}
@@ -115,7 +110,7 @@ In order to configure chart before deployment (eg. enable ingress, change servic
           #    - example.com
         ```
     === "Modified values"
-        ```yaml linenums="23" hl_lines="2 3 4 7"
+        ```yaml linenums="31" hl_lines="2 3 4 7"
         ingress:
           enabled: true
           annotations:
@@ -184,37 +179,18 @@ Application is up and running now! You can check it by cURLing the ingress addre
         "path": "/",
         "method": "GET",
         "headers": {
-            "Accept": [
-                "*/*"
-            ],
-            "User-Agent": [
-                "curl/7.79.1"
-            ],
-            "X-Forwarded-For": [
-                "192.168.65.3"
-            ],
-            "X-Forwarded-Host": [
-                "test0.host.net"
-            ],
-            "X-Forwarded-Port": [
-                "80"
-            ],
-            "X-Forwarded-Proto": [
-                "http"
-            ],
-            "X-Forwarded-Scheme": [
-                "http"
-            ],
-            "X-Real-Ip": [
-                "192.168.65.3"
-            ],
-            "X-Request-Id": [
-                "b08e79506d17797a0f890fea0579978e"
-            ],
-            "X-Scheme": [
-                "http"
-            ]
-        }
+            "Accept": "*/*",
+            "User-Agent": "curl/7.79.1",
+            "X-Forwarded-For": "192.168.65.3",
+            "X-Forwarded-Host": "test0.host.net",
+            "X-Forwarded-Port": "80",
+            "X-Forwarded-Proto": "http",
+            "X-Forwarded-Scheme": "http",
+            "X-Real-Ip": "192.168.65.3",
+            "X-Request-Id": "b08e79506d17797a0f890fea0579978e",
+            "X-Scheme": "http"
+        },
+        "queries": {}
     }
     ```
 
@@ -227,24 +203,15 @@ Application is up and running now! You can check it by cURLing the ingress addre
     path: /
     method: GET
     headers:
-      Accept:
-        - text/yaml
-      User-Agent:
-        - curl/7.79.1
-      X-Forwarded-For:
-        - 192.168.65.3
-      X-Forwarded-Host:
-        - test0.host.net
-      X-Forwarded-Port:
-        - "80"
-      X-Forwarded-Proto:
-        - http
-      X-Forwarded-Scheme:
-        - http
-      X-Real-Ip:
-        - 192.168.65.3
-      X-Request-Id:
-        - be588ef84375e7207cdf8c1c9acfe731
-      X-Scheme:
-        - http
+      Accept: text/yaml
+      User-Agent: curl/7.79.1
+      X-Forwarded-For: 192.168.65.3
+      X-Forwarded-Host: test0.host.net
+      X-Forwarded-Port: "80"
+      X-Forwarded-Proto: http
+      X-Forwarded-Scheme: http
+      X-Real-Ip: 192.168.65.3
+      X-Request-Id: be588ef84375e7207cdf8c1c9acfe731
+      X-Scheme: http
+    queries: {}
     ```
diff --git a/docs/usage/default.md b/docs/usage/default.md
@@ -0,0 +1,45 @@
+# **GPTS**' default response for unconfigured routes
+
+If user is attempting to send a request for unconfigured route, the application will respond with a predefined response, which consists of following fields:
+
+| Field name | Value type | Description |
+|-|-|-|
+| `host` | `string` | Hostname for which the request was sent |
+| `path` | `string` | Path for which the request was sent |
+| `method` | `string` | HTTP method of the sent request |
+| `headers` | `string` to `string` map | HTTP headers of the sent request |
+| `queries` | `string` to `string` map | Query values of the sent request |
+
+By default the response is returned in JSON format, but it is possible to retrieve it in YAML format by using `Accept: text/yaml` header.
+
+=== "Example of JSON response"
+    ```json
+    {
+      "host": "localhost:8080",
+      "path": "/some-path",
+      "method": "GET",
+      "headers": {
+        "Accept": "*/*",
+        "User-Agent": "curl/7.81.0"
+      },
+      "queries": {
+        "param1": "someValue",
+        "param2": "someOtherValue"
+      }
+    }
+    ```
+=== "Example of YAML response"
+    ```yaml
+    host: localhost:8080
+    path: /
+    method: GET
+    headers:
+      Accept: text/yaml
+      User-Agent: curl/7.81.0
+    queries:
+      param1: someValue
+      param2: someOtherValue
+    ```
+
+!!! important "Changing the default response"
+    Please note that default response is hardcoded in the application, so it cannot be changed directly. In order to override it, the route for path `/` with `allowSubpaths` option enabled must be manually created and added to the configuration.
diff --git a/docs/usage/flags.md b/docs/usage/flags.md
@@ -6,7 +6,8 @@ There are four configurable **GPTS** settings which can be controlled using list
 |-|-|-|
 | [Service port](#service-port) | `--service-port` | `GPTS_SERVICE_PORT` |
 | [Healthchecks port](#healthchecks-port) | `--healthchecks-port` | `GPTS_HEALTHCHECKS_PORT` |
-| [Default configuration on startup](#default-configuration-on-startup)  | `--default-config` | `GPTS_DEFAULT_CONFIG_ON_STARTUP` |
+| [Configuration endpoint](#configuration-endpoint) | `--config-endpoint` | `GPTS_CONFIG_ENDPOINT` |
+| [Default configuration on startup](#default-configuration-on-startup) | `--default-config` | `GPTS_DEFAULT_CONFIG_ON_STARTUP` |
 | [Log level](#log-level) | `--log-level` | `GPTS_LOG_LEVEL` |
 | [Pretty logging](#pretty-logging) | `--pretty-log` | `GPTS_PRETTY_LOG` |
 
@@ -29,6 +30,14 @@ There are four configurable **GPTS** settings which can be controlled using list
 
 **Default value**: `8081`
 
+## Configuration endpoint
+
+**Description**: Defines the address of the configuration endpoint.
+
+**Allowed values**: valid path, must start with `/`
+
+**Default value**: `/config`
+
 ## Default configuration on startup
 
 **Description**: Determines whether the default configuration (see below) should be loaded or not on application start.
@@ -76,7 +85,7 @@ There are four configurable **GPTS** settings which can be controlled using list
 
 ## Pretty logging
 
-**Description**: Enables/Disables pretty log format (may impact performance)
+**Description**: Enables/Disables pretty log format. When enabled, log is printed in a human-readable, colored format instead of JSON. This is useful for debugging purposes, but it is not recommended for production as it can impact performance.
 
 **Allowed values**: `false` or `true`
 

diff --git a/docs/usage/index.md b/docs/usage/index.md
@@ -2,6 +2,6 @@
 
 **GPTS** has relatively simple configuration, which can be controlled using [flags and environment variables](flags.md).
 
-The process of [fetching and applying new configuration](config.md) consists of sending proper `GET` and `POST` requests to always available `/config` endpoint.
+The process of [fetching and applying new configuration](config.md) consists of sending proper `GET` and `POST` requests to always available `/config` endpoint. In case of sending request for unconfigured route, the [default response](default.md) will be used.
 
 Moreover, it is possible to access [liveness & readiness probes](health.md) in order to check whether the application is working correctly.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -21,6 +21,7 @@ nav:
     - usage/index.md
     - Flags & environment variables: usage/flags.md
     - Configuring endpoints: usage/config.md
+    - Default response: usage/default.md
     - Liveness & readiness probes: usage/health.md
   - Examples:
     - examples/index.md
@@ -98,6 +99,8 @@ markdown_extensions:
   - pymdownx.mark
   - pymdownx.smartsymbols
   - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
   - pymdownx.tasklist:
       custom_checkbox: true
   - pymdownx.tabbed
@@ -109,4 +112,4 @@ plugins:
   - git-revision-date
 
 extra_css:
-  - assets/extra.css
+  - assets/extra.css