[DX-1591] Integrate Tyk Operator Endpoint Level Features (Draft)

tyk-docs/content/product-stack/tyk-gateway/middleware/allow-list-tyk-classic.md

@@ -11,7 +11,7 @@ When working with Tyk Classic APIs the middleware is configured in the Tyk Class
 
 If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/allow-list-tyk-oas" >}}) page.
 
-## Configuring the allow list in the Tyk Classic API Definition
+## Configuring the allow list in the Tyk Classic API Definition {#tyk-classic}
 
 To enable and configure the allow list you must add a new `white_list` object to the `extended_paths` section of your API definition.
 
@@ -33,7 +33,7 @@ The `method_actions` object should be configured as follows, with an entry creat
 - `headers` : this should be blank
 
 For example:
-```.json  {linenos=true, linenostart=1}
+```json  {linenos=true, linenostart=1}
 {
     "extended_paths": {
         "white_list": [
@@ -64,6 +64,8 @@ In this example the allow list middleware has been configured for HTTP `GET` and
 Note that the allow list has been configured to be case sensitive, so calls to `GET /Status/200` will also be rejected.
 Note also that the endpoint path has not been terminated with `$`. Requests to, for example, `GET /status/200/foobar` will be allowed as the [regular expression pattern match]({{< ref "product-stack/tyk-gateway/middleware/allow-list-middleware#endpoint-parsing" >}}) will recognize this as `GET /status/200`.
 
+Consult section [configuring the Allow List in Tyk Operator](#tyk-operator) for details on how to configure allow lists for endpoints using Tyk Operator.
+
 ## Configuring the Allow List in the API Designer
 
 You can use the API Designer in the Tyk Dashboard to configure the allow list middleware for your Tyk Classic API by following these steps.
@@ -81,3 +83,52 @@ Once you have selected the middleware for the endpoint, the only additional feat
 #### Step 3: Save the API
 
 Use the *save* or *create* buttons to save the changes and activate the allow list middleware.
+
+## Configuring the Allow List in Tyk Operator {#tyk-operator}
+
+Similar to the configuration of a [Tyk Classic API Definition](#tyk-classic) you must add a new `white_list` object to the `extended_paths` section of your API definition. Furthermore, the `use_extended_paths` configuration parameter should be set to `true`.
+
+{{< note success >}}
+**Note**
+
+Historically, Tyk followed the out-dated whitelist/blacklist naming convention. We are working to remove this terminology from the product and documentation, however this configuration object currently retains the old name.
+{{< /note >}}
+
+```yaml {linenos=true,linenostart=1}
+apiVersion: tyk.tyk.io/v1alpha1
+kind: ApiDefinition
+metadata:
+  name: httpbin-whitelist
+spec:
+  name: httpbin-whitelist
+  use_keyless: true
+  protocol: http
+  active: true
+  proxy:
+    target_url: http://httpbin.org/
+    listen_path: /httpbin
+    strip_listen_path: true
+  version_data:
+    default_version: Default
+    not_versioned: true
+    versions:
+      Default:
+        name: Default
+        use_extended_paths: true
+        paths:
+          black_list: []
+          ignored: []
+          white_list: []
+        extended_paths:
+          white_list:
+            - ignore_case: true
+              method_actions:
+                GET:
+                  action: "no_action"
+                  code: 200
+                  data: ""
+                  headers: { }
+              path: "/get"
+```
+
+In this example the allow list middleware has been configured for `HTTP GET` requests to the `/get` endpoint. Requests to any other endpoints will be rejected with `HTTP 403 Forbidden`, unless they also have the allow list middleware enabled. Note that the allow list has been configured to case insensitive, so calls to `GET /Get` will also be accepted. Note also that the endpoint path has not been terminated with `$`. Requests to, for example, `GET /get/foobar` will be allowed as the [regular expression pattern match]({{< ref "product-stack/tyk-gateway/middleware/allow-list-middleware#endpoint-parsing" >}}) will recognize this as `GET /get`.

tyk-docs/content/product-stack/tyk-gateway/middleware/block-list-tyk-classic.md

@@ -11,7 +11,9 @@ When working with Tyk Classic APIs the middleware is configured in the Tyk Class
 
 If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/block-list-tyk-oas" >}}) page.
 
-## Configuring the block list in the Tyk Classic API Definition
+If you're using Tyk Operator then check out the [configuring the block list in Tyk Operator](#tyk-operator) section below.
+
+## Configuring the block list in the Tyk Classic API Definition {#tyk-classic}
 
 To enable and configure the block list you must add a new `black_list` object to the `extended_paths` section of your API definition.
 
@@ -64,6 +66,8 @@ In this example the block list middleware has been configured for HTTP `GET` and
 Note that the block list has been configured to be case sensitive, so calls to `GET /Status/200` will not be rejected.
 Note also that the endpoint path has not been terminated with `$`. Requests to, for example, `GET /status/200/foobar` will be rejected as the [regular expression pattern match]({{< ref "product-stack/tyk-gateway/middleware/block-list-middleware#endpoint-parsing" >}}) will recognize this as `GET /status/200`.
 
+Consult section [configuring the Allow List in Tyk Operator](#tyk-operator) for details on how to configure allow lists for endpoints using Tyk Operator.
+
 ## Configuring the Block List in the API Designer
 
 You can use the API Designer in the Tyk Dashboard to configure the block list middleware for your Tyk Classic API by following these steps.
@@ -82,3 +86,54 @@ Once you have selected the middleware for the endpoint, the only additional feat
 
 Use the *save* or *create* buttons to save the changes and activate the middleware.
 
+## Configuring the block list in Tyk Operator {#tyk-operator}
+
+Similar to the configuration of a [Tyk Classic API Definition](#tyk-classic) you must add a new `black_list` object to the `extended_paths` section of your API definition. Furthermore, the `use_extended_paths` configuration parameter should be set to `true`.
+
+{{< note success >}}
+**Note**
+
+Historically, Tyk followed the out-dated whitelist/blacklist naming convention. We are working to remove this terminology from the product and documentation, however this configuration object currently retains the old name.
+{{< /note >}}
+
+```yaml {linenos=true, linenostart=1}
+apiVersion: tyk.tyk.io/v1alpha1
+kind: ApiDefinition
+metadata:
+  name: httpbin-blacklist
+spec:
+  name: httpbin-blacklist
+  use_keyless: true
+  protocol: http
+  active: true
+  proxy:
+    target_url: http://httpbin.org/
+    listen_path: /httpbin
+    strip_listen_path: true
+  version_data:
+    default_version: Default
+    not_versioned: true
+    versions:
+      Default:
+        name: Default
+        use_extended_paths: true
+        paths:
+          black_list: []
+          ignored: []
+          white_list: []
+        extended_paths:
+          black_list:
+            - ignore_case: true
+              method_actions:
+                GET:
+                  action: "no_action"
+                  code: 200
+                  data: ""
+                  headers: {}
+              path: "/get"
+```
+
+In this example the block list middleware has been configured for HTTP `GET` requests to the `/get` endpoint. Requests to these endpoints will be rejected with `HTTP 403 Forbidden`.
+Note that the block list has been configured to be case insensitive, so calls to `GET /Get` will not be rejected.
+Note also that the endpoint path has not been terminated with `$`. Requests to, for example, `GET /get/foobar` will be rejected as the [regular expression pattern match]({{< ref "product-stack/tyk-gateway/middleware/block-list-middleware#endpoint-parsing" >}}) will recognize this as `GET /get`.
+

tyk-docs/content/product-stack/tyk-gateway/middleware/circuit-breaker-tyk-classic.md

@@ -11,7 +11,9 @@ When working with Tyk Classic APIs the circuit breaker is configured in the Tyk
 
 If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/circuit-breaker-tyk-oas" >}}) page.
 
-## Configuring the Circuit Breaker in the Tyk Classic API Definition
+If you're using Tyk Operator then check out the [confguring the Circuit Breaker in Tyk Operator](#tyk-operator) section below.
+
+## Configuring the Circuit Breaker in the Tyk Classic API Definition {#tyk-classic}
 
 To configure the circuit breaker you must add a new `circuit_breakers` object to the `extended_paths` section of your API definition, with the following configuration:
 - `path`: the endpoint path
@@ -68,4 +70,51 @@ Use the *save* or *create* buttons to save the changes and activate the middlewa
 
 The Dashboard supports the separate `BreakerTripped` and `BreakerReset` events, but not the combined `BreakerTriggered` [event type]({{< ref "basic-config-and-security/report-monitor-trigger-events/event-types" >}}). You should use **API Designer > Advanced Options** to add a Webhook plugin to your endpoint for each event.
 
-{{< img src="/img/dashboard/system-management/webhook-breaker.png" alt="Webhook events" >}}
+{{< img src="/img/dashboard/system-management/webhook-breaker.png" alt="Webhook events" >}}
+
+## Confguring the Circuit Breaker in Tyk Operator {#tyk-operator}
+
+The example API Definition below configures an API to listen on path `/httpbin-timeout-breaker` and forwards requests upstream to http://httpbin.org. A hard timeout value of 2 seconds is configured for path `/delay/{delay_seconds}`. This will return a `504 Gateway Timeout` response to the client if the upstream response is not received before expiry of the timer.
+
+```yaml
+apiVersion: tyk.tyk.io/v1alpha1
+kind: ApiDefinition
+metadata:
+  name: httpbin-timeout-breaker
+spec:
+  name: httpbin-timeout-breaker
+  use_keyless: true
+  protocol: http
+  active: true
+  proxy:
+    target_url: http://httpbin.org
+    listen_path: /httpbin-timeout-breaker
+    strip_listen_path: true
+  version_data:
+    default_version: Default
+    not_versioned: true
+    versions:
+      Default:
+        name: Default
+        use_extended_paths: true
+        paths:
+          black_list: []
+          ignored: []
+          white_list: []
+        extended_paths:
+          hard_timeouts:
+            - method: GET
+              path: /delay/{delay_seconds}
+              timeout: 2
+          circuit_breakers:
+            - method: GET
+              path: /status/500
+              return_to_service_after: 10
+              samples: 4
+              # createOrUpdate failure  {"ApiDefinition": "default/httpbin-timeout-breaker", "error": "unable to create api: API Returned error: {\"Status\":\"Error\",\"Message\":\"Request body malformed\",\"Meta\":null} (code: 403)"
+              threshold_percent: "0.5" # Tyk Dashboard API doesn't support strings.
+```
+
+A circuit breaker has been configured to monitor HTTP GET requests to the /status/500 endpoint. It will configure a sampling window (samples) of 4 requests and calculate the ratio of failed requests (those returning HTTP 500 or above) within that window. If the ratio of failed requests exceeds 50% (threshold_percent = 0.5) then the breaker will be tripped. After it has tripped, the circuit breaker will remain open for 10 seconds (return_to_service_after). The circuit breaker will operate using the default half-open mode so when open, Tyk will periodically poll the upstream service to test if it has become available again.
+
+When the breaker has tripped, it will return HTTP 503 Service temporarily unavailable in response to any calls to GET /status/500.

tyk-docs/content/product-stack/tyk-gateway/middleware/do-not-track-tyk-classic.md

@@ -11,7 +11,9 @@ When working with Tyk Classic APIs the middleware is configured in the Tyk Class
 
 If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/do-not-track-tyk-oas" >}}) page.
 
-## Configuring the middleware in the Tyk Classic API Definition
+If you're using Tyk Operator, then check out the [configuring the middleware in Tyk Operator](#tyk-operator) section below.
+
+## Configuring the middleware in the Tyk Classic API Definition {#tyk-classic}
 
 You can prevent tracking for all endpoints of an API by configuring the `do_not_track` field in the root of your API definition.
 - `true`: no transaction logs will be generated for requests to the API
@@ -55,3 +57,45 @@ From the **Endpoint Designer** add an endpoint that matches the path for which y
 #### Step 2: Save the API
 
 Use the *save* or *create* buttons to save the changes and activate the middleware.
+
+## Configuring the middleware in Tyk Operator {#tyk-operator}
+
+The process for configuring the middleware in Tyk Operator is similar to that explained in [configuring the middleware in the Tyk Classic API Definition](#tyk-classic). It is possible to specify which endpoints are tracked and which are not by using the `track_endpoints` and `do_not_track_endpoints` list fields in the API Definition.
+
+The example Tyk Operator API Definition below configures an API to listen on path `/httpbin` and forwards requests upstream to http://httpbin.org. In this example the do-not-track middleware has been configured for requests to the GET /headers endpoint. Any such calls will not generate transaction records from the Gateway and so will not appear in the analytics. Conversely, requests to the GET /get endpoint will appear in the analytics.
+
+```yaml {linenos=true, linenostart=1}
+# `do_not_track_endpoints` allows you to manually disable tracking for requests to specific endpoints by method and path
+apiVersion: tyk.tyk.io/v1alpha1
+kind: ApiDefinition
+metadata:
+  name: httpbin-endpoint-tracking
+spec:
+  name: httpbin - Endpoint Track
+  use_keyless: true
+  protocol: http
+  active: true
+  do_not_track: false
+  proxy:
+    target_url: http://httpbin.org/
+    listen_path: /httpbin
+    strip_listen_path: true
+  version_data:
+    default_version: Default
+    not_versioned: true
+    versions:
+      Default:
+        name: Default
+        use_extended_paths: true
+        paths:
+          black_list: []
+          ignored: []
+          white_list: []
+        extended_paths:
+          track_endpoints:
+            - method: GET
+              path: "/get"
+          do_not_track_endpoints:
+            - method: GET
+              path: "/headers"
+```

tyk-docs/content/product-stack/tyk-gateway/middleware/endpoint-cache-tyk-classic.md

@@ -11,6 +11,8 @@ When working with Tyk Classic APIs the middleware is configured in the Tyk Class
 
 If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/endpoint-cache-tyk-oas" >}}) page.
 
+If using Tyk Operator please refer to section [configuring the middleware in the Tyk Operator](#tyk-operator).
+
 ## Configuring the middleware in the Tyk Classic API Definition
 
 When using the Tyk Classic API Definition, there are two options for endpoint caching - simple and advanced.
@@ -176,3 +178,56 @@ Body value match or [request selective]({{< ref "basic-config-and-security/reduc
 ##### Step 4: Save the API
 
 Use the *save* or *create* buttons to save the changes and activate the middleware.
+
+## Configuring the middleware in the Tyk Operator {#tyk-operator}
+
+You can use Tyk Operator to configure the endpoint caching middleware for your Tyk Classic API by following these steps.
+
+### Simple endpoint cache
+
+Configuring simple endpoint caching in Tyk Operator is similar to the process for a [Tyk Classic API Definition](#tyk-classic). A list of endpoints for which you wish to cache safe requests should be configured within the `cache` list in the `extended_paths` section.
+
+In the API-level `cache_options` object you must enable caching by setting `enable_cache` to true and configure the cache refresh period by setting a value for the `cache_timeout` in seconds. To allow selective caching per-endpoint you should also set `cache_all_safe_requests`to `false`.
+
+```yaml {linenos=true, linenostart=1}
+apiVersion: tyk.tyk.io/v1alpha1
+kind: ApiDefinition
+metadata:
+  name: httpbin-cache
+spec:
+  name: httpbin-cache
+  use_keyless: true
+  protocol: http
+  active: true
+  proxy:
+    target_url: http://httpbin.org
+    listen_path: /httpbin-cache
+    strip_listen_path: true
+  version_data:
+    default_version: Default
+    not_versioned: true
+    versions:
+      Default:
+        name: Default
+        use_extended_paths: true
+        paths:
+          black_list: []
+          ignored: []
+          white_list: []
+        extended_paths:
+          cache:
+            - /get
+            - /anything
+  cache_options:
+    cache_all_safe_requests: false
+#    cache_by_headers: []
+    cache_timeout: 10
+    cache_response_codes:
+      - 400
+    enable_cache: true
+```
+
+### Advanced endpoint cache
+
+<!-- TODO: awaiting example ->
+