[DX-1590] Tyk Operator : API Level Global Features (Draft) (#5175)

Add API level global features provided in Google spreadsheet

---------

Co-authored-by: Simon Pears <[email protected]>
Co-authored-by: caroltyk <[email protected]>

tyk-docs/content/advanced-configuration/manage-multiple-environments/with-tyk-multi-cloud.md

@@ -41,4 +41,26 @@ Scroll down to the **Segment Tags** options:
 
 Set the tag name you want to apply, and click **Add**.
 
-When you save the API, the tags will become immediately active. If any Gateways are configured to only load tagged API Definitions then this configuration will only be loaded by the relevant Gateway.
+When you save the API, the tags will become immediately active. If any Gateways are configured to only load tagged API Definitions then this configuration will only be loaded by the relevant Gateway.
+
+## Tag an API for a shard using Tyk Operator
+
+Add the tag names to the tags mapping field within an API Definition as shown in the example below:
+
+```yaml {linenos=table,hl_lines=["8-9"],linenostart=1}
+apiVersion: tyk.tyk.io/v1alpha1
+kind: ApiDefinition
+metadata:
+  name: httpbin
+spec:
+  name: httpbin
+  use_keyless: true
+  tags:
+    - edge
+  protocol: http
+  active: true
+  proxy:
+    target_url: http://httpbin.org
+    listen_path: /httpbin
+    strip_listen_path: true
+```

tyk-docs/content/basic-config-and-security/control-limit-traffic/rate-limiting.md

@@ -81,6 +81,28 @@ Check out the following video to see this being done.
 
 Using the `global_rate_limit` field in the API definition you can specify the API-level rate limit in the following format: `{"rate": 10, "per": 60}`.
 
+An equivalent example using Tyk Operator is given below:
+
+```yaml {linenos=table,hl_lines=["14-17"],linenostart=1}
+apiVersion: tyk.tyk.io/v1alpha1
+kind: ApiDefinition
+metadata:
+  name: httpbin-global-rate-limit
+spec:
+  name: httpbin-global-rate-limit
+  use_keyless: true
+  protocol: http
+  active: true
+  proxy:
+    target_url: http://httpbin.org
+    listen_path: /httpbin
+    strip_listen_path: true
+  # setting a global rate-limit for the API of 10 requests per 60 seconds
+  global_rate_limit:
+    rate: 10
+    per: 60
+```
+
 ## Configuring the rate limiter on the session object
 
 All actions on the session object must be done via the Gateway API.

tyk-docs/content/planning-for-production/ensure-high-availability/load-balancing.md

@@ -36,7 +36,7 @@ You must fill in the `target_list` section.
 
 See [Service Discovery]({{< ref "planning-for-production/ensure-high-availability/service-discovery" >}}) to see how you can integrate a service discovery system such as Consul or etcd with Tyk and enable dynamic load balancing support.
 
-### Configure load balancing and Weighting via the Dashboard
+### Configure load balancing and weighting via the Dashboard
 
 To set up load balancing via the Dashboard, from the **Core Settings** tab in the **API Designer** select **Enable round-robin load balancing** from the **API Settings** options:
 
@@ -50,6 +50,35 @@ You can now add your Load Balancing **Upstream targets** and apply weighting to
 Weighting is new from v1.10 of the Dashboard
 {{< /note >}}
 
+## Configure load balancing via Tyk Operator
+
+Load balancing is configured within Tyk Operator, using the following configuration parameters within the proxy configuration block:
+
+- `enable_load_balancing`: Set to `true` to activate load balancing
+- `target_list`: Specifies a list of upstream targets
+
+An example is shown below:
+
+```yaml {linenos=table,hl_lines=["14-17"],linenostart=1}
+apiVersion: tyk.tyk.io/v1alpha1
+kind: ApiDefinition
+metadata:
+  name: enable-load-balancing-rr
+spec:
+  name: enable-load-balancing-rr
+  use_keyless: true
+  protocol: http
+  active: true
+  proxy:
+    target_url: httpbin.org
+    listen_path: /httpbin
+    strip_listen_path: true
+    enable_load_balancing: true
+    target_list: 
+        - "httpbin.org"
+        - "httpbingo.org"
+```
+
 ## gRPC load balancing
 
 You can also perform [gRPC Load balancing]({{< ref "key-concepts/grpc-proxy#grpc-load-balancing" >}}).

tyk-docs/content/plugins/plugin-types/analytics-plugins.md

@@ -20,14 +20,61 @@ Since Tyk 4.1.0 we have incorporated analytic plugins which enables editing or r
 
 Example analytics Go plugins can be found [here](https://github.com/TykTechnologies/tyk/blob/master/test/goplugins/test_goplugin.go#L149)
 
+---
+
+An analytics plugin is configured using the `analytics_plugin` configuration block within an API Definition. This contains the following configuration parameters:
+
+- `enable`: Set to `true` to enable the plugin
+- `func_name`: The name of the function representing the plugin
+- `plugin_path`: The path to the source code file containing the function that implements the plugin
+
+{{< tabs_start >}}
+
+{{< tab_start "Tyk Gateway" >}}
+
 To enable the analytics rewriting functionality, adjust the following in API definition:
 
-```
+```json
 {
     "analytics_plugin": {
         "enable": true,
         "func_name": "<function name>",
         "plugin_path": "<path>/analytics_plugin.so"
     }
 }
-```
+```
+
+{{< tab_end >}}
+
+{{< tab_start "Tyk Operator" >}}
+
+The example API Definition resource listed below listens on path */httpbin* and forwards requests upstream to *http://httpbin.org*. A Go Analytics Plugin is enabled for function *MaskAnalyticsData*, located within the */opt/tyk-gateway/plugins/example-plugin.so* shared object file.
+
+```yaml {linenos=table,hl_lines=["15-18"],linenostart=1}
+apiVersion: tyk.tyk.io/v1alpha1
+kind: ApiDefinition
+metadata:
+  name: analytics-plugin
+spec:
+  name: httpbin-analytics-plugin
+  active: true
+  protocol: http
+  proxy:
+    listen_path: /httpbin
+    strip_listen_path: true
+    target_url: http://httpbin.org
+  use_keyless: true
+  enable_detailed_recording: true
+  analytics_plugin:
+    enable: true
+    func_name: MaskAnalyticsData # Replace it with function name of your plugin
+    plugin_path: /opt/tyk-gateway/plugins/example-plugin.so  # Replace it with path of your plugin file
+```
+
+{{< tab_end >}}
+
+{{< tabs_end >}}
+
+---
+
+</br>

tyk-docs/content/plugins/supported-languages/rich-plugins/grpc/write-grpc-plugin.md

@@ -127,6 +127,10 @@ Plugin hooks for your APIs in Tyk can be configured either by directly specifyin
 
 ### Local
 
+This section provides examples for how to configure gRPC plugin hooks, locally within an API Definition. Examples are provided for Tyk Gateway and Tyk Operator.
+
+#### Tyk Gateway
+
 For configurations directly embedded within the Tyk Gateway, plugin hooks can be defined within your API Definition. An example snippet from a Tyk Classic API Definition is provided below:
 
 ```yaml
@@ -151,6 +155,55 @@ For configurations directly embedded within the Tyk Gateway, plugin hooks can be
 Ensure the plugin driver is configured as type *grpc*. Tyk will issue a request to your gRPC server for each plugin hook that you have configured.
 {{< /note >}}
 
+#### Tyk Operator
+
+The examples below illustrate how to configure plugin hooks for an API Definition within Tyk Operator:
+
+**Pre plugin hook example**
+
+```yaml {linenos=table,hl_lines=["14-18"],linenostart=1}
+apiVersion: tyk.tyk.io/v1alpha1
+kind: ApiDefinition
+metadata:
+  name: httpbin-grpc-pre
+spec:
+  name: httpbin-grpc-pre
+  use_keyless: true
+  protocol: http
+  active: true
+  proxy:
+    target_url: http://httpbin.default.svc:8000
+    listen_path: /httpbin-grpc-pre
+    strip_listen_path: true
+  custom_middleware:
+    driver: grpc
+    pre:
+      - name: HelloFromPre
+        path: ""
+```
+
+**Post plugin hook example**
+
+```yaml {linenos=table,hl_lines=["14-18"],linenostart=1}
+apiVersion: tyk.tyk.io/v1alpha1
+kind: ApiDefinition
+metadata:
+  name: httpbin-grpc-post
+spec:
+  name: httpbin-grpc-post
+  use_keyless: true
+  protocol: http
+  active: true
+  proxy:
+    target_url: http://httpbin.default.svc:8000
+    listen_path: /httpbin-grpc-post
+    strip_listen_path: true
+  custom_middleware:
+    driver: grpc
+    post:
+      - name: HelloFromPost
+        path: ""
+```
 
 ### Remote
 

tyk-docs/content/product-stack/tyk-gateway/middleware/do-not-track-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/do-not-track-tyk-oas" >}}) page.
 
-If you're using Tyk Operator, then check out the [configuring the middleware in Tyk Operator](#tyk-operator) section below.
+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}
 
@@ -60,11 +60,34 @@ Use the *save* or *create* buttons to save the changes and activate the middlewa
 
 ## 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 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).
 
-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.
+It is possible to prevent tracking for all endpoints of an API by configuring the `do_not_track` field in the root of your API definition as follows:
 
-```yaml {linenos=true, linenostart=1}
+- `true`: no transaction logs will be generated for requests to the API
+- `false`: transaction logs will be generated for requests to the API
+
+```yaml {linenos=true, linenostart=1, hl_lines=["10"]}
+apiVersion: tyk.tyk.io/v1alpha1
+kind: ApiDefinition
+metadata:
+  name: httpbin-do-not-track
+spec:
+  name: httpbin-do-not-track 
+  use_keyless: true
+  protocol: http
+  active: true
+  do_not_track: true
+  proxy:
+    target_url: http://example.com
+    listen_path: /example
+    strip_listen_path: true
+```
+
+If you want to disable tracking only for selected endpoints, then the process is similar to that defined in [configuring the middleware in the Tyk Classic API Definition](#tyk-classic), i.e. you must add a new `do_not_track_endpoints` list to the extended_paths section of your API definition.
+This should contain a list of objects representing each endpoint `path` and `method` that should have tracking disabled:
+
+```yaml {linenos=true, linenostart=1, hl_lines=["31-33"]}
 apiVersion: tyk.tyk.io/v1alpha1
 kind: ApiDefinition
 metadata:
@@ -98,3 +121,5 @@ spec:
             - method: GET
               path: "/headers"
 ```
+
+In the example above we can see that the `do_not_track_endpoints` list is configured so that requests to `GET /headers` will have tracking disabled.

tyk-docs/content/product-stack/tyk-gateway/middleware/request-header-tyk-classic.md

@@ -145,7 +145,44 @@ The process for configuring a request header transform is similar to that define
 
 ### API Level {#tyk-operator-api}
 
-<!-- need an example here -->
+Request headers can be removed and inserted using the following fields within an `ApiDefinition`:
+
+- `global_headers`: Mapping of key values corresponding to headers to add to API requests.
+- `global_headers_remove`: List containing the name of headers to remove from API requests.
+
+The example below shows an `ApiDefinition` custom resource that adds *foo-req* and *bar-req* headers to the request before it is sent upstream. The *foo-req* header has a value of *foo-val* and the *bar-req* header has a value of *bar-val*. Furthermore, the *hello* header is removed from the request before it is sent upstream.
+
+```yaml {linenos=true, linenostart=1, hl_lines=["25-29"]}
+apiVersion: tyk.tyk.io/v1alpha1
+kind: ApiDefinition
+metadata:
+  name: httpbin-global-headers
+spec:
+  name: httpbin-global-headers
+  use_keyless: true
+  protocol: http
+  active: true
+  proxy:
+    target_url: http://httpbin.org
+    listen_path: /httpbin-global-headers
+    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: []
+        global_headers:
+          foo-req: my-foo
+          bar-req: my-bar
+        global_headers_remove:
+          - hello
+```
 
 ### Endpoint Level {#tyk-operator-endpoint}
 
@@ -217,4 +254,4 @@ spec:
                 Content-Type: "application/json"
               act_on: false
               delete_headers: []
-```
+```

tyk-docs/content/product-stack/tyk-gateway/middleware/response-header-tyk-classic.md

@@ -385,4 +385,4 @@ spec:
                 Content-Type: "application/json"
               act_on: false
               delete_headers: []
-```
+```

tyk-docs/content/product-stack/tyk-gateway/middleware/url-rewrite-tyk-classic.md

@@ -204,3 +204,5 @@ spec:
               rewrite_to: /xml
               triggers: []
 ```
+
+For further examples check out the [internal looping]({{< ref "/product-stack/tyk-operator/advanced-configurations/internal-looping" >}}) page.