diff --git a/tyk-docs/content/advanced-configuration/manage-multiple-environments/with-tyk-multi-cloud.md b/tyk-docs/content/advanced-configuration/manage-multiple-environments/with-tyk-multi-cloud.md index 00dc5306e6..f2a5eb2df1 100755 --- a/tyk-docs/content/advanced-configuration/manage-multiple-environments/with-tyk-multi-cloud.md +++ b/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. \ No newline at end of file +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 +``` \ No newline at end of file diff --git a/tyk-docs/content/basic-config-and-security/control-limit-traffic/rate-limiting.md b/tyk-docs/content/basic-config-and-security/control-limit-traffic/rate-limiting.md index 322ff71b4f..4334d7cfff 100755 --- a/tyk-docs/content/basic-config-and-security/control-limit-traffic/rate-limiting.md +++ b/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. diff --git a/tyk-docs/content/basic-config-and-security/security/authentication-authorization/basic-auth.md b/tyk-docs/content/basic-config-and-security/security/authentication-authorization/basic-auth.md index e49081beb2..2a3738060a 100755 --- a/tyk-docs/content/basic-config-and-security/security/authentication-authorization/basic-auth.md +++ b/tyk-docs/content/basic-config-and-security/security/authentication-authorization/basic-auth.md @@ -71,6 +71,10 @@ To enable Basic Authentication, the API Definition file needs to be set up to al As you can see in the above example, enabling Basic Authentication is as simple as setting a flag for the feature in your API Definition object. Since Basic Authentication is a standard, Tyk will always look for the credentials as part of the `Authorization` header. +### Enable basic authentication using Tyk Operator + +Please consult the Tyk Operator supporting documentation for an example of how to [enable basic authentication]({{< ref "product-stack/tyk-operator/advanced-configurations/client-authentication#basic-authentication" >}}) with Tyk Operator. + ## Create a Basic Authentication user When using Basic Authentication, the API key used to access the API is not generated by the Tyk system, instead you need to create at least one Basic Authentication user in the Tyk Gateway. Tyk will compare the Basic Authentication key provided in the request against the list of users you have created. diff --git a/tyk-docs/content/basic-config-and-security/security/authentication-authorization/bearer-tokens.md b/tyk-docs/content/basic-config-and-security/security/authentication-authorization/bearer-tokens.md index 12ed61ce88..9185a5372a 100755 --- a/tyk-docs/content/basic-config-and-security/security/authentication-authorization/bearer-tokens.md +++ b/tyk-docs/content/basic-config-and-security/security/authentication-authorization/bearer-tokens.md @@ -99,3 +99,7 @@ If you are migrating from platforms like Mashery, which use request signing, you ### Custom tokens It is possible to provide Tyk with your own custom tokens, this can be achieved using the Tyk Gateway REST API. This is very useful if you have your own identity provider and don't want Tyk to create and manage tokens for you, and instead just mirror those tokens within Tyk to off-load access control, quotas and rate limiting from your own application. + +## Enabling bearer tokens with Tyk Operator + +Please consult the Tyk Operator supporting documentation for an example of how to [enable a bearer tokens]({{< ref "product-stack/tyk-operator/advanced-configurations/client-authentication#auth-token-bearer-token" >}}) with Tyk Operator. \ No newline at end of file diff --git a/tyk-docs/content/basic-config-and-security/security/authentication-authorization/json-web-tokens.md b/tyk-docs/content/basic-config-and-security/security/authentication-authorization/json-web-tokens.md index 4698ccd69d..af56986920 100755 --- a/tyk-docs/content/basic-config-and-security/security/authentication-authorization/json-web-tokens.md +++ b/tyk-docs/content/basic-config-and-security/security/authentication-authorization/json-web-tokens.md @@ -237,3 +237,7 @@ Several scopes in JWT claim will lead to have several policies applied to a key. ### JWT Diagram in Tyk API Gateway {{< img src="/img/diagrams/diagram_docs_JSON-web-tokens@2x.png" alt="JSON Web Tokens Flow" >}} + +### JWT authentication with Tyk Operator + +Please consult the Tyk Operator supporting documentation for an example of how to [configure JWT authentication]({{< ref "product-stack/tyk-operator/advanced-configurations/client-authentication#jwt" >}}) with Tyk Operator. diff --git a/tyk-docs/content/basic-config-and-security/security/authentication-authorization/multiple-auth.md b/tyk-docs/content/basic-config-and-security/security/authentication-authorization/multiple-auth.md index db9f3d834c..9adee15ef0 100755 --- a/tyk-docs/content/basic-config-and-security/security/authentication-authorization/multiple-auth.md +++ b/tyk-docs/content/basic-config-and-security/security/authentication-authorization/multiple-auth.md @@ -53,4 +53,8 @@ To enable this mode you must set the `base_identity_provided_by` field in your A The provider set here will then be the one that provides the session object that determines rate limits, ACL rules and quotas. -Tyk will chain the auth mechanisms as they appear in the code and will default to auth token if none are specified. You can explicitly set auth token support by setting `use_standard_auth` to true. \ No newline at end of file +Tyk will chain the auth mechanisms as they appear in the code and will default to auth token if none are specified. You can explicitly set auth token support by setting `use_standard_auth` to true. + +## Enable Multi (Chained) Authentication with Tyk Operator + +Please consult the Tyk Operator supporting documentation for an example of how to enable [multi chained authentication]({{< ref "product-stack/tyk-operator/advanced-configurations/client-authentication#multiple-chained-auth" >}}) with Tyk Operator. \ No newline at end of file diff --git a/tyk-docs/content/basic-config-and-security/security/authentication-authorization/open-keyless.md b/tyk-docs/content/basic-config-and-security/security/authentication-authorization/open-keyless.md index 4372bf6cab..9722239494 100755 --- a/tyk-docs/content/basic-config-and-security/security/authentication-authorization/open-keyless.md +++ b/tyk-docs/content/basic-config-and-security/security/authentication-authorization/open-keyless.md @@ -11,10 +11,14 @@ weight: 5 Tyk keyless access represents completely open access for your API and causes Tyk to bypass any session-based middleware (middleware that requires access to token-related metadata). Most middleware will work with keyless access (header transformation, mocks, virtual endpoints, etc.). +## Use Case + Open access is very useful for situations where analytics is the key reason for tracking usage, using the Tyk node as a reverse logging proxy, since it adds extremely low latency to proxied requests. It can offer a great way to monitor how an API is being used by existing users without having to use a key store. Keyless access will allow all requests through. All access control, versioning, quotas and rate limiting will not be possible as individual sessions are not identified. +## Example + To implement keyless access, simply set the flag in your API Definition: ```{.copyWrapper} @@ -35,4 +39,6 @@ This will stop checking keys that are proxied by Tyk. Keyless APIs cannot be selected for [Access Rights]({{< ref "getting-started/create-security-policy" >}}) in a security policy. {{< /note >}} +## Tyk Operator Example +Please consult the Tyk Operator supporting documentation for an example of how to configure an API within Tyk Operator for [Open Access]({{< ref "product-stack/tyk-operator/advanced-configurations/client-authentication#keyless-open" >}}). diff --git a/tyk-docs/content/basic-config-and-security/security/mutual-tls/client-mtls.md b/tyk-docs/content/basic-config-and-security/security/mutual-tls/client-mtls.md index fd4de4d7fb..231cb1979b 100644 --- a/tyk-docs/content/basic-config-and-security/security/mutual-tls/client-mtls.md +++ b/tyk-docs/content/basic-config-and-security/security/mutual-tls/client-mtls.md @@ -86,13 +86,15 @@ $ curl -k \ Static mTLS simply means to allow client certs at the API level. -to set it up, in the API authentication settings, choose mTLS and one other authentication type. If you don't want to use additional authentication type, i.e. only client cert alone, then select "keyless" as the other. +To set it up, in the API authentication settings, choose mTLS and one other authentication type. If you don't want to use additional authentication type, i.e. only client cert alone, then select "keyless" as the other. The base Identity can be anything as the client cert is the only thing configured. Here's what it should look like: {{< img src="/img/2.10/client_mtls_multiple_auth.png" alt="enable_cert" >}} +Please consult the Tyk Operator supporting documentation for an example of how to [configure static mTLS]({{< ref "product-stack/tyk-operator/advanced-configurations/client-authentication#client-mtls" >}}) with Tyk Operator. + ## FAQ #### Why am I getting "Unauthorized! Header Not Found" Error? diff --git a/tyk-docs/content/basic-config-and-security/security/mutual-tls/upstream-mtls.md b/tyk-docs/content/basic-config-and-security/security/mutual-tls/upstream-mtls.md index a3105be17e..e33da95722 100644 --- a/tyk-docs/content/basic-config-and-security/security/mutual-tls/upstream-mtls.md +++ b/tyk-docs/content/basic-config-and-security/security/mutual-tls/upstream-mtls.md @@ -15,21 +15,134 @@ If your upstream API is protected with mutual TLS you can configure Tyk to send - Specified client certificates will be used not only for internal Tyk calls but also for HTTP calls inside your JSVM middleware. -### How To Set Up +## How To Set Up -**Via API Definition** +### Via API Definition Inside your API definition you should set the `upstream_certificates` field to the following format: `{"example.com": ""}`. Defining on a global level looks the same, but should be specified via the `security.certificates.upstream` field in your Gateway configuration file. -**Via Dashboard** + +### Via Dashboard To do the same via the Tyk Dashboard, go to the **API Designer** > **Advanced Options** panel > **Upstream certificates** section. {{< img src="/img/2.10/attach_upstream_cert.png" alt="upstream_cert" >}} - -### Domain +### Via Tyk Operator + +Tyk Operator supports configuring upstream mTLS using one of the following fields within the ApiDefinition object: + +- **upstream_certificate_refs**: Configure using certificates stored within Kubernetes secret objects. +- **upstream_certificates**: Configure using certificates stored within Tyk Dashboard's certificate store. + +#### upstream_certificate_refs + +The `upstream_certificate_refs` field can be used to configure certificates for different domains. References can be held to multiple secrets which are used for the domain mentioned in the key. Currently "*" is used as a wildcard for all the domains + +The example listed below shows that the certificate in the secret, *my-test-tls*, is used for all domains. + +```yaml +# First apply this manifest using the command +# "kubectl apply -f config/samples/httpbin_upstream_cert.yaml" +# +# The operator will try to create the ApiDefinition and will succeed but will log an error that a certificate is missing +# in the cluster for an upstream +# +# Generate your public-private key pair , for test you can use the following command to obtain one fast: +# "openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes -out tls.crt -keyout tls.key" +# +# Run the following command to obtain the values that must be put inside the yaml that contians the secret resource: +# "kubectl create secret tls my-test-tls --key="tls.key" --cert="tls.crt" -n default -o yaml --dry-run=client" +# +# Apply your TLS certificate using the following command: (we already have an example one in our repo) +# "kubectl apply -f config/sample/simple_tls_secret.yaml" +# +# NOTE: the upstream_certificate_refs can hold references to multiple secrets which are used for the domain +# mentioned in the key (currently "*" is used as a wildcard for all the domains) +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin +spec: + name: httpbin + use_keyless: true + upstream_certificate_refs: + "*": my-test-tls + 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 +``` + +A secret can be created and output in yaml format using the following command: + +```bash +kubectl create secret tls my-test-tls --key="keyfile.key" --cert="certfile.crt" -n default -o yaml --dry-run=client +kubectl apply -f path/to/your/tls_secret.yaml +``` + +#### upstream_certificates + +The `upstream_certificates` field allows certificates uploaded to the certificate store in Tyk Dashboard to be referenced in the Api Definition: + +```yaml +# Skip the concatenation and .pem file creation if you already have a certificate in the correct format + +# First generate your public-private key pair , for test use you can use the following command to obtain one fast: +# "openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes -out tls.crt -keyout tls.key" + +# Concatenate the above files to obtain a .pem file which we will upload using the dashboard UI +# "cat tls.crt tls.key > cert.pem" + +# Upload it to the tyk certificate store using the dashboard + +# Fill in the manifest with the certificate id (the long hash) that you see is given to it in the dashboard +# (in place of "INSERT UPLOADED CERTIFICATE NAME FROM DASHBOARD HERE") +# Optional: Change the domain from "*" to something more specific if you need to use different +# upstream certificates for different domains + +# Then apply this manifest using the command +# "kubectl apply -f config/samples/httpbin_upstream_cert_manual.yaml" + +# The operator will try create the ApiDefinition and will succeed and it will have the requested domain upstream certificate +# in the cluster for an upstream + +# NOTE: the upstream_certificate can hold multiple domain-certificateName pairs +# (currently "*" is used as a wildcard for all the domains) + +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin +spec: + name: httpbin + use_keyless: true + upstream_certificates: + "*": #INSERT UPLOADED CERTIFICATE NAME FROM DASHBOARD HERE# + 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 +``` + +## Domain Do **NOT** include the protocol or Tyk will not match your certificates to the correct domain. @@ -44,7 +157,7 @@ Do **NOT** include the protocol or Tyk will not match your certificates to the c ✅ `api.production.myupstream.com:8443` -### Wild Cards +## Wild Cards You may use wild cards in combination with text to match the domain, but it only works one level deep. @@ -57,5 +170,3 @@ Example, if your domain is `api.production.myupstream.com` #### Default Upstream Cert To set a default client certificate, use `*` instead of domain name: `{"*": ""}` - - diff --git a/tyk-docs/content/context-variables.md b/tyk-docs/content/context-variables.md index 801bf77f90..a4823a54ad 100755 --- a/tyk-docs/content/context-variables.md +++ b/tyk-docs/content/context-variables.md @@ -90,4 +90,25 @@ URL Rewriter and Header Transform middleware cannot iterate through list indices {{< img src="/img/2.10/context_variables.png" alt="Context Variables" >}} -If not using a Tyk Dashboard, add the field `enable_context_vars` to your API definition file at root level and set it to `true`. \ No newline at end of file +If not using a Tyk Dashboard, add the field `enable_context_vars` to your API definition file at root level and set it to `true`. + +If you are using Tyk Operator, set the field `spec.enable_context_vars` to `true`. + +The example API Definition below enabled context variable: + +```yaml {linenos=true, linenostart=1, hl_lines=["10-10"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin +spec: + name: httpbin + use_keyless: true + protocol: http + active: true + enable_context_vars: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin + strip_listen_path: true +``` \ No newline at end of file diff --git a/tyk-docs/content/getting-started/key-concepts/versioning.md b/tyk-docs/content/getting-started/key-concepts/versioning.md index bba5876f2c..7a435542f3 100644 --- a/tyk-docs/content/getting-started/key-concepts/versioning.md +++ b/tyk-docs/content/getting-started/key-concepts/versioning.md @@ -15,6 +15,8 @@ API versioning is configured in the Tyk Classic API Definition. You can do this If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "getting-started/key-concepts/oas-versioning" >}}) page. +If you're using Tyk Operator then check out the [configuring API versioning in Tyk Operator](#tyk-operator) section below. + ### Controlling access to Tyk Classic API versions You can explicitly grant access to specific version(s) of an API by specifying only those version(s) in the [key]({{< ref "tyk-apis/tyk-gateway-api/token-session-object-details" >}}) (also known as an *authorization token*, *bearer token*, *access token*, *API token* or *token session object* - see [here]({{< ref "basic-config-and-security/security/authentication-authorization/bearer-tokens" >}})). @@ -221,3 +223,100 @@ From the **Endpoint Designer** tab, you can select the version that you wish to {{< img src="/img/dashboard/endpoint-designer/tyk-classic-version-endpoint.png" alt="Choosing the API version for which to configure endpoint middleware" >}} Select **Update** to save the changes to your API. + +## Configuring API versioning in Tyk Operator {#tyk-operator} + +The process for configuring API versioning is similar to that defined in section [Configuring API versioning in the Tyk Classic API Definition](#configuring-api-versioning-in-the-tyk-classic-api-definition). + +We can see in the example below that one version is configured for the API within `spec.version_data`: + +- the version name is `v1` +- the default version (`default_version`) is `v1` +- the `definition` configuration block contains a `location` field set to `header` and has an accompanying `key` field set to `x-api-version`. Subsequently, the version identifier for the API will be retrieved from the `x-api-version` header. The comments provide examples for how to configure the version identifier to be retrieved from URL or a named URL parameter +- an allow list, black list and ignore authentication middleware have been configured for version `v1` +- an alternative upstream URL (`override_target`) is configured for `v1` to send requests to `http://test.org`. + +```yaml {linenos=table,hl_lines=["14-17", "25-27", "29-82"], linenostart=1} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: versioned-api +spec: + name: Versioned API + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://version-api.example.com + listen_path: /version-api + strip_listen_path: true + definition: + # Tyk should find version data in Header + location: header + key: x-api-version + + # Tyk should find version data in First URL Element + #location: url + + # Tyk should find version data in URL/Form Parameter + #location: url-param + #key: api-version + version_data: + default_version: v1 + not_versioned: false + versions: + v1: + name: v1 + expires: "" + override_target: "http://test.org" + use_extended_paths: true + extended_paths: + ignored: + - path: /v1/ignored/noregex + method_actions: + GET: + action: no_action + code: 200 + data: "" + headers: + x-tyk-override-test: tyk-override + x-tyk-override-test-2: tyk-override-2 + white_list: + - path: v1/allowed/allowlist/literal + method_actions: + GET: + action: no_action + code: 200 + data: "" + headers: + x-tyk-override-test: tyk-override + x-tyk-override-test-2: tyk-override-2 + - path: v1/allowed/allowlist/reply/{id} + method_actions: + GET: + action: reply + code: 200 + data: flump + headers: + x-tyk-override-test: tyk-override + x-tyk-override-test-2: tyk-override-2 + - path: v1/allowed/allowlist/{id} + method_actions: + GET: + action: no_action + code: 200 + data: "" + headers: + x-tyk-override-test: tyk-override + x-tyk-override-test-2: tyk-override-2 + black_list: + - path: v1/disallowed/blocklist/literal + method_actions: + GET: + action: no_action + code: 200 + data: "" + headers: + x-tyk-override-test: tyk-override + x-tyk-override-test-2: tyk-override-2 +``` diff --git a/tyk-docs/content/planning-for-production/ensure-high-availability/load-balancing.md b/tyk-docs/content/planning-for-production/ensure-high-availability/load-balancing.md index 89b5dfc65b..4d326813f4 100755 --- a/tyk-docs/content/planning-for-production/ensure-high-availability/load-balancing.md +++ b/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" >}}). diff --git a/tyk-docs/content/plugins/plugin-types/analytics-plugins.md b/tyk-docs/content/plugins/plugin-types/analytics-plugins.md index 283579cdab..f5c91b7b43 100755 --- a/tyk-docs/content/plugins/plugin-types/analytics-plugins.md +++ b/tyk-docs/content/plugins/plugin-types/analytics-plugins.md @@ -20,9 +20,21 @@ 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, @@ -30,4 +42,39 @@ To enable the analytics rewriting functionality, adjust the following in API def "plugin_path": "/analytics_plugin.so" } } -``` \ No newline at end of file +``` + +{{< 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 >}} + +--- + +
diff --git a/tyk-docs/content/plugins/plugin-types/auth-plugins/auth-plugins.md b/tyk-docs/content/plugins/plugin-types/auth-plugins/auth-plugins.md index f5033f4c5e..c3d82d8431 100755 --- a/tyk-docs/content/plugins/plugin-types/auth-plugins/auth-plugins.md +++ b/tyk-docs/content/plugins/plugin-types/auth-plugins/auth-plugins.md @@ -13,23 +13,20 @@ aliases: If you have unique authentication requirements, you can write a custom authentication plugin. +## Session Authentication and Authorization -See the supported languages tab for custom authentication plugin examples in a Language of your choosing. There's also a [a blog that walks you through setting up gRPC custom auth in Java](https://tyk.io/how-to-setup-custom-authentication-middleware-using-grpc-and-java/) - -## Supported Languages for Custom Authentication Plugin -- All Rich Plugins (gRPC, Python, Lua) -- GoLang - -A very important thing to understand when using custom authentication plugins is that Tyk will continue to perform session authentication and authorization using the information returned by your plugin. Tyk will cache this Session information. **This is necessary in order to do things like rate limiting, access control, quotas, throttling, etc.** +A very important thing to understand when using custom authentication plugins is that Tyk will continue to perform session authentication and authorization using the information returned by your plugin. Tyk will cache this Session information. **This is necessary in order to do things like rate limiting, access control, quotas, throttling, etc.** Tyk will try to be clever about what to cache, but we need to help it. There are two ways to do that, with and without the `ID Extractor`. ### The ID Extractor + The ID Extractor is a caching mechanism that's used in combination with Tyk Plugins. It can be used specifically with plugins that implement custom authentication mechanisms. The ID Extractor works for all rich plugins: gRPC-based plugins, Python and Lua. See [ID Extractor]({{< ref "plugins/plugin-types/auth-plugins/id-extractor" >}}) for more details. -## Token Metadata +### Token Metadata + Tyk creates an in-memory object to track the rate limit, quotas, and more for each session. This is why we set the `token` metadata when using custom authentication middleware, in order to give Tyk a unique ID with which to track each session. @@ -52,5 +49,23 @@ object.Session = &coprocess.SessionState{ ``` [source](https://github.com/TykTechnologies/tyk-grpc-go-basicauth-jwt/blob/master/main.go#L102) -## Without ID Extractor -When not using ID Extractor, Tyk will continue to cache authenticated sessions returned by custom auth plugins. We must set a unique `token` field in the Metadata (see above) that Tyk will use to cache. \ No newline at end of file +### Without ID Extractor + +When not using ID Extractor, Tyk will continue to cache authenticated sessions returned by custom auth plugins. We must set a unique `token` field in the Metadata (see above) that Tyk will use to cache. + +## Supported Languages + +The following languages are supported for custom authentication plugins: + +- All Rich Plugins (gRPC, Python, Lua) +- GoLang + +See the [supported languages]({{< ref "plugins/supported-languages" >}}) section for custom authentication plugin examples in a language of your choosing. There's also a [blog that walks you through setting up gRPC custom auth in Java](https://tyk.io/how-to-setup-custom-authentication-middleware-using-grpc-and-java/). + +## Tyk Operator + +Please consult the Tyk Operator supporting documentation for examples of how to configure a Tyk Operator API to use: + +- [Go custom authentication plugin]({{< ref "product-stack/tyk-operator/advanced-configurations/client-authentication#custom-plugin-auth-go" >}}) +- [gRPC custom authentication plugin]({{< ref "product-stack/tyk-operator/advanced-configurations/client-authentication#custom-plugin-auth-grpc" >}}) + diff --git a/tyk-docs/content/plugins/supported-languages/rich-plugins/grpc/write-grpc-plugin.md b/tyk-docs/content/plugins/supported-languages/rich-plugins/grpc/write-grpc-plugin.md index 90b8edc7e9..c4ccaaa1f8 100755 --- a/tyk-docs/content/plugins/supported-languages/rich-plugins/grpc/write-grpc-plugin.md +++ b/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 @@ -144,6 +148,8 @@ For configurations directly embedded within the Tyk Gateway, plugin hooks can be } ``` +For example, a Post request plugin hook has been configured with name `MyPostMiddleware`. Before the request is sent upstream Tyk Gateway will serialize the request into a [Object protobuf message]({{< ref "plugins/supported-languages/rich-plugins/rich-plugins-data-structures#object" >}}) with the `hook_name` property set to `MyPostMiddleware` and the `hook_type` property set to `Post`. This message will then then be dispatched to the gRPC server for processing before the request is sent upstream. +
{{< note success >}} **Note** @@ -151,6 +157,63 @@ 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. + +Setting the `driver` configuring parameter to `gRPC` instructs Tyk Gateway to issue a request to your gRPC server for each plugin hook that you have configured. + +**Pre plugin hook example** + +In this example we can see that a `custom_middleware` configuration block has been used to configure a gRPC Pre request plugin hook with name `HelloFromPre`. Before any middleware is executed Tyk Gateway will serialize the request into a [Object protobuf message]({{< ref "plugins/supported-languages/rich-plugins/rich-plugins-data-structures#object" >}}) with the `hook_name` property set to `HelloFromPre` and the `hook_type` property set to `Pre`. This message will then then be dispatched to the gRPC server. + +```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** + +In the example we can see that a `custom_middleware` configuration block has been used to configure a gRPC Post plugin with name `HelloFromPost`. + +Before the request is sent upstream Tyk Gateway will serialize the request and session details into a [Object protobuf message]({{< ref "plugins/supported-languages/rich-plugins/rich-plugins-data-structures#object" >}}) with the `hook_name` property set to `HelloFromPost` and the `hook_type` property set to `Post`. This message will then then be dispatched to the gRPC server for processing before the request is sent upstream. + +```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 @@ -202,6 +265,8 @@ The resulting bundle file should then be uploaded to the webserver that hosts yo #### Configure API +##### Tyk Gateway + To add a gRPC plugin to your API definition, you must specify the bundle file name within the `custom_middleware_bundle` field: ```yaml @@ -214,6 +279,10 @@ To add a gRPC plugin to your API definition, you must specify the bundle file na The value of the `custom_middleware_bundle` field will be used in combination with the gateway settings to construct a bundle URL. For example, if Tyk Gateway is configured with a webserver base URL of https://my-bundle-server.com/bundles/ then an attempt would be made to download the bundle from https://my-bundle-server.com/bundles/mybundle.zip. +##### Tyk Operator + + Currently this feature is not yet documented with a Tyk Operator example for configuring an API to use plugin bundles. For further details please reach out and contact us on the [community support forum](https://community.tyk.io). + --- ## Test your API Endpoint diff --git a/tyk-docs/content/product-stack/tyk-gateway/basic-config-and-security/logging-api-traffic/detailed-recording.md b/tyk-docs/content/product-stack/tyk-gateway/basic-config-and-security/logging-api-traffic/detailed-recording.md index 9ffa1f00bd..b2f667f4be 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/basic-config-and-security/logging-api-traffic/detailed-recording.md +++ b/tyk-docs/content/product-stack/tyk-gateway/basic-config-and-security/logging-api-traffic/detailed-recording.md @@ -82,7 +82,7 @@ In the Dashboard UI, you can configure detailed recording using the Enable Detai {{< img src="/img/dashboard/api-designer/tyk-oas-detailed-logs.png" alt="Enabling detailed activity logs for a Tyk OAS API" >}} -#### Detailed recording with Tyk Classic APIs +#### Detailed recording with Tyk Classic APIs {#tyk-classic} When working with Tyk Classic APIs, you should configure `enable_detailed_recording: "true"` in the root of the API definition: @@ -94,6 +94,29 @@ In the Dashboard UI, you can configure detailed recording using the Enable Detai {{< img src="/img/dashboard/endpoint-designer/classic-detailed-logging.png" alt="Enabling detailed activity logs for a Tyk Classic API" >}} +#### Detailed recording with Tyk Operator + +The process for configuring detailed recording using Tyk Operator is similar to that explained in [Detailed recording with Tyk Classic APIs](#tyk-classic). + +The example API Definition below enabled detailed recording by setting `spec.enable_detailed_recording` to `true`. + +```yaml {linenos=true, linenostart=1, hl_lines=["10-10"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin +spec: + name: httpbin + use_keyless: true + protocol: http + active: true + enable_detailed_recording: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin + strip_listen_path: true +``` + ### Configuration at the key level An alternative approach to controlling detailed recording is to enable it only for specific [access keys]({{< ref "getting-started/key-concepts/what-is-a-session-object" >}}). This is particularly useful for debugging purposes where you can configure detailed recording only for the key(s) that are reporting issues. diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/allow-list-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/allow-list-tyk-classic.md index 68e537d815..fad31910fe 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/allow-list-tyk-classic.md +++ b/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,hl_lines=["26-34"]} +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`. diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/block-list-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/block-list-tyk-classic.md index b4a317f3c3..37875f0770 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/block-list-tyk-classic.md +++ b/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, hl_lines=["26-34"]} +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 this endpoint 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`. + diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/circuit-breaker-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/circuit-breaker-tyk-classic.md index 3ab5d4912c..fed5be6859 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/circuit-breaker-tyk-classic.md +++ b/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,50 @@ 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" >}} \ No newline at end of file +{{< 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 {linenos=true, linenostart=1, hl_lines=["30-35"]} +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 + threshold_percent: "0.5" +``` + +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. \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/do-not-track-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/do-not-track-tyk-classic.md index 4886aa4e39..038d2eeed6 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/do-not-track-tyk-classic.md +++ b/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,69 @@ 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 prevent tracking for all endpoints of an API by configuring the `do_not_track` field in the root of your API definition as follows: + +- `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: + 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" +``` + +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. diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/endpoint-cache-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/endpoint-cache-tyk-classic.md index b02e3bbd18..ed980ac3ab 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/endpoint-cache-tyk-classic.md +++ b/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. @@ -52,7 +54,7 @@ For example: In this example the endpoint caching middleware has been configured to cache all safe requests to two endpoints (`/widget` and `/fish`) with a cache refresh period of 60 seconds. -#### Advanced endpoint cache +#### Advanced endpoint cache {#tyk-classic-advanced-caching} For ultimate control over what Tyk caches, you should use the advanced configuration options for the per-endpoint cache. You can separately configure, for each HTTP method for an endpoint: - an individual cache refresh (timeout) @@ -176,3 +178,103 @@ 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, hl_lines=["26-35"]} +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 + +Advanced caching with Tyk Operator is a similar process to that for configuring the [advanced caching middleware in the Tyk Classic API Definition](#tyk-classic-advanced-caching). + +To enable the advanced middleware you must add a new `advance_cache_config` object to the `extended_paths` section of your API definition. + +This allows you to configure caching per endpoint. For each endpoint, it is possible to specify the endpoint path, method, list of response codes to cache, cache timeout and a cache key regular expression. The cache key regular expression represents a pattern match to cache only requests containing specific data in the [request body]({{< ref " basic-config-and-security/reduce-latency/caching/advanced-cache#selective-caching-by-body-value" >}}) + +For example: + +```yaml {linenos=true, linenostart=1, hl_lines=["26-35"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-advance-cache +spec: + name: httpbin-advance-cache + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin-advance-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: + advance_cache_config: + - path: /anything + method: GET + cache_key_regex: "" + cache_response_codes: [200] + cache_options: + cache_timeout: 30 + enable_cache: true +``` + +In this example the endpoint caching middleware has been configured to cache requests for the `/anything` endpoint as follows: + +| endpoint | HTTP response codes to cache | cache refresh timeout | body value regex | +|----------|------------------------------|-----------------------|------------------| +| `GET /anything` | 200 | 30 seconds (taken from `cache_options`) | none | diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/enforced-timeout-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/enforced-timeout-tyk-classic.md index e2930351bb..e903066641 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/enforced-timeout-tyk-classic.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/enforced-timeout-tyk-classic.md @@ -11,7 +11,9 @@ When working with Tyk Classic APIs the enforced timeout 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/enforced-timeout-tyk-oas" >}}) page. -## Configuring an enforced timeout in the Tyk Classic API Definition +If you're using Tyk Operator then check out the [configuring an enforced timeout in Tyk Operator](#tyk-operator) section below. + +## Configuring an enforced timeout in the Tyk Classic API Definition {#tyk-classic} To configure an enforced timeout you must add a new `hard_timeouts` object to the `extended_paths` section of your API definition. @@ -56,3 +58,62 @@ Then enter the timeout to be enforced for the endpoint (in seconds): #### Step 3: Save the API Use the *save* or *create* buttons to save the changes and activate the middleware. + +## Configuring an enforced timeout in Tyk Operator {#tyk-operator} + +The process for configuring the middleware in Tyk Operator is similar to that explained in [configuring an enforced timeout in the Tyk Classic API Definition](#tyk-classic). It is possible to configure an enforced timeout using the `hard_timeouts` object within the `extended_paths` section of the API Definition. + +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 {linenos=true, linenostart=1, hl_lines=["26-29"]} +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 + threshold_percent: "0.5" # Tyk Dashboard API doesn't support strings. +``` + +We can test the example using the curl command as shown below: + +```bash +curl http://localhost:8081/httpbin-timeout/delay/3 -i + HTTP/1.1 504 Gateway Timeout +Content-Type: application/json +X-Generator: tyk.io +Date: Fri, 09 Aug 2024 07:43:48 GMT +Content-Length: 57 + +{ + "error": "Upstream service reached hard timeout." +} +``` \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/ignore-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/ignore-tyk-classic.md index f3465b5534..42742fbf97 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/ignore-tyk-classic.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/ignore-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/ignore-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} To enable the middleware you must add a new `ignored` object to the `extended_paths` section of your API definition. @@ -71,3 +73,48 @@ Once you have selected the Ignore middleware for the endpoint, the only addition #### Step 3: 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 configure an enforced timeout using the `ignored` object within the `extended_paths` section of the API Definition. + +In the example below the ignore authentication middleware has been configured for requests to the `GET /get` endpoint. Any such calls will skip the authentication step in the Tyk Gateway's processing chain. +- the middleware has been configured to be case insensitive, so calls to `GET /Get` will also skip authentication + +```yaml {linenos=true, linenostart=1, hl_lines=["27-35"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-ignored +spec: + name: httpbin-ignored + use_keyless: false + use_standard_auth: 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: + ignored: + - ignore_case: true + method_actions: + GET: + action: "no_action" + code: 200 + data: "" + headers: {} + path: "/get" +``` diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/internal-endpoint-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/internal-endpoint-tyk-classic.md index 36d3849b2e..2a75a75b67 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/internal-endpoint-tyk-classic.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/internal-endpoint-tyk-classic.md @@ -11,7 +11,9 @@ When working with Tyk Classic APIs, the middleware is configured in the Tyk Clas If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/internal-endpoint-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} To enable the middleware you must add a new `internal` object to the `extended_paths` section of your API definition. @@ -49,3 +51,40 @@ From the **Endpoint Designer** add an endpoint that matches the path that you wi #### 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). The middleware can be configured by adding a new `internal` object to the `extended_paths` section of your API definition. + +In the example below the internal endpoint middleware has been configured for HTTP `GET` requests to the `/status/200` endpoint. Any requests made to this endpoint that originate externally to Tyk will be rejected with `HTTP 403 Forbidden`. Conversely, the endpoint can be reached internally by another API at `tyk:///status/200`. + +```yaml {linenos=true, linenostart=1, hl_lines=["26-28"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-endpoint-internal +spec: + name: httpbin - Endpoint Internal + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org/ + listen_path: /httpbin-internal + 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: + internal: + - path: /status/200 + method: GET +``` diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-tyk-classic.md index c36587b14c..3e3584df6e 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-tyk-classic.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-tyk-classic.md @@ -13,6 +13,8 @@ The middleware is configured in the Tyk Classic API Definition. You can do this If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/mock-response-tyk-oas" >}}) page. +If you're using Tyk Operator then check out the [configuring the middleware in Tyk Operator](#tyk-operator) section below. + ### Endpoint parsing When you define an endpoint in your API Definition (for example `GET /anything`), Tyk will also match for `GET /anything/somepath` and any other sub-path based on the `GET /anything` route. @@ -23,7 +25,7 @@ If you add a `$` at the end of the `listen_path` (in our example `GET /anything$ Thus, if you enable the middleware for `GET /anything$` then `GET /anything/somepath` will be proxied to the upstream and will not trigger the mock response. -## Configuring the middleware in the Tyk Classic API Definition +## Configuring the middleware in the Tyk Classic API Definition {#tyk-classic} To enable mock response, you must first add the endpoint to a list - one of [allow list]({{< ref "product-stack/tyk-gateway/middleware/allow-list-middleware" >}}), [block list]({{< ref "product-stack/tyk-gateway/middleware/block-list-middleware" >}}) or [ignore authentication]({{< ref "product-stack/tyk-gateway/middleware/ignore-middleware" >}}). This will add a new object to the `extended_paths` section of your API definition - `white_list`, `black_list` or `ignored`. The mock response can then be configured within the `method_actions` element within the new object. @@ -108,3 +110,52 @@ Use the *save* or *create* buttons to save the changes and activate the middlewa For the mock response to be enabled, the endpoint must also be in a list. We recommend adding the path to an [allow list]({{< ref "advanced-configuration/transform-traffic/endpoint-designer#allowlist" >}}). If this isn't done, then the mock will not be saved when you save your API in the designer. {{< /note >}} + +## Configuring the middleware in Tyk Operator {#tyk-operator} + +The process of configuring a mock response is similar to that defined in section [configuring the middleware in Tyk Classic API definition](#tyk-classic). + +To configure a mock response, you must first add a mock response configuration object to the `extended_paths` section, e.g. one of allow list (`white_list`), block list (`black_list`) or ignore authentication (`ignore`). The mock response configuration object has the following properties: + +- path: the path of the endpoint, e.g `/foo`. +- ignore_case: when set to true the path matching is case insensitive. +- method_actions: a configuration object that allows the mock response to be configured for a given method, including the response body, response headers and status code. This object should also contain an `action` field with a value set to `reply`. + +In the example below we can see that a mock response is configured to ignore authentication (`ignore`) for the `GET /foo` endpoint. When a request is made to the endpoint then authentication will be ignored and a mock response is returned with status code `200` and a response body payload of `{"foo": "bar"}`. The middleware has been configured to be case sensitive, so calls to `GET /Foo` will not ignore authentication. + +```yaml {linenos=true, linenostart=1, hl_lines=["26-34"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin +spec: + name: httpbin + protocol: http + active: true + use_keyless: 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: + ignored: + - ignore_case: false + method_actions: + GET: + action: "reply" + code: 200 + data: "{\"foo\": \"bar\"}" + headers: {} + path: /foo +``` diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/request-body-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-body-tyk-classic.md index 576002d161..db9ce1bbdc 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/request-body-tyk-classic.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-body-tyk-classic.md @@ -13,7 +13,9 @@ If you want to use dynamic data from context variables, you must [enable]({{< re If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/request-body-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} To enable the middleware you must add a new `transform` object to the `extended_paths` section of your API definition. @@ -83,3 +85,72 @@ If sample input data is available, you can use the Input box to add it, and then #### Step 4: Save the API Use the *save* or *create* buttons to save the changes and activate the Request Body Transform middleware. + +## Configuring the middleware in Tyk Operator {#tyk-operator} + +The process for configuring a request body transform is similar to that defined in section [Configuring the middleware in the Tyk Classic API Definition](#tyk-classic). Tyk Operator allows you to configure a request body transform by adding a `transform` object to the `extended_paths` section of your API definition. + +In the example below the Request Body middleware (`transform`) has been configured for `HTTP POST` requests to the `/anything` endpoint. The Request Body Transform middleware is directed to use the template located in the blob included in the `template_source` field. The input (pre-transformation) request payload will be json format and session metadata will be available for use in the transformation. + +```yaml {linenos=true, linenostart=1, hl_lines=["32-40"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-transform +spec: + name: httpbin-transform + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin-transform + strip_listen_path: true + response_processors: + - name: response_body_transform + - name: header_injector + version_data: + default_version: Default + not_versioned: true + versions: + Default: + name: Default + use_extended_paths: true + paths: + black_list: [] + ignored: [] + white_list: [] + extended_paths: + transform: + - method: POST + path: /anything + template_data: + enable_session: false + input_type: json + template_mode: blob + # base64 encoded template + template_source: eyJiYXIiOiAie3suZm9vfX0ifQ== + transform_headers: + - delete_headers: + - "remove_this" + add_headers: + foo: bar + path: /anything + method: POST + transform_response: + - method: GET + path: /xml + template_data: + enable_session: false + input_type: xml + template_mode: blob + # base64 encoded template + template_source: e3sgLiB8IGpzb25NYXJzaGFsIH19 + transform_response_headers: + - method: GET + path: /xml + add_headers: + Content-Type: "application/json" + act_on: false + delete_headers: [] +``` diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/request-header-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-header-tyk-classic.md index 65586f3a8f..96a21dfe1f 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/request-header-tyk-classic.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-header-tyk-classic.md @@ -23,11 +23,13 @@ If you want to use dynamic data from context variables, you must [enable]({{< re If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/request-header-tyk-oas" >}}) page. -## Configuring the Request Header Transform in the Tyk Classic API Definition +If you're using Tyk Operator then check out the [configuring the Request Header Transform in Tyk Operator](#tyk-operator) section below. + +## Configuring the Request Header Transform in the Tyk Classic API Definition {#tyk-classic} The API-level and endpoint-level request header transforms have a common configuration but are configured in different sections of the API definition. -#### API-level transform +#### API-level transform {#tyk-classic-api} To **append** headers to all requests to your API (i.e. for all endpoints) you must add a new `global_headers` object to the `versions` section of your API definition. This contains a list of key:value pairs, being the names and values of the headers to be added to requests. @@ -61,7 +63,7 @@ This configuration will add three new headers to each request: It will also delete one header (if present) from each request: - `Auth_Id` -#### Endpoint-level transform +#### Endpoint-level transform {#tyk-classic-endpoint} To configure a transformation of the request header for a specific endpoint you must add a new `transform_headers` object to the `extended_paths` section of your API definition. @@ -137,4 +139,116 @@ Select the headers to delete and insert using the provided fields. You need to c Use the *save* or *create* buttons to save the changes and activate the middleware. +## Configuring the Request Header Transform in Tyk Operator {#tyk-operator} + +The process for configuring a request header transform is similar to that defined in section [Configuring the Request Header Transform in the Tyk Classic API Definition](#tyk-classic). Tyk Operator allows you to configure a request size limit for [all endpoints of an API](#tyk-operator-api) or for a [specific API endpoint](#tyk-operator-endpoint). + +### API-level transform {#tyk-operator-api} + +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 transform {#tyk-operator-endpoint} + +The process of configuring a transformation of a request header for a specific endpoint is similar to that defined in section [Endpoint-level transform](#tyk-classic-endpoint). To configure a transformation of the request header for a specific endpoint you must add a new `transform_headers` object to the `extended_paths` section of your API definition. + +In the example below the Request Header Transform middleware (`transform_headers`) has been configured for HTTP `POST` requests to the `/anything` endpoint. Any request received to that endpoint will have the `remove_this` header removed and the `foo` header added, with the value set to `bar`. + +```yaml {linenos=true, linenostart=1, hl_lines=["41-47"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-transform +spec: + name: httpbin-transform + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin-transform + strip_listen_path: true + response_processors: + - name: response_body_transform + - name: header_injector + version_data: + default_version: Default + not_versioned: true + versions: + Default: + name: Default + use_extended_paths: true + paths: + black_list: [] + ignored: [] + white_list: [] + extended_paths: + transform: + - method: POST + path: /anything + template_data: + enable_session: false + input_type: json + template_mode: blob + # base64 encoded template + template_source: eyJiYXIiOiAie3suZm9vfX0ifQ== + transform_headers: + - delete_headers: + - "remove_this" + add_headers: + foo: bar + path: /anything + method: POST + transform_response: + - method: GET + path: /xml + template_data: + enable_session: false + input_type: xml + template_mode: blob + # base64 encoded template + template_source: e3sgLiB8IGpzb25NYXJzaGFsIH19 + transform_response_headers: + - method: GET + path: /xml + add_headers: + Content-Type: "application/json" + act_on: false + delete_headers: [] +``` diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/request-method-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-method-tyk-classic.md index e0793426b5..a468bc3f74 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/request-method-tyk-classic.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-method-tyk-classic.md @@ -11,7 +11,9 @@ When working with Tyk Classic APIs the transformation is configured in the Tyk C If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/request-method-tyk-oas" >}}) page. -## Configuring a Request Method Transform in the Tyk Classic API Definition +If you're using Tyk Operator then check out the [configuring a Request Method Transform in Tyk Operator](#tyk-operator) section below. + +## Configuring a Request Method Transform in the Tyk Classic API Definition {#tyk-classic} To configure a transformation of the request method you must add a new `method_transforms` object to the `extended_paths` section of your API definition. @@ -57,4 +59,46 @@ Then select the HTTP method to which you wish to transform the request. #### Step 3: Save the API -Use the *save* or *create* buttons to save the changes and activate the middleware. \ No newline at end of file +Use the *save* or *create* buttons to save the changes and activate the middleware. + +## Configuring a Request Method Transform in Tyk Operator {#tyk-operator} + +The process for configuring a request method transform for an endpoint in Tyk Operator is similar to that defined in section [configuring a Request Method Transform in the Tyk Classic API Definition](#tyk-classic). + +To configure a transformation of the request method you must add a new `method_transforms` object to the `extended_paths` section of your API definition: + +```yaml {linenos=true, linenostart=1, hl_lines=["26-29"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin +spec: + name: httpbin + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.default.svc:8000 + listen_path: /transform + strip_listen_path: true + version_data: + default_version: v1 + not_versioned: true + versions: + v1: + name: v1 + use_extended_paths: true + paths: + black_list: [] + ignored: [] + white_list: [] + extended_paths: + method_transforms: + - path: /anything + method: GET + to_method: POST +``` + +The example API Definition above configures an API to listen on path `/transform` and forwards requests upstream to http://httpbin.org. + +In this example the Request Method Transform middleware has been configured for `HTTP GET` requests to the `/anything` endpoint. Any request received to that endpoint will be modified to `POST /anything`. diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/request-size-limit-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-size-limit-tyk-classic.md index 5764cc8dd2..812fadd14a 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/request-size-limit-tyk-classic.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-size-limit-tyk-classic.md @@ -11,14 +11,16 @@ This middleware is configured in the Tyk Classic API Definition. You can do this If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/request-size-limit-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} There are three different levels of granularity that can be used when configuring a request size limit. - [system-wide]({{< ref "basic-config-and-security/control-limit-traffic/request-size-limits#applying-a-system-wide-size-limit" >}}): affecting all APIs deployed on the gateway - [API-level]({{< ref "product-stack/tyk-gateway/middleware/request-size-limit-tyk-classic#applying-a-size-limit-for-a-specific-api" >}}): affecting all endpoints for an API - [endpoint-level]({{< ref "product-stack/tyk-gateway/middleware/request-size-limit-tyk-classic#applying-a-size-limit-for-a-specific-endpoint" >}}): affecting a single API endpoint -### Applying a size limit for a specific API +### Applying a size limit for a specific API {#tyk-classic-api} You can configure a request size limit (in bytes) to an API by configuring the `global_size_limit` within the `version` element of the API Definition, for example: ``` @@ -29,7 +31,7 @@ A value of zero (default) means that no maximum is set and the API-level size li This limit is applied for all endpoints within an API. It is evaluated after the Gateway-wide size limit and before any endpoint-specific size limit. If this test fails, the Tyk Gateway will report `HTTP 400 Request is too large`. -### Applying a size limit for a specific endpoint +### Applying a size limit for a specific endpoint {#tyk-classic-endpoint} The most granular control over request sizes is provided by the endpoint-level configuration. This limit will be applied after any Gateway-level or API-level size limits and is given in bytes. If this test fails, the Tyk Gateway will report `HTTP 400 Request is too large`. @@ -82,4 +84,80 @@ Use the *save* or *create* buttons to save the changes and activate the middlewa **Note** The Tyk Classic API Designer does not provide an option to configure `global_size_limit`, but you can do this from the Raw Definition editor. -{{< /note >}} \ No newline at end of file +{{< /note >}} + +## Configuring the middleware in Tyk Operator {#tyk-operator} + +The process for configuring a request size limit is similar to that defined in section [configuring the middleware in the Tyk Classic API Definition](#tyk-classic). Tyk Operator allows you to configure a request size limit for [all endpoints of an API](#tyk-operator-api) or for a [specific API endpoint](#tyk-operator-endpoint). + +### Applying a size limit for a specific API {#tyk-operator-api} + + +The process for configuring the request size_limits middleware for a specific API is similar to that explained in [applying a size limit for a specific API](#tyk-classic-api). + +You can configure a request size limit (in bytes) for all endpoints within an API by configuring the `global_size_limit` within the `version` element of the API Definition, for example: + +```yaml {linenos=true, linenostart=1, hl_lines=["19"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-global-limit +spec: + name: httpbin-global-limit + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin-global-limit + strip_listen_path: true + version_data: + default_version: Default + not_versioned: true + versions: + Default: + global_size_limit: 5 + name: Default +``` + +The example API Definition above configures an API to listen on path `/httpbin-global-limit` and forwards requests upstream to http://httpbin.org. + +In this example the request size limit is set to 5 bytes. If the limit is exceeded then the Tyk Gateway will report `HTTP 400 Request is too large`. + +### Applying a size limit for a specific endpoint {#tyk-operator-endpoint} + +The process for configuring the request size_limits middleware for a specific endpoint is similar to that explained in [applying a size limit for a specific endpoint](#tyk-classic-endpoint). + +To configure the request size_limits middleware you must add a new `size_limits` object to the `extended_paths` section of your API definition, for example: + +```yaml {linenos=true, linenostart=1, hl_lines=["22-25"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-limit +spec: + name: httpbin-limit + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin-limit + strip_listen_path: true + version_data: + default_version: Default + not_versioned: true + versions: + Default: + name: Default + use_extended_paths: true + extended_paths: + size_limits: + - method: POST + path: /post + size_limit: 5 +``` + +The example API Definition above configures an API to listen on path `/httpbin-limit` and forwards requests upstream to http://httpbin.org. + +In this example the endpoint-level Request Size Limit middleware has been configured for `HTTP POST` requests to the `/post` endpoint. For any call made to this endpoint, Tyk will check the size of the payload (Request body) and, if it is larger than 5 bytes, will reject the request, returning `HTTP 400 Request is too large`. diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/response-body-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/response-body-tyk-classic.md index 7a6b620c2e..cdee3846af 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/response-body-tyk-classic.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/response-body-tyk-classic.md @@ -11,7 +11,9 @@ This middleware is configured in the Tyk Classic API Definition at the endpoint If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/response-body-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} To enable the middleware you must add a new `transform_response` object to the `extended_paths` section of your API definition. @@ -99,3 +101,138 @@ If you have sample input data, you can use the Input box to add it, and then tes #### Step 4: Save the API Use the *save* or *create* buttons to save the changes and activate the Response Body Transform middleware. + +## Configuring the middleware in Tyk Operator {#tyk-operator} + +The process of configuring a transformation of a response body for a specific endpoint is similar to that defined in section [configuring the middleware in the Tyk Classic API Definition](#tyk-classic) for the Tyk Classic API definition. To enable the middleware you must add a new `transform_response` object to the `extended_paths` section of your API definition. + +In the examples below, the Response Body Transform middleware (`transform_response`) is directed to use the template located in the `template_source`, decoding the xml in the base64 encoded string. The input (pre-transformation) response payload will be `xml` format and there is no session metadata provided for use in the transformation. + +### Example + +```yaml {linenos=true, linenostart=1, hl_lines=["45-53"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-transform +spec: + name: httpbin-transform + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin-transform + 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: + transform: + - method: POST + path: /anything + template_data: + enable_session: false + input_type: json + template_mode: blob + # base64 encoded template + template_source: eyJiYXIiOiAie3suZm9vfX0ifQ== + transform_headers: + - delete_headers: + - "remove_this" + add_headers: + foo: bar + path: /anything + method: POST + transform_response: + - method: GET + path: /xml + template_data: + enable_session: false + input_type: xml + template_mode: blob + # base64 encoded template + template_source: e3sgLiB8IGpzb25NYXJzaGFsIH19 + transform_response_headers: + - method: GET + path: /xml + add_headers: + Content-Type: "application/json" + act_on: false + delete_headers: [] +``` + +### Tyk Gateway < 5.3.0 Example {#gw-lt-5-3-example} + +If using Tyk Gateway < v5.3.0 then a `response_processor` object must be added to the API definition containing a `response_body_transform` item, as highlighted below: + +```yaml {linenos=true, linenostart=1, hl_lines=["17-18", "48-56"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-transform +spec: + name: httpbin-transform + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin-transform + strip_listen_path: true + response_processors: + - name: response_body_transform + - name: header_injector + version_data: + default_version: Default + not_versioned: true + versions: + Default: + name: Default + use_extended_paths: true + paths: + black_list: [] + ignored: [] + white_list: [] + extended_paths: + transform: + - method: POST + path: /anything + template_data: + enable_session: false + input_type: json + template_mode: blob + # base64 encoded template + template_source: eyJiYXIiOiAie3suZm9vfX0ifQ== + transform_headers: + - delete_headers: + - "remove_this" + add_headers: + foo: bar + path: /anything + method: POST + transform_response: + - method: GET + path: /xml + template_data: + enable_session: false + input_type: xml + template_mode: blob + # base64 encoded template + template_source: e3sgLiB8IGpzb25NYXJzaGFsIH19 + transform_response_headers: + - method: GET + path: /xml + add_headers: + Content-Type: "application/json" + act_on: false + delete_headers: [] +``` \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/response-header-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/response-header-tyk-classic.md index 5144399510..7ba6dee567 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/response-header-tyk-classic.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/response-header-tyk-classic.md @@ -23,7 +23,9 @@ If you want to use dynamic data from context variables, you must [enable]({{< re If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/response-header-tyk-oas" >}}) page. -## Configuring the Response Header Transform in the Tyk Classic API Definition +If you're using Tyk Operator then check out the [configuring the Response Header Transform in Tyk Operator](#tyk-operator) section below. + +## Configuring the Response Header Transform in the Tyk Classic API Definition {#tyk-classic} The API-level and endpoint-level response header transforms have a common configuration but are configured in different sections of the API definition. {{< note success >}} @@ -44,7 +46,7 @@ If using the Endpoint Designer in the Tyk Dashboard, this would be added automat We removed the need to configure the `response_processors` element in Tyk 5.3.0. {{< /note >}} -#### API-level transform +#### API-level transform {#tyk-classic-api} To **append** headers to all responses from your API (i.e. for all endpoints) you must add a new `global_response_headers` object to the `versions` section of your API definition. This contains a list of key:value pairs, being the names and values of the headers to be added to responses. @@ -78,7 +80,7 @@ This configuration will add three new headers to each response: It will also delete one header (if present) from each response: - `X-Secret` -#### Endpoint-level transform +#### Endpoint-level transform {#tyk-classic-endpoint} To configure response header transformation for a specific endpoint you must add a new `transform_response_headers` object to the `extended_paths` section of your API definition. @@ -184,4 +186,197 @@ Select the headers to delete and insert using the provided fields. You need to c Use the *save* or *create* buttons to save the changes and activate the middleware. +## Configuring the Response Header Transform in Tyk Operator {#tyk-operator} + +The process for configuring a response header transform in Tyk Operator is similar to that defined in section [configuring the Response Header Transform in the Tyk Classic API Definition](#tyk-classic). Tyk Operator allows you to configure a response header transformation for [all endpoints of an API](#tyk-operator-endpoint) or for a [specific API endpoint](#tyk-operator-api). + +### API-level transform {#tyk-operator-api} + +The process of configuring transformation of response headers for a specific API in Tyk Operator is similar to that defined in section [API-level transform](#tyk-classic-api) for the Tyk Classic API definition. + +To **append** headers to all responses from your API (i.e. for all endpoints) you must add a new `global_response_headers` object to the `versions` section of your API definition. This contains a list of key:value pairs, being the names and values of the headers to be added to responses. + +To **delete** headers from all responses from your API (i.e. for all endpoints), you must add a new `global_response_headers_remove` object to the `versions` section of the API definition. This contains a list of the names of existing headers to be removed from responses. + +An example is listed below: + +```yaml {linenos=true, linenostart=1, hl_lines=["25-30"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-global-header +spec: + name: httpbin-global-header + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin-global-header + 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_response_headers: + X-Static: foobar + X-Request-ID: "$tyk_context.request_id" + X-User-ID: "$tyk_meta.uid" + global_response_headers_remove: + - X-Secret +``` + +The example API Definition above configures an API to listen on path `/httpbin-global-header` and forwards requests upstream to http://httpbin.org. +This configuration will add three new headers to each response: + +- `X-Static` with the value `foobar` +- `X-Request-ID` with a dynamic value taken from the `request_id` [context variable]({{< ref "context-variables" >}}) +- `X-User-ID` with a dynamic value taken from the `uid` field in the [session metadata]({{< ref "getting-started/key-concepts/session-meta-data" >}}) + +It will also delete one header (if present) from each response: + +- `X-Secret` + + +### Endpoint-level transform {#tyk-operator-endpoint} + +The process of configuring a transformation of a response header for a specific endpoint in Tyk Operator is similar to that defined in section [endpoint-level transform](#tyk-classic-endpoint) for the Tyk Classic API definition. To configure a transformation of the response headers for a specific endpoint you must add a new `transform_response_headers` object to the `extended_paths` section of your API definition. + +In this example the Response Header Transform middleware (`transform_response_headers`) has been configured for HTTP `GET` requests to the `/xml` endpoint. Any response received from the upstream service following a request to that endpoint will have the `Content-Type` header added with a value set to `application/json`. + +##### Example + +```yaml {linenos=true, linenostart=1, hl_lines=["54-60"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-transform +spec: + name: httpbin-transform + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin-transform + 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: + transform: + - method: POST + path: /anything + template_data: + enable_session: false + input_type: json + template_mode: blob + # base64 encoded template + template_source: eyJiYXIiOiAie3suZm9vfX0ifQ== + transform_headers: + - delete_headers: + - "remove_this" + add_headers: + foo: bar + path: /anything + method: POST + transform_response: + - method: GET + path: /xml + template_data: + enable_session: false + input_type: xml + template_mode: blob + # base64 encoded template + template_source: e3sgLiB8IGpzb25NYXJzaGFsIH19 + transform_response_headers: + - method: GET + path: /xml + add_headers: + Content-Type: "application/json" + act_on: false + delete_headers: [] +``` + +##### Tyk Gateway < 5.3.0 Example + +If using Tyk Gateway < v5.3.0 then a `response_processor` object must be added to the API definition containing a `header_injector` item, as highlighted below: + +```yaml {linenos=true, linenostart=1, hl_lines=["17", "19", "57-63"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-transform +spec: + name: httpbin-transform + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin-transform + strip_listen_path: true + response_processors: + - name: response_body_transform + - name: header_injector + version_data: + default_version: Default + not_versioned: true + versions: + Default: + name: Default + use_extended_paths: true + paths: + black_list: [] + ignored: [] + white_list: [] + extended_paths: + transform: + - method: POST + path: /anything + template_data: + enable_session: false + input_type: json + template_mode: blob + # base64 encoded template + template_source: eyJiYXIiOiAie3suZm9vfX0ifQ== + transform_headers: + - delete_headers: + - "remove_this" + add_headers: + foo: bar + path: /anything + method: POST + transform_response: + - method: GET + path: /xml + template_data: + enable_session: false + input_type: xml + template_mode: blob + # base64 encoded template + template_source: e3sgLiB8IGpzb25NYXJzaGFsIH19 + transform_response_headers: + - method: GET + path: /xml + add_headers: + Content-Type: "application/json" + act_on: false + delete_headers: [] +``` diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/url-rewrite-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/url-rewrite-tyk-classic.md index 50825b4bba..797c10fd50 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/url-rewrite-tyk-classic.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/url-rewrite-tyk-classic.md @@ -15,7 +15,9 @@ If you want to use dynamic data from context variables, you must [enable]({{< re If you're using the newer Tyk OAS APIs, then check out [this]({{< ref "/product-stack/tyk-gateway/middleware/url-rewrite-tyk-oas" >}}) page. -## Configuring the URL rewriter in the Tyk Classic API Definition +If you're using Tyk Operator then check out the [configuring the URL rewriter in Tyk Operator](#tyk-operator) section below. + +## Configuring the URL rewriter in the Tyk Classic API Definition {#tyk-classic} To configure the URL rewriter you must add a new `url_rewrites` object to the `extended_paths` section of your API definition, for example: @@ -32,7 +34,7 @@ To configure the URL rewriter you must add a new `url_rewrites` object to the `e } ``` -In this example the basic trigger has been configured to match the path for arequest to the `GET /books/author` endpoint against the pure regex `(\w+)/(\w+)`. This is looking for two word groups in the path which, if found, will store the first string (`books`) in context variable `$1` and the second (`author`) in `$2`. The request (target) URL will then be rewritten to `library/service?value1=books&value2=author` ready for processing by the next middleware in the chain. +In this example the basic trigger has been configured to match the path for a request to the `GET /books/author` endpoint against the pure regex `(\w+)/(\w+)`. This is looking for two word groups in the path which, if found, will store the first string (`books`) in context variable `$1` and the second (`author`) in `$2`. The request (target) URL will then be rewritten to `library/service?value1=books&value2=author` ready for processing by the next middleware in the chain. You can add advanced triggers to your URL rewriter configuration by adding the `triggers` element within the `url_rewrites` object. @@ -161,3 +163,98 @@ When triggers are added, you can edit or remove them inside the **Advanced URL r Use the *save* or *create* buttons to save the changes and activate the middleware. +## Configuring the URL rewriter in Tyk Operator {#tyk-operator} + +The process for configuring the URL rewriter in Tyk Operator is similar to that explained in [configuring the URL rewriter in the Tyk Classic API Definition](#tyk-classic). To configure the URL rewriter you must add a new `url_rewrites` object to the `extended_paths` section of your API definition. + +The example API Definition provides the corresponding custom resource configuration for the [Tyk Classic API Definition example](#tyk-classic), configuring an API to listen on path `/url-rewrite` and forward requests upstream to http://httpbin.org. The URL rewrites middleware would match the path for a request to the `GET /anything/books/author` endpoint against the pure regex `/anything/(\w+)/(\w+)`. The request (target) URL will then be rewritten to `/anything/library/service?value1=$1&value2=$2`. + +```yaml {linenos=true, linenostart=1, hl_lines=["26-31"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: url-rewrite +spec: + name: URL Rewrite + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /url-rewrite + 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: + url_rewrites: + - path: /anything/books/author + match_pattern: /anything/(\w+)/(\w+) + method: GET + rewrite_to: /anything/library/service?value1=$1&value2=$2 + triggers: [] +``` + +URL Rewrite Triggers can be specified in a similar way. The Tyk Operator example below is the equivalent for the advanced triggers example included in the [configuring the URL rewriter in the Tyk Classic API Definition](#tyk-classic) section above. + +```yaml {linenos=true, linenostart=1, hl_lines=["26-49"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: url-rewrite-advanced +spec: + name: URL Rewrite Advanced + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /url-rewrite + 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: + url_rewrites: + - path: /anything/books/author + match_pattern: /anything/(\w+)/(\w+) + method: GET + rewrite_to: /anything/library/service?value1=$1&value2=$2 + triggers: + - "on": "any" + "rewrite_to": "library/service/author?genre=$tyk_context.trigger-0-genre-0" + "options": + "query_val_matches": + "genre": + "match_rx": "fiction" + "reverse": false + - "on": "all" + "options": + "header_matches": + "X-Enable-Beta": + "match_rx": "true" + "reverse": false + "session_meta_matches": + "beta_enabled": + "match_rx": "true" + "reverse": false + "rewrite_to": "https://beta.library.com/books/author" +``` + +For further examples check out the [internal looping]({{< ref "/product-stack/tyk-operator/advanced-configurations/internal-looping" >}}) page. diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/validate-request-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/validate-request-tyk-classic.md index a713e895b4..c9e7885b98 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/validate-request-tyk-classic.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/validate-request-tyk-classic.md @@ -15,7 +15,9 @@ This middleware is configured in the Tyk Classic API Definition. You can do this If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/validate-request-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} To enable the middleware you must add a new `validate_json` object to the `extended_paths` section of your API definition. @@ -83,3 +85,56 @@ Once you have selected the request validation middleware for the endpoint, you c #### Step 3: 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). To configure the request validation middleware you must add a new `validate_json` object to the `extended_paths` section of your API definition, for example: + +The example API Definition below configures an API to listen on path `/httpbin` and forwards requests upstream to http://httpbin.org. + +In this example, the Validate JSON middleware has been configured for requests to the `GET /get` endpoint. For any call made to this endpoint, Tyk will compare the request body with the schema and, if it does not match, the request will be rejected with the error code `HTTP 422 Unprocessable Entity`. + +```yaml {linenos=true, linenostart=1, hl_lines=["26-41"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-json-schema-validation +spec: + name: httpbin-json-schema-validation + 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: + validate_json: + - error_response_code: 422 + disabled: false + path: /get + method: GET + schema: + properties: + userName: + type: string + minLength: 2 + age: + type: integer + minimum: 1 + required: + - userName + type: object +``` + diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/virtual-endpoint-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/virtual-endpoint-tyk-classic.md index 65b4e8469f..7cbf8d7b6b 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/virtual-endpoint-tyk-classic.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/virtual-endpoint-tyk-classic.md @@ -16,7 +16,9 @@ This middleware is configured in the Tyk Classic API Definition. You can do this If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/virtual-endpoint-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} If you want to use Virtual Endpoints, you must [enable Tyk's JavaScript Virtual Machine]({{< ref "tyk-oss-gateway/configuration#enable_jsvm" >}}) by setting `enable_jsvm` to `true` in your `tyk.conf` file. @@ -126,3 +128,97 @@ Use the *save* or *create* buttons to save the changes and activate the Virtual The Tyk Classic API Designer does not provide options to configure `use_session` or `proxy_on_error`, but you can do this from the Raw Definition editor. {{< /note >}} + +## Configuring the middleware in Tyk Operator {#tyk-operator} + +The process for configuring a virtual endpoint using Tyk Operator is similar to that explained in [configuring the middleware in the Tyk Classic API Definition](#tyk-classic) + +The example API Definition below configures an API to listen on path `/httpbin` and forwards requests upstream to `http://httpbin.org`. The Virtual Endpoint middleware has been configured for requests to the `GET /virtual` endpoint. For any call made to this endpoint, Tyk will invoke the function `myVirtualHandler` that is base64 encoded in the `function_source_uri` field. This virtual endpoint does not require access to the session data and will not proxy the request on to the upstream if there is an error when processing the `myVirtualHandler` function. + +```yaml {linenos=true, linenostart=1, hl_lines=["23-35"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: test-config-data-test +spec: + name: test-config-data-test + protocol: http + proxy: + listen_path: /httpbin/ + target_url: http://httpbin.org + strip_listen_path: true + active: true + use_keyless: true + enable_context_vars: true + version_data: + default_version: Default + not_versioned: false + versions: + Default: + name: Default + use_extended_paths: true + extended_paths: + virtual: + - function_source_type: blob + response_function_name: myVirtualHandler + function_source_uri: "ZnVuY3Rpb24gbXlWaXJ0dWFsSGFuZGxlciAocmVxdWVzdCwgc2Vzc2lvbiwgY29uZmlnKSB7ICAgICAgCiAgdmFyIHJlc3BvbnNlT2JqZWN0ID0gewogICAgQm9keTogIlRISVMgSVMgQSAgVklSVFVBTCBSRVNQT05TRSIsCiAgICBIZWFkZXJzOiB7CiAgICAgICJmb28taGVhZGVyIjogImJhciIsCiAgICAgICJtYXAtaGVhZGVyIjogSlNPTi5zdHJpbmdpZnkoY29uZmlnLmNvbmZpZ19kYXRhLm1hcCksCiAgICAgICJzdHJpbmctaGVhZGVyIjogY29uZmlnLmNvbmZpZ19kYXRhLnN0cmluZywKICAgICAgIm51bS1oZWFkZXIiOiBKU09OLnN0cmluZ2lmeShjb25maWcuY29uZmlnX2RhdGEubnVtKQogICAgfSwKICAgICAgQ29kZTogMjAwCiAgfQogIHJldHVybiBUeWtKc1Jlc3BvbnNlKHJlc3BvbnNlT2JqZWN0LCBzZXNzaW9uLm1ldGFfZGF0YSkKfQ==" + path: /virtual + method: GET + use_session: false + proxy_on_error: false + config_data: + string: "string" + map: + key: 3 + num: 4 +``` + +Decoding the value in `function_source_uri` we can see that the JavaScript code is: + +```javascript +function myVirtualHandler (request, session, config) { + var responseObject = { + Body: "THIS IS A VIRTUAL RESPONSE", + Headers: { + "foo-header": "bar", + "map-header": JSON.stringify(config.config_data.map), + "string-header": config.config_data.string, + "num-header": JSON.stringify(config.config_data.num) + }, + Code: 200 + } + return TykJsResponse(responseObject, session.meta_data) +} +``` + +This function will terminate the request without proxying it to the upstream, returning HTTP 200 as follows: + +```bash +HTTP/1.1 200 OK +Date: Wed, 14 Aug 2024 15:37:46 GMT +Foo-Header: bar +Map-Header: {"key":3} +Num-Header: 4 +Server: tyk +String-Header: string +Content-Length: 27 +Content-Type: text/plain; charset=utf-8 + +THIS IS A VIRTUAL RESPONSE +``` + +If, however, we introduce an error to the JavaScript, such that Tyk fails to process the function, we will receive an HTTP 500 Internal Server Error as follows: + +```bash +HTTP/1.1 500 Internal Server Error +Date: Wed, 14 Aug 2024 15:37:46 GMT +Server: tyk +Content-Type: application/json +Content-Length: 99 + +{ +"error": "Error during virtual endpoint execution. Contact Administrator for more details." +} +``` + +If we set `proxy_on_error` to `true` and keep the error in the Javascript, the request will be forwarded to the upstream and Tyk will return the response received from that service. diff --git a/tyk-docs/content/product-stack/tyk-operator/advanced-configurations/client-authentication.md b/tyk-docs/content/product-stack/tyk-operator/advanced-configurations/client-authentication.md new file mode 100644 index 0000000000..3f37be2bf5 --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-operator/advanced-configurations/client-authentication.md @@ -0,0 +1,392 @@ +--- +title: "Authentication examples" +date: 2024-06-25 +tags: ["Tyk", "Kubernetes", "API Management", "CRD", "DevOps", "API Gateway Configuration"] +description: "This documentation provides a comprehensive guide on configuring API versioning within the ApiDefinition Custom Resource Definition (CRD)." +keywords: ["Tyk Operator", "Kubernetes", "API Versioning"] +--- + +Client to Gateway Authentication in Tyk ensures secure communication between clients and the Tyk Gateway. Tyk supports various authentication methods to authenticate and authorize clients before they can access your APIs. These methods include API keys, Static Bearer Tokens, JWT, mTLS, Basic Authentication, and more. This document provides example manifests for each authentication method supported by Tyk. + +## Keyless (Open) + +This configuration allows [keyless (open)]({{}}) access to the API without any authentication. + +```yaml {hl_lines=["7-7"],linenos=false} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-keyless +spec: + name: httpbin-keyless + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin + strip_listen_path: true +``` + +## Auth Token (Bearer Token) + +This setup requires a [bearer token]({{}}) for access. + +In the below example, the authentication token is set by default to the `Authorization` header of the request. You can customize this behavior by configuring the following fields: + +- `use_cookie`: Set to true to use a cookie value for the token. +- `cookie_name`: Specify the name of the cookie if use_cookie is enabled. +- `use_param`: Set to true to allow the token to be passed as a query parameter. +- `param_name`: Specify the parameter name if use_param is enabled. +- `use_certificate`: Enable client certificate. This allows you to create dynamic keys based on certificates. +- `validate_signature`: Enable [signature validation]({{}}). + +```yaml {hl_lines=["13-35"],linenos=false} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-auth-token +spec: + name: httpbin-auth-token + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin + strip_listen_path: true + use_standard_auth: true + auth_configs: + authToken: + # Auth Key Header Name + auth_header_name: Authorization + # Use cookie value + use_cookie: false + # Cookie name + cookie_name: "" + # Allow query parameter as well as header + use_param: false + # Parameter name + param_name: "" + # Enable client certificate + use_certificate: false + # Enable Signature validation + validate_signature: false + signature: + algorithm: "" + header: "" + secret: "" + allowed_clock_skew: 0 + error_code: 0 +``` + +## JWT + +This configuration uses [JWT tokens]({{}}) for authentication. + +Users can configure JWT authentication by defining the following fields: + +- `jwt_signing_method`: Specify the method used to sign the JWT. Refer to [JWT Signing Method]({{}}) for supported methods. +- `jwt_source`: Specify the public key used for verifying the JWT. +- `jwt_identity_base_field`: Define the identity source, typically set to `sub` (subject), which uniquely identifies the user or entity. +- `jwt_policy_field_name`: Specify the claim within the JWT payload that indicates the policy ID to apply. +- `jwt_default_policies` (Optional): Define default policies to apply if no policy claim is found in the JWT payload. + +The following example configures an API to use JWT authentication. It specifies the ECDSA signing method and public key, sets the `sub` claim as the identity source, uses the `pol` claim for policy ID, and assigns a default policy (`jwt-policy` SecurityPolicy in `default` namespace) if no policy is specified in the token. + +```yaml {hl_lines=["13-22"],linenos=false} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-jwt1 +spec: + name: httpbin-jwt1 + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin-jwt1 + strip_listen_path: true + enable_jwt: true + strip_auth_data: true + jwt_signing_method: ecdsa + # ecdsa pvt: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JR0hBZ0VBTUJNR0J5cUdTTTQ5QWdFR0NDcUdTTTQ5QXdFSEJHMHdhd0lCQVFRZ2V2WnpMMWdkQUZyODhoYjIKT0YvMk54QXBKQ3pHQ0VEZGZTcDZWUU8zMGh5aFJBTkNBQVFSV3oram42NUJ0T012ZHlIS2N2akJlQlNEWkgycgoxUlR3am1ZU2k5Ui96cEJudVE0RWlNbkNxZk1QV2lacUI0UWRiQWQwRTdvSDUwVnB1WjFQMDg3RwotLS0tLUVORCBQUklWQVRFIEtFWS0tLS0t + # ecdsa pub: LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFRVZzL281K3VRYlRqTDNjaHluTDR3WGdVZzJSOQpxOVVVOEk1bUVvdlVmODZRWjdrT0JJakp3cW56RDFvbWFnZUVIV3dIZEJPNkIrZEZhYm1kVDlQT3hnPT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0t + jwt_source: LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFRVZzL281K3VRYlRqTDNjaHluTDR3WGdVZzJSOQpxOVVVOEk1bUVvdlVmODZRWjdrT0JJakp3cW56RDFvbWFnZUVIV3dIZEJPNkIrZEZhYm1kVDlQT3hnPT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0t + jwt_identity_base_field: sub + jwt_policy_field_name: pol + jwt_default_policies: + - default/jwt-policy +--- +apiVersion: tyk.tyk.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: jwt-policy +spec: + access_rights_array: + - name: httpbin-jwt1 + namespace: default + versions: + - Default + active: true + name: jwt-policy + state: active +``` + +You can verify the API is properly authenticated with following command: + +1. JWT with default policy +```bash +curl http://localhost:8080/httpbin-jwt1/get -H 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0ZXN0IiwiaWF0IjoxNTE2MjM5MDIyfQ.rgPyrCJYs2im7zG6im5XUqsf_oAf_Kqk-F6IlLb3yzZCSZvrQObhBnkLKgfmVTbhQ5El7Q6KskXPal5-eZFuTQ' +{ + "args": {}, + "headers": { + "Accept": "*/*", + "Accept-Encoding": "gzip", + "Host": "httpbin.org", + "Traceparent": "00-d2b93d763ca27f29181c8e508b5ac0c9-a446afa3bd053617-01", + "User-Agent": "curl/8.6.0", + "X-Amzn-Trace-Id": "Root=1-6696f0bf-1d9e532c6a2eb3a709e7086b" + }, + "origin": "127.0.0.1, 178.128.43.98", + "url": "http://httpbin.org/get" +} +``` + +2. JWT with explicit policy +```bash +curl http://localhost:8080/httpbin-jwt1/get -H 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0ZXN0IiwiaWF0IjoxNTE2MjM5MDIyLCJwb2wiOiJaR1ZtWVhWc2RDOXFkM1F0Y0c5c2FXTjUifQ.7nY9TvYgsAZqIHLhJdUPqZtzqU_5T-dcNtCt4zt8YPyUj893Z_NopL6Q8PlF8TlMdxUq1Ff8rt4-p8gVboIqlA' +{ + "args": {}, + "headers": { + "Accept": "*/*", + "Accept-Encoding": "gzip", + "Host": "httpbin.org", + "Traceparent": "00-002adf6632ec20377cb7ccf6c3037e78-3c4cb97c70d790cb-01", + "User-Agent": "curl/8.6.0", + "X-Amzn-Trace-Id": "Root=1-6696f1dd-7f9de5f947c8c73279f7cca6" + }, + "origin": "127.0.0.1, 178.128.43.98", + "url": "http://httpbin.org/get" +} +``` + +## Client mTLS + +This setup requires mutual TLS (mTLS) for client authentication using specified client certificates. The example provided shows how to create an API definition with mTLS authentication for `httpbin-client-mtls`. + +1. **Generate Self-Signed Key Pair:** + +You can generate a self-signed key pair using the following OpenSSL command: + +```bash +openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes +``` + +2. **Create Kubernetes Secret:** + +Create a secret in Kubernetes to store the client certificate: + +```bash +kubectl create secret tls my-test-tls --cert cert.pem --key key.pem +``` + +3. **Create API Definition:** + +Below is the YAML configuration for an API that uses mTLS authentication. Note that the `client_certificate_refs` field references the Kubernetes secret created in the previous step. + +```yaml {hl_lines=["19-21"],linenos=false} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-client-mtls +spec: + name: Httpbin Client MTLS + 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_mutual_tls_auth: true + client_certificate_refs: + - my-test-tls +``` + +## Basic Authentication + +This configuration uses [Basic Authentication]({{}}), requiring a username and password for access. + +```yaml {hl_lines=["13-13"],linenos=false} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-basic-auth +spec: + name: Httpbin Basic Authentication + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin + strip_listen_path: true + use_basic_auth: true +``` + +## Custom Plugin Auth (go) + +This configuration uses a [Golang plugin]({{}}) for custom authentication. The following example shows how to create an API definition with a Golang custom plugin for `httpbin-go-auth`. + +For an example of Golang authentication middleware, see [Performing custom authentication with a Golang plugin]({{}}). + +```yaml {hl_lines=["7-7", "14-21"],linenos=false} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-go-auth +spec: + name: httpbin-go-auth + use_go_plugin_auth: true # Turn on GO auth + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin + strip_listen_path: true + custom_middleware: + driver: goplugin + pre: + - name: "AddFooBarHeader" + path: "/mnt/tyk-gateway/example-go-plugin.so" + auth_check: + name: "MyPluginCustomAuthCheck" + path: "/mnt/tyk-gateway/example-go-plugin.so" +``` + +## Custom Plugin Auth (gRPC) + +This configuration uses a [gRPC plugin]({{}}) for custom authentication. The following example shows how to create an API definition with a gRPC custom plugin for `httpbin-grpc-auth`. + +For a detailed walkthrough on setting up Tyk with gRPC authentication plugins, refer to [Extending Tyk with gRPC Authentication Plugins](https://tyk.io/blog/how-to-setup-custom-authentication-middleware-using-grpc-and-java/). + +```yaml {hl_lines=["9-9", "14-26"],linenos=false} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-grpc-auth +spec: + name: httpbin-grpc-auth + protocol: http + active: true + enable_coprocess_auth: true + proxy: + target_url: http://httpbin.default.svc:8000 + listen_path: /httpbin-grpc-auth + strip_listen_path: true + custom_middleware: + driver: grpc + post_key_auth: + - name: "HelloFromPostKeyAuth" + path: "" + auth_check: + name: foo + path: "" + id_extractor: + extract_from: header + extract_with: value + extractor_config: + header_name: Authorization +``` + +## Multiple (Chained) Auth + +This setup allows for [multiple authentication]({{}}) methods to be chained together, requiring clients to pass through each specified authentication provider. + +To enable multiple (chained) auth, you should set `base_identity_provided_by` field to one of the supported chained enums. Consult [Enable Multi (Chained) Authentication in your API Definition]({{}}) for the supported auths. + +In this example, we are creating an API definition with basic authentication and mTLS with basic authentication as base identity for `httpbin-multiple-authentications`. + +```yaml {hl_lines=["19-21"],linenos=false} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-multiple-authentications +spec: + name: Httpbin Multiple Authentications + 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 + base_identity_provided_by: basic_auth_user + use_basic_auth: true + use_mutual_tls_auth: true +``` + +## IP Allowlist + +To enable [IP Allowlist]({{}}), set the following fields: + +* `enable_ip_whitelisting`: Enables IPs allowlist. When set to `true`, only requests coming from the explicit list of IP addresses defined in (`allowed_ips`) are allowed through. +* `allowed_ips`: A list of strings that defines the IP addresses (in [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation) notation) that are allowed access via Tyk. + +In this example, only requests coming from 127.0.0.2 is allowed. + +```yaml {hl_lines=["10-12"],linenos=false} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin +spec: + name: httpbin + use_keyless: true + protocol: http + active: true + enable_ip_whitelisting: true + allowed_ips: + - 127.0.0.2 + proxy: + target_url: http://httpbin.default.svc:8000 + listen_path: /httpbin + strip_listen_path: true +``` + +## IP Blocklist + +To enable [IP Blocklist]({{}}), set the following fields: + +* `enable_ip_blacklisting`: Enables IPs blocklist. If set to `true`, requests coming from the explicit list of IP addresses (blacklisted_ips) are not allowed through. +* `blacklisted_ips`: A list of strings that defines the IP addresses (in [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation) notation) that are blocked access via Tyk. This list is explicit and wildcards are currently not supported. + +In this example, requests coming from 127.0.0.2 will be forbidden (`403`). + +```yaml {hl_lines=["10-12"],linenos=false} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin +spec: + name: httpbin + use_keyless: true + protocol: http + active: true + enable_ip_blacklisting: true + blacklisted_ips: + - 127.0.0.2 + proxy: + target_url: http://httpbin.default.svc:8000 + listen_path: /httpbin + strip_listen_path: true +``` \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-operator/advanced-configurations/custom-plugins.md b/tyk-docs/content/product-stack/tyk-operator/advanced-configurations/custom-plugins.md new file mode 100644 index 0000000000..87e8ff13de --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-operator/advanced-configurations/custom-plugins.md @@ -0,0 +1,204 @@ +--- +title: "Custom Plugins" +date: 2024-08-07 +tags: ["Tyk", "Kubernetes", "Plugins", "Javascript Plugins", "API Gateway Configuration"] +description: "This documentation explains how to configure plugins using Tyk Operator" +keywords: [ "Tyk Operator", "custom plugins", "plugins" ] +--- + +This guide explains how to configure one or more custom plugins where the source code and associated configuration is co-located on Tyk Gateway’s file system. The process is similar to that for configuring the API Definition of a Tyk Classic API to use custom plugins. + +--- + +## Overview + +Using Tyk Classic APIs, developers can implement API-level custom plugins that can be optionally setup to execute for each of the following [hooks]({{< ref "plugins/plugin-types/plugintypes#plugin-and-hook-types" >}}) in the API request lifecycle: [Pre (Request)]({{< ref "plugins/plugin-types/request-plugins" >}}), [Authentication]({{< ref "plugins/plugin-types/auth-plugins/auth-plugins" >}}), [Post (Request)]({{< ref "plugins/plugin-types/request-plugins" >}}), [Post Authentication]({{< ref "plugins/plugin-types/request-plugins" >}}), [Response]({{< ref "plugins/plugin-types/response-plugins" >}}) and [Analytics]({{< ref "plugins/plugin-types/analytics-plugins" >}}). Subsequently, users can execute, or “hook”, their plugin into these phases of the API request lifecycle based on their specific use case. + +This document explains how to configure the following plugin types with different drivers (plugin languages): +- Pre (Request) +- Authentication +- Post-Auth (Request) +- Post (Request) +- Response + +Please refer to [Analytics Plugins]({{< ref "plugins/plugin-types/analytics-plugins" >}}) to learn how to configure Analytics plugins using Tyk Operator. + +--- + +## How It Works {#tyk-classic} + +In Tyk Classic APIs, the *custom_middleware* section of the Tyk Classic API Definition is where you configure plugins that will run at different points during the lifecycle of an API request. + +The table below illustrates the Tyk Classic API configuration parameters that correspond to each phase of the API request lifecycle: + +| Phase | Description | Config Value | +| ----- | --- | ---- | +| Pre | Occurs before main request processing. | pre | +| Auth | Custom authentication can be handled during this phase. | auth_check | +| Post Auth | Occurs after key authentication | post_key_auth | +| Post | Occurs after the main request processing but before the response is sent. | post | +| Response | Occurs after the main request processing but before the response is sent. | response | + +The example configuration below illustrates how to set up multiple plugins for different phases of the request lifecycle: + +```json {linenos=true, linenostart=1} +{ + "custom_middleware": { + "pre": [ + { + "name": "PreHook1", + "path": "/path/to/plugin1.so", + "require_session": false, + "raw_body_only": false + } + ], + "auth_check": { + "name": "AuthCheck", + "path": "/path/to/plugin.so", + "require_session": false, + "raw_body_only": false + }, + "post_key_auth": [ + { + "name": "PostKeyAuth", + "path": "/path/to/plugin.so", + "require_session": false, + "raw_body_only": false + } + ], + "post": [ + { + "name": "PostHook1", + "path": "/path/to/plugin1.so", + "require_session": false, + "raw_body_only": false + }, + { + "name": "PostHook2", + "path": "/path/to/plugin2.so", + "require_session": false, + "raw_body_only": false + } + ], + "response": [ + { + "name": "ResponseHook", + "path": "/path/to/plugin.so", + "require_session": false, + "raw_body_only": false + } + ], + "driver": "goplugin" + } +} +``` + +In the `custom_middleware` section of the API definition above we can see that there are Golang custom authentication (`auth_check`), post authentication (`post_key_auth`), post, pre and response plugins configured. + +It can be seen that each plugin is configured with the specific function name and associated source file path of the file that contains the function. Furthermore, each lifecycle phase can have a list of plugins configured, allowing for complex processing workflows. For example, you might develop one plugin for logging and another for modifying the request in the pre request phase. + +The `driver` configuration parameter describes the plugin implementation language. Please refer to the [supported languages]({{< ref "/plugins/supported-languages#plugin-driver-names" >}}) section for list of supported plugin driver names. + +Each plugin can have additional settings, such as: +- `raw_body_only`: When true, indicates that only the raw body should be processed. +- `require_session`: When true, indicates that session metadata will be available to the plugin. This is applicable only for post, post authentication and response plugins. + +### Unsupported + +##### Per-Endpoint Plugins + +At the endpoint-level, Tyk provides the facility to attach a custom Golang plugin at the end of the request processing chain (immediately before the API-level post-plugin is executed). Please note that [per-endpoint]({{< ref "product-stack/tyk-gateway/middleware/endpoint-plugin" >}}) level plugins are not currently supported by Tyk Operator. + +### Undocumented + +##### Plugin Bundles + +Tyk Operator also supports configuring custom plugins using plugin bundles, where the source code and associated configuration is packaged into a zip file and uploaded to a remote webserver. Tyk Gateway will then download, extract, cache and execute the plugin bundles for each of the configured phases of the [API request lifecycle]({{< ref "concepts/middleware-execution-order" >}}). + +Currently, there are no examples documented for configuring plugin bundles with Tyk Operator. Please refer to [plugin bundles]({{< ref "plugins/how-to-serve-plugins/plugin-bundles" >}}) for further details of the equivalent Tyk Classic API configuration or reach out on the [community forum](https://community.tyk.io). + +--- + +## Example: Configure Custom Plugins (JavaScript) With Tyk Operator + +In this example we will create a JavaScript plugin that will inject a request header *Hello* with a value of *World*. This will be configured as a pre request [hook]({{< ref "" >}}). + +### 1. Implement Plugin + +The first step is to create the plugin source code. + +```javascript +var exampleJavaScriptMiddlewarePreHook = new TykJS.TykMiddleware.NewMiddleware({}); + +exampleJavaScriptMiddlewarePreHook.NewProcessRequest(function(request, session) { + // You can log to Tyk console output by calling the built-in log() function: + log("Hello from the Tyk JavaScript middleware pre hook function") + + // Add a request header + request.SetHeaders["Hello"] = "World"; + + // You must return both the request and session metadata + return exampleJavaScriptMiddlewarePreHook.ReturnData(request, {} ); +}); +``` + +Copy the source code above and save it to the following file on the Gateway file system at `/opt/tyk-gateway/middleware/example-javascript-middleware.js` + + +### 2. Create API Definition Resource + +The example API Definition resource listed below listens on path */httpbin* and forwards requests to upstream *http://httpbin.org*. + +```yaml {linenos=table,hl_lines=["14-18"],linenostart=1} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin +spec: + name: httpbin + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin + strip_listen_path: true + custom_middleware: + driver: otto # Javascript driver name + pre: + - name: "exampleJavaScriptMiddlewarePreHook" + path: "middleware/example-javascript-middleware.js" +``` + +At lines 14-18 we can see the *custom_middleware* section contains the configuration for our plugin: + +- The `driver` configuration parameter is set to `otto` at line 15, since our plugin is a Javascript plugin. For other valid values please refer to the [plugins driver page]({{< ref "plugins/supported-languages#plugin-driver-names" >}}). +- A plugin hook configuration block is specified at line 16, containing the `name` and `path` for our plugin. The plugin configuration block identifies the "hook" or phase in the API request lifecycle when Tyk Gateway will execute the plugin. In the example above the configuration block is for a `pre` request plugin that will be executed before any middleware. Valid values are the same as the [Tyk Classic API Definition]({{< ref "#tyk-classic" >}}) equivalent, i.e. `pre`, `auth_check`, `post`, `post-auth` and `response`. We can see that the following fields are set within the `pre` plugin hook configuration object: + + - The `name` field represents the name of the function that implements the plugin in your source code. For Javascript plugins this must match the name of the middleware object that was created. In the example above we created the middleware object, `exampleJavaScriptMiddlewarePreHook`, by calling `var exampleJavaScriptMiddlewarePreHook = new TykJS.TykMiddleware.NewMiddleware({});`. + - The `path` field contains the path to the source file `middleware/example-javascript-middleware.js`, relative to the base installation folder, i.e `/opt/tyk-gateway`. + +Save the API Definition to file and create the APIDefinition resource: + +```bash +$ kubectl apply -f path_to_your_apidefinition.yaml +apidefinition.tyk.tyk.io/httpbin created +``` + +### 3. Test Plugin + +We can test that our plugin injects a *Hello* header with a corresponding value of *World* by using the curl command: + +```bash +$ curl http://localhost:8080/httpbin/headers + { + "headers": { + "Accept": "*/*", + "Accept-Encoding": "gzip", + "Hello": "World", + "Host": "httpbin.org" + } + } +``` + +The header `"Hello: World"` should be injected by the custom plugin. diff --git a/tyk-docs/content/product-stack/tyk-operator/advanced-configurations/graphql-federation.md b/tyk-docs/content/product-stack/tyk-operator/advanced-configurations/graphql-federation.md new file mode 100644 index 0000000000..2266fdb982 --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-operator/advanced-configurations/graphql-federation.md @@ -0,0 +1,570 @@ +--- +title: "GraphQL Federation with Tyk Operator" +date: 2024-06-25 +tags: ["Tyk Operator", "GraphQL Federation", "Kubernetes"] +description: "" +--- + +Tyk, with release *v4.0* offers [GraphQL federation]({{}}) that allows you to divide GraphQL implementation across multiple back-end +services, while still exposing them all as a single graph for the consumers. + +Tyk Operator supports GraphQL Federation subgraph and supergraph with following Custom Resources. + +## Custom Resources + +GraphQL Federation uses concepts of Subgraph and Supergraph. + +**Subgraph** is a representation of a back-end service and defines a distinct GraphQL schema. It can be queried directly as a separate service or it can be federated into a larger schema of a supergraph. + +**Supergraph** is a composition of several subgraphs that allows the execution of a query across multiple services in the backend. + +Tyk Operator uses Custom Resources called [SubGraph](#subgraph) and [SuperGraph](#supergraph), that allows users to model the relationship between Subgraphs and Supergraphs. + +### SubGraph + +```yaml +apiVersion: tyk.tyk.io/v1alpha1 +kind: SubGraph +metadata: + name: users-subgraph +spec: + schema: | + + sdl: | + +``` + +SubGraph Custom Resource Definitions (CRD) takes `schema` and `sdl` values for your subgraph. + +To create a Subgraph API in Tyk, you can reference the subgraph's metadata name through `graphql.graph_ref` field, as follows: + +```yaml +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: subgraph-api +spec: + name: Federation - Subgraph + ... + graphql: + enabled: true + execution_mode: subgraph + graph_ref: users-subgraph ## corresponds to Subgraph resource's metadata name + version: "2" + playground: + enabled: false + path: "" + proxy: + target_url: http://users.default.svc:4001/query + listen_path: /users-subgraph/ + disable_strip_slash: true +``` + +An ApiDefinition must adhere to the following rules in order to represent an ApiDefinition for your SubGraph CRDs. + +1. ApiDefinition and SubGraph must be in the same namespace, +2. `graphql.execution_mode` must be set to `subgraph`, +3. `graphql.graph_ref` must be set to the metdata name of the SubGraph resource that you would like to refer. + +### SuperGraph + +```yaml +apiVersion: tyk.tyk.io/v1alpha1 +kind: SuperGraph +metadata: + name: social-media-supergraph +spec: + subgraph_refs: + - name: users-subgraph + namespace: default + schema: |- + +``` + +SuperGraph CRD takes `subgraph_refs` and `schema` values for your supergraph. `subgraph_refs` is an array of SubGraph Custom Resource(CR) references which expects the name and namespace of the referenced subgraph. If `namespace` is not specified, Operator will check SubGraphs in the current namespace. + +Tyk Operator will update your SuperGraph ApiDefinition when one of the subgraphs that you reference in `subgraph_refs` changes. + +To create a SuperGraph API in Tyk, you can reference the supergraph's metadata name through `graphql.graph_ref field`, as follows: + +```yaml +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: federation-supergraph +spec: + name: Federated - Social Media APIS + ... + graphql: + execution_mode: supergraph + graph_ref: social-media-supergraph ## corresponds to SuperGraph resource's metadata name + enabled: true + version: "2" + playground: + enabled: true + path: /playground + proxy: + target_url: "" + strip_listen_path: true + listen_path: /social-media-apis-federated/ +``` + +An ApiDefinition must adhere to the following rules in order to represent an ApiDefinition for your SuperGraph CRDs. + +1. ApiDefinition and SuperGraph must be in the same namespace, +2. `graphql.execution_mode` must be set to `supergraph`, +3. `graphql.graph_ref` must be set to the metdata name of the SuperGraph resource that you would like to refer. + +## Propagating updates from Subgraph CRD to Subgraph API and Supergraph APIs + +Tyk Operator will automatically propagate changes in SubGraph CRD to the corresponding Subgraph ApiDefinition. Also, if the SubGraph is referenced by a SuperGraph, the corresponding SuperGraph CR and corresponding supergraph ApiDefinition will be updated too. + +Therefore, once you make an update on SubGraph CR, you do not need to update your supergraph. It will be updated by Tyk Operator. With this approach, multiple teams can work on SubGraph CRDs and Tyk Operator will update the relevant SuperGraph ApiDefinition. + +### Example + +Let's assume that a developer responsible for the [Users SubGraph](#users-subgraph) would like to delete `username` field from the Users SubGraph. +Also, the [Supergraph](#supergraph-1) called Social Media already uses the Users Subgraph. + +To achieve this, the developer should update the Users SubGraph CRD. Once the SubGraph CRD is updated, Tyk Operator will: +1. Update Users SubGraph CRD, +2. Update Social Media Supergraph ApiDefinition since it is referencing the Users SubGraph CRD. + +## Deleting SubGraph + +### SubGraph without any reference + +If the subgraph is not referenced in any ApiDefinition CRD or SuperGraph CRD, it is easy to delete SubGraph CRDs as follows: +```bash +kubectl delete subgraphs.tyk.tyk.io +``` + +### SubGraph referenced in ApiDefinition + +If you have a subgraph which is referenced in any ApiDefinition, Tyk Operator will not delete the SubGraph. + +In order to delete this subgraph, the corresponding ApiDefinition CR must be updated, such that it has no reference to the +subgraph in `graph_ref` field. + +### SubGraph referenced in SuperGraph + +Although the subgraph is not referenced in any ApiDefinition, if it is referenced in the SuperGraph, Tyk Operator will +not delete the subgraph again. + +In order to delete this subgraph, SuperGraph CR should not have reference to corresponding subgraph in the `subgraph_ref`. + +## Deleting SuperGraph + +### SuperGraph without any reference +If the supergraph is not referenced in any ApiDefinition CRD, it can be deleted as follows: + +```bash +kubectl delete supergraphs.tyk.tyk.io +``` + +### SuperGraph referenced in ApiDefinition +If a supergraph is referenced in any ApiDefinition, the Tyk Operator will not delete the SuperGraph CRD. + +In order to delete this supergraph, the ApiDefinition that has a reference to the supergraph must de-reference the supergraph +or be deleted. + +## Example Manifests + +### Users Subgraph + +```yaml +# Create Namespace & Service & Deployment for Users API +--- +apiVersion: v1 +kind: Namespace +metadata: + name: users-ns +--- +apiVersion: v1 +kind: Service +metadata: + name: users + namespace: users-ns + labels: + app: users +spec: + ports: + - name: http + port: 4201 + targetPort: 4201 + selector: + app: users +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: users + namespace: users-ns +spec: + replicas: 1 + selector: + matchLabels: + app: users + version: v1 + template: + metadata: + labels: + app: users + version: v1 + spec: + containers: + - image: zalbiraw/go-api-test-service:v2.0.0 + imagePullPolicy: Always + name: users + command: ["./services/graphql-subgraphs/users/server"] + env: + - name: PORT + value: "4201" +--- +apiVersion: tyk.tyk.io/v1alpha1 +kind: SubGraph +metadata: + name: users-subgraph + namespace: users-ns +spec: + schema: | + directive @extends on OBJECT | INTERFACE + + directive @external on FIELD_DEFINITION + + directive @key(fields: _FieldSet!) on OBJECT | INTERFACE + + directive @provides(fields: _FieldSet!) on FIELD_DEFINITION + + directive @requires(fields: _FieldSet!) on FIELD_DEFINITION + + scalar _Any + + union _Entity = User + + scalar _FieldSet + + type _Service { + sdl: String + } + + type Address { + street: String! + suite: String! + city: String! + zipcode: String! + geo: GeoLocation! + } + + type Company { + name: String! + catchPhrase: String! + bs: String! + } + + type Entity { + findUserByID(id: ID!): User! + } + + type GeoLocation { + lat: String! + lng: String! + } + + type Query { + user(id: ID!): User! + users: [User!]! + _entities(representations: [_Any!]!): [_Entity]! + _service: _Service! + } + + type User { + id: ID! + name: String! + username: String! + email: String! + address: Address! + phone: String! + website: String! + company: Company! + } + sdl: | + extend type Query { + user(id: ID!): User! + users: [User!]! + } + + type User @key(fields: "id") { + id: ID! + name: String! + username: String! + email: String! + address: Address! + phone: String! + website: String! + company: Company! + } + + type Address { + street: String! + suite: String! + city: String! + zipcode: String! + geo: GeoLocation! + } + + type GeoLocation { + lat: String! + lng: String! + } + + type Company { + name: String! + catchPhrase: String! + bs: String! + } +--- +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: federation-users-subgraph + namespace: users-ns +spec: + name: Federation - Users Subgraph + protocol: "http" + do_not_track: false + use_keyless: true + active: true + internal: true + graphql: + enabled: true + execution_mode: subgraph + graph_ref: users-subgraph + version: "2" + playground: + enabled: false + path: "" + proxy: + target_url: http://users.users-ns.svc:4201/query + listen_path: /users-subgraph/ + disable_strip_slash: true +``` + +### Posts Subgraph + +```yaml +# Create Service & Deployment of Posts API +--- +apiVersion: v1 +kind: Service +metadata: + name: posts + labels: + app: posts +spec: + ports: + - name: http + port: 4202 + targetPort: 4202 + selector: + app: posts +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: posts +spec: + replicas: 1 + selector: + matchLabels: + app: posts + version: v1 + template: + metadata: + labels: + app: posts + version: v1 + spec: + containers: + - image: zalbiraw/go-api-test-service:v2.0.0 + imagePullPolicy: Always + name: posts + command: ["./services/graphql-subgraphs/posts/server"] + env: + - name: PORT + value: "4202" +--- +apiVersion: tyk.tyk.io/v1alpha1 +kind: SubGraph +metadata: + name: posts-subgraph +spec: + schema: | + directive @extends on OBJECT | INTERFACE + + directive @external on FIELD_DEFINITION + + directive @key(fields: _FieldSet!) on OBJECT | INTERFACE + + directive @provides(fields: _FieldSet!) on FIELD_DEFINITION + + directive @requires(fields: _FieldSet!) on FIELD_DEFINITION + + scalar _Any + + union _Entity = Post | User + + scalar _FieldSet + + type _Service { + sdl: String + } + + type Entity { + findPostByID(id: ID!): Post! + findUserByID(id: ID!): User! + } + + type Post { + id: ID! + userId: ID! + title: String! + body: String! + } + + type Query { + post(id: ID!): Post! + posts: [Post!]! + _entities(representations: [_Any!]!): [_Entity]! + _service: _Service! + } + + type User { + id: ID! + posts: [Post!]! + } + sdl: | + extend type Query { + post(id: ID!): Post! + posts: [Post!]! + } + + type Post @key(fields: "id") { + id: ID! + userId: ID! + title: String! + body: String! + } + + extend type User @key(fields: "id") { + id: ID! @external + posts: [Post!]! + } + +--- +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: federation-posts-subgraph +spec: + name: Federation - Posts Subgraph + protocol: "http" + do_not_track: false + use_keyless: true + active: true + internal: true + graphql: + enabled: true + execution_mode: subgraph + graph_ref: posts-subgraph + version: "2" + playground: + enabled: false + path: "" + proxy: + target_url: http://posts.default.svc:4202/query + listen_path: /posts-subgraph/ + disable_strip_slash: true +``` + +### Supergraph + +```yaml +apiVersion: tyk.tyk.io/v1alpha1 +kind: SuperGraph +metadata: + name: social-media-supergraph +spec: + subgraph_refs: + - name: users-subgraph + namespace: users-ns + - name: posts-subgraph # Since namespace is not specified for posts-subgraph, Operator uses the namespace of this SuperGraph CRD which is default for our example. + schema: |- + type Query { + user(id: ID!): User! + users: [User!]! + post(id: ID!): Post! + posts: [Post!]! + } + + type User { + id: ID! + name: String! + username: String! + email: String! + address: Address! + phone: String! + website: String! + company: Company! + posts: [Post!]! + } + + type Address { + street: String! + suite: String! + city: String! + zipcode: String! + geo: GeoLocation! + } + + type GeoLocation { + lat: String! + lng: String! + } + + type Company { + name: String! + catchPhrase: String! + bs: String! + } + + type Post { + id: ID! + userId: ID! + title: String! + body: String! + } +--- +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: federation-supergraph +spec: + name: Federated - Social Media APIS + protocol: "http" + do_not_track: false + use_keyless: true + active: true + graphql: + enabled: true + execution_mode: supergraph + graph_ref: social-media-supergraph + version: "2" + playground: + enabled: true + path: /playground + proxy: + target_url: "" + strip_listen_path: true + listen_path: /social-media-apis-federated/ +``` \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-operator/advanced-configurations/internal-looping.md b/tyk-docs/content/product-stack/tyk-operator/advanced-configurations/internal-looping.md new file mode 100644 index 0000000000..d7c9e49b78 --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-operator/advanced-configurations/internal-looping.md @@ -0,0 +1,339 @@ +--- +title: Internal Looping +date: 2024-08-07 +description: "Using internal looping with Tyk Operator" +tags: ["Internal Looping", "Tyk Operator", "internal looping","per-API", "Tyk Classic"] +--- + +The concept of [internal looping]({{< ref "advanced-configuration/transform-traffic/looping" >}}) allows you to use URL Rewriting to redirect your URL to *another API endpoint* or to *another API* in the Gateway. In Tyk, looping is generally targeted using the `tyk:///` scheme, which requires prior knowledge of the `API_ID`. Tyk Operator simplifies the management and transformation of API traffic within Kubernetes environments by abstracting APIs as objects, managing them and dynamically assigning `API_ID`s by its Kubernetes metedata name and namespace. + +--- + +## Configuring looping to internal ApiDefinition resources + +Looping can be configured within Tyk Operator for [URL Rewrites](#url-rewrites), [URL Rewrite Triggers](#url-rewrite-triggers) and [Proxy to internal APIs](#proxy-to-internal-apis) by configuring the `rewrite_to_internal` in `url_rewrite`, `rewrite_to_internal` in `triggers`, and `proxy.target_internal` fields respectively with these properties: + +- **Path**: The `path` property specifies the endpoint on the target API where the request should be directed. This is the portion of the URL that follows the domain and is crucial for ensuring that the request reaches the correct resource. For example, setting a value of `"/myendpoint"` means that the request will be forwarded to the `/myendpoint` path on the target API. + +- **Query**: The `query` property allows you to append additional query parameters to the target URL. These parameters can be used to modify the behavior of the target API or to pass along specific request information. For instance, setting `query: "check_limits=true"` will include this query string in the redirected request, potentially triggering special handling by the target API. + +- **Target**: The `target` property identifies the API resource to which the request should be routed. It consists of two components: `name` and `namespace`. The `name` is the identifier of the target API, while the `namespace` specifies the Kubernetes namespace where the API resource resides. Together, these elements ensure that Tyk Operator accurately locates and routes the request to the intended API. For example, `name: "proxy-api"` and `namespace: "default"` direct the request to the `proxy-api` resource in the `default` namespace. + +Tyk Operator would dynamically update the API definition by generating internal looping URL in the form of `tyk:///`. This mechanism is essential for routing traffic within a microservices architecture or when managing APIs across different namespaces in Kubernetes. Using this object you can effectively manage and optimize API traffic within your Tyk Gateway. + +--- + +## URL Rewrites {#url-rewrites} + +[URL rewriting]({{< ref "transform-traffic/url-rewriting" >}}) in Tyk enables the alteration of incoming API request paths to align with the expected endpoint format of your backend services. + +Assume that we wish to redirect incoming `GET /basic/` requests to an API defined by an ApiDefinition object named `proxy-api` in the `default` namespace. We want the `/basic/` prefix to be stripped from the request path and the redirected path should be of the format `/proxy/$1`, where the context variable `$1` is substituted with the remainder of the path request. For example `GET /basic/456` should become `GET /proxy/456`. + +In this case we can use a `rewrite_to_internal` object to instruct Tyk Operator to automatically generate the API rewrite URL on our behalf for the API identified by name `proxy-api` in the `default` namespace: + +```yaml +url_rewrites: + - path: "/{id}" + match_pattern: "/basic/(.*)" + method: GET + rewrite_to_internal: + target: + name: proxy-api + namespace: default + path: proxy/$1 +``` + +In the above example an incoming request of `/basic/456` would be matched by the `match_pattern` rule `/basic/(.*)` for `GET` requests specified in the `method` field. The `456` part of the URL will be captured and replaces `{id}` in the `path` field. Tyk Operator will use the `rewrite_to_internal` configuration to generate the URL rewrite for the API named `proxy-api` in the `default` namespace, and update the `rewrite_to` field accordingly: + +```yaml +url_rewrites: +- match_pattern: /basic/(.*) + method: GET + path: /{id} + rewrite_to: tyk://ZGVmYXVsdC9wcm94eS1hcGk/proxy/$1 +``` + +Here we can see that the `rewrite_to` field has been generated with the value `tyk://ZGVmYXVsdC9wcm94eS1hcGk/proxy/$1` where `ZGVmYXVsdC9wcm94eS1hcGk` represents the API ID for the `proxy-api` API resource in the `default` namespace. Notice also that path `proxy/$1` is appended to the base URL `tyk://ZGVmYXVsdC9wcm94eS1hcGk` and contains the context variable `$1`. This will be substituted with the value of `{id}` in the `path` configuration parameter. + +## URL Rewrite Triggers {#url-rewrite-triggers} + +[Triggers]({{< ref "product-stack/tyk-gateway/middleware/url-rewrite-middleware#url-rewrite-triggers" >}}) are configurations that specify actions based on certain conditions present in HTTP headers, query parameters, path parameters etc. + +Triggers are essential for executing specific actions when particular criteria are met, such as rewriting URLs. They are useful for automating actions based on real-time data received in requests. For example, you might use triggers to: + +- Redirect users to different APIs in the Gateway based on their authentication status. +- Enforce business rules by redirecting requests to different APIs in the Gateway based on certain parameters. + +The process for configuring internal looping in triggers to is similar to that explained in section [URL Rewrites](#url-rewrites"). + +Assume that we wish to instruct Tyk Operator to redirect all *Basic Authentication* requests to the API identified by `basic-auth-internal` within the `default` namespace. Subsequently, we can use a `rewrite_to_internal` object as follows: + +```yaml +triggers: + - "on": "all" + options: + header_matches: + "Authorization": + match_rx: "^Basic" + rewrite_to_internal: + target: + name: basic-auth-internal + namespace: default + path: "basic/$2" +``` + +Here we we can see that a trigger is configured for all requests that include an `Authorization` header containing `Basic` in the header value. + +A `rewrite_to_internal` configuration object is used to instruct Tyk Operator to generate a redirect to the API identified by the `basic-auth-internal` API resource in the `default` namespace. The redirect path will be prefixed with `basic`. For example, a basic authentication request to path `/` will be redirected to `/basic/`. + +Tyk Operator will automatically generate a URL Rewrite (`rewrite_to`) to redirect the request to the API identified by `basic-auth-internal` within the `default` namespace as follows: + +```yaml +triggers: +- "on": all + options: + header_matches: + Authorization: + match_rx: ^Basic + rewrite_to: tyk://ZGVmYXVsdC9iYXNpYy1hdXRoLWludGVybmFs/basic/$2 +``` + +Here we can see that the `rewrite_to` field has been generated with the value `tyk://ZGVmYXVsdC9iYXNpYy1hdXRoLWludGVybmFs/proxy/$1` where `ZGVmYXVsdC9iYXNpYy1hdXRoLWludGVybmFs` represents the API ID for the `proxy-api` API resource in the `default` namespace. Notice also that path `basic/$2` is appended to the base URL `tyk://ZGVmYXVsdC9iYXNpYy1hdXRoLWludGVybmFs` and contains the context variable `$2`. This will be substituted with the remainder of the request path. + +## Proxy to Internal APIs {#proxy-to-internal-apis} + +Internal looping can also be used for [proxying to internal APIs]({{< ref "advanced-configuration/transform-traffic/looping" >}}). + +Assume that we wish to redirect all incoming requests on listen path `/users` to an API defined by an ApiDefinition object named `users-internal-api` in the `default` namespace. + +In this case we can use a `proxy.target_internal` field to instruct Tyk Operator to automatically generate the target URL on our behalf for the API identified by name `users-internal-api` in the `default` namespace: + +```yaml {linenos=true, linenostart=1, hl_lines=["12-15"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: users +spec: + name: Users API + protocol: http + active: true + use_keyless: true + proxy: + target_url: "" + target_internal: + target: + name: users-internal-api + namespace: default + listen_path: /users + strip_listen_path: true +``` + +The proxy object’s `target_internal` field references other API resources. This field shares the same properties as those described for `rewrite_to_internal`, ensuring consistent configuration. + +Tyk Operator will automatically generate the target URL to redirect the request to the API identified by `users-internal-api` within the `default` namespace as follows: + +```yaml + target_url: "tyk://ZGVmYXVsdC91c2Vycy1pbnRlcm5hbC1hcGk" +``` + +--- + +## Example + +Assume a business has legacy customers who authenticate with a service using *Basic Authentication*. The business also wants to support API Keys, enabling both client types to access the same ingress. + +To facilitate this, Tyk must be configured for dynamic authentication, accommodating both *Basic Authentication* and *Auth Token* methods. + +This setup requires configuring four API Definitions within Tyk: + +1. Entry Point API +2. BasicAuth Internal API +3. AuthToken Internal API +4. Proxy Internal API + +When a request arrives at the ingress route, a URL rewrite can direct it to either the *BasicAuth Internal* or *AuthToken Internal* API, depending on the authentication method used. + +These internal APIs will authenticate the requests. Assuming successful authentication (the happy path), they will forward the requests to the *Proxy Internal API*, which handles the proxying to the underlying service. + +
+ +{{< note success >}} +**Note** + +There are no actual HTTP redirects in this scenario, meaning that there is no performance penalty in performing any of these *Internal Redirects*. + +{{< /note >}} + +### Entry Point API + +The *Entry Point* API is the first point of entry for a client request. It inspects the header to determine if the incoming client request requires authentication using *Basic Authentication* or *Auth Token*. Consequently, it then redirects the request to the *BasicAuth Internal* or *AuthToken Internal* API depending upon the header included in the client request. + +The API definition resource for the *Entry Point* API is listed below. It is configured to listen for requests on the `/entry` path and forward requests upstream to `http://example.com` + +We can see that there is a URL Rewrite rule (`url_rewrites`) with two triggers configured to match Basic Authentication and Auth Token requests: + +- **Basic Authentication trigger**: Activated for incoming client requests that include an *Authorization* header containing a value starting with *Basic*. In this case a `rewrite_to_internal` configuration object is used to instruct Tyk Operator to redirect the request to the *BasicAuthInternal* API, identified by name `basic-auth-internal` in the `default` namespace. The request URL is rewritten, modifying the path to `/basic/`. +- **Auth Token trigger**: Activated for incoming client requests that include an *Authorization* header containing a value starting with *Bearer*. In this case a `rewrite_to_internal` configuration object is used to instruct Tyk Operator to redirect the request to the *AuthTokenInternal* API, identified by name `auth-token-internal` in the `default` namespace. The request URL is rewritten, modifying the path to `/token/`. + + ```yaml {linenos=true, linenostart=1, hl_lines=["21-45"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: entrypoint-api +spec: + name: Entrypoint API + protocol: http + active: true + proxy: + listen_path: /entry + target_url: http://example.com + use_keyless: true + version_data: + default_version: Default + not_versioned: true + versions: + Default: + name: Default + use_extended_paths: true + extended_paths: + url_rewrites: + - path: "/{id}" + match_pattern: "/(.*)/(.*)" + method: GET + triggers: + - "on": "all" + options: + header_matches: + "Authorization": + match_rx: "^Basic" + rewrite_to_internal: + target: + name: basic-auth-internal + namespace: default + path: "basic/$2" + - "on": "all" + options: + header_matches: + "Authorization": + match_rx: "^Bearer" + rewrite_to_internal: + target: + name: auth-token-internal + namespace: default + path: "token/$2" +``` + +### BasicAuth Internal API + +The *BasicAuth Internal* API listens to requests on path `/basic` and forwards them upstream to `http://example.com`. + +The API is configured with a URL rewrite rule in `url_rewrites` to redirect incoming `GET /basic/` requests to the API in the Gateway represented by name `proxy-api` in the `default` namespace. The `/basic/` prefix will be stripped from the request URL and the URL will be rewritten with the format `/proxy/$1`. The context variable `$1` is substituted with the remainder of the path request. For example `GET /basic/456` will become `GET /proxy/456`. + +Furthermore, a header transform rule is configured within `transform_headers` to add the header `x-transform-api` with value `basic-auth`, to the request. + +```yaml {linenos=true, linenostart=1, hl_lines=["21-35"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: basic-auth-internal +spec: + name: BasicAuth Internal API + protocol: http + proxy: + listen_path: "/basic" + target_url: http://example.com + active: true + use_keyless: true + version_data: + default_version: Default + not_versioned: true + versions: + Default: + name: Default + use_extended_paths: true + extended_paths: + url_rewrites: + - path: "/{id}" + match_pattern: "/basic/(.*)" + method: GET + rewrite_to_internal: + target: + name: proxy-api + namespace: default + path: proxy/$1 + transform_headers: + - add_headers: + x-transform-api: "basic-auth" + method: GET + path: "/{id}" + delete_headers: [] +``` + +### AuthToken Internal API + +The *AuthToken Internal* API listens to requests on path `/token` and forwards them upstream to `http://example.com`. + +The API is configured with a URL rewrite rule in `url_rewrites` to redirect incoming `GET /token/` requests to the API in the Gateway represented by name `proxy-api` in the `default` namespace. The `/token/` prefix will be stripped from the request URL and the URL will be rewritten to the format `/proxy/$1`. The context variable `$1` is substituted with the remainder of the path request. For example `GET /token/456` will become `GET /proxy/456`. + +Furthermore, a header transform rule is configured within `transform_headers` to add the header `x-transform-api` with value `token-auth`, to the request. + +```yaml {linenos=true, linenostart=1, hl_lines=["21-35"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: auth-token-internal +spec: + name: AuthToken Internal API + protocol: http + proxy: + listen_path: "/token" + target_url: http://example.com + active: true + use_keyless: true + version_data: + default_version: Default + not_versioned: true + versions: + Default: + name: Default + use_extended_paths: true + extended_paths: + url_rewrites: + - path: "/{id}" + match_pattern: "/token/(.*)" + method: GET + rewrite_to_internal: + target: + name: proxy-api + namespace: default + path: proxy/$1 + transform_headers: + - add_headers: + x-transform-api: "token-auth" + method: GET + path: "/{id}" + delete_headers: [] +``` + +### Proxy Internal API + +The *Proxy Internal* API is keyless and responsible for listening to requests on path `/proxy` and forwarding upstream to `http://httpbin.org`. The listen path is stripped from the request before it is sent upstream. + +This API receives requests forwarded from the internal *AuthToken Internal* and *BasicAuth Internal APIs*. Requests will contain the header `x-transform-api` with value `token-auth` or `basic-auth`, depending upon which internal API the request originated from. + +```yaml {linenos=true, linenostart=1, hl_lines=["10-13"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: proxy-api +spec: + name: Proxy API + protocol: http + active: true + internal: true + proxy: + listen_path: "/proxy" + target_url: http://httpbin.org + strip_listen_path: true + use_keyless: true +``` \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-operator/advanced-configurations/management-of-api.md b/tyk-docs/content/product-stack/tyk-operator/advanced-configurations/management-of-api.md new file mode 100644 index 0000000000..2a0f86683f --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-operator/advanced-configurations/management-of-api.md @@ -0,0 +1,166 @@ +--- +title: "Management of APIs" +date: 2024-06-25 +tags: ["Tyk", "Kubernetes", "API Management", "CRD", "DevOps", "API Gateway Configuration"] +description: "This documentation provides a comprehensive guide on configuring various aspects of API descriptions and metadata using Tyk Operator. It includes detailed instructions and examples for setting API name, status, category, ID, path, ownership, and versioning within the ApiDefinition Custom Resource Definition (CRD). The guide ensures that users can manage their Tyk API Gateway configurations effectively within a Kubernetes environment." +keywords: ["Tyk Operator", "Kubernetes", "API Gateway", "API Configuration", "API Metadata", "ApiDefinition CRD", "Tyk Dashboard", "API Status", "API Category", "API ID", "API Path", "API Ownership", "API Versioning"] +--- + +This documentation provides a comprehensive guide on configuring various aspects of API descriptions and metadata using Tyk Operator. + +## API Name + +To set the name of an API in the `ApiDefinition`, use the `spec.name` string field. This name is displayed on the Tyk Dashboard and should concisely describe what the API represents. + +Example: + +```yaml {linenos=true, linenostart=1, hl_lines=["6-6"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: example-api # This is the metadata name of the Kubernetes resource +spec: + name: Example API # This is the "API NAME" in Tyk + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://example.com + listen_path: /example + strip_listen_path: true +``` + +## API Status + +### API Active Status + +An active API will be loaded to the Gateway, while an inactive API will not, resulting in a 404 response when called. + +The active status of an API can be set by modifying the `spec.active` configuration parameter. When set to `true`, this enables the API so that Tyk will listen for and process requests made to the `listenPath`. + +```yaml {linenos=true, linenostart=1, hl_lines=["9-9"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: inactive-api +spec: + name: Inactive API + use_keyless: true + protocol: http + active: false + proxy: + target_url: http://inactive.example.com + listen_path: /inactive + strip_listen_path: true +``` + +### API Accessibility + +An API can be configured as internal so that external requests are not processed. This is achieved by setting the `spec.internal`configuration parameter as shown in the example below. + + +```yaml {linenos=true, linenostart=1, hl_lines=["10-10"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: inactive-api +spec: + name: Inactive API + use_keyless: true + protocol: http + active: true + internal: true + proxy: + target_url: http://inactive.example.com + listen_path: /inactive + strip_listen_path: true +``` + +## API Category + +For a Tyk Classic API, you can specify the category name using the `spec.name` field with a `#` qualifier. This will categorize the API in the Tyk Dashboard. + +Example + +```yaml {linenos=true, linenostart=1, hl_lines=["6-6"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: categorized-api +spec: + name: "my-classic-api #global #staging" + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://categorized.example.com + listen_path: /categorized + strip_listen_path: true +``` + +## API ID + +### Creating a new API + +If you're creating a new API using Tyk Operator, you don't need to specify the ID in the manifest. The API ID will be generated in a deterministic way. You can inspect `status.api_id` field to get the generated API ID. + +Example + +```yaml {linenos=true, linenostart=1} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: order + namespace: shop +spec: + name: Order API + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://order.example.com + listen_path: /order + strip_listen_path: true +``` + +Run the following command to inspect generated API ID. + +```bash +% kubectl get apidefinition order --namespace shop -o yaml | grep api_id -B 1 +status: + api_id: c2hvcC9vcmRlcg +``` + +### Updating an existing API + +If you already have API configurations created in the Tyk Dashboard and want to start using Tyk Operator to manage these APIs, you can include the existing API ID in the manifest under the `spec.api_id` field. This way, when you apply the manifest, Tyk Operator will not create a new API in the Dashboard. Instead, it will update the original API with the Kubernetes spec. + +Example + +```yaml {linenos=true, linenostart=1, hl_lines=["8-8"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: existing-api + namespace: default +spec: + name: Existing API + api_id: 12345 + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://existing.example.com + listen_path: /existing + strip_listen_path: true +``` + +In this example, the API with ID `12345` will be updated according to the provided spec instead of creating a new API. + +## API Ownership + +To configure API ownership, ensure Tyk Operator is also an owner of the API. This can be done using Operator Context. For details, refer to Tyk [Operator API Ownership]({{< ref "product-stack/tyk-operator/getting-started/tyk-operator-api-ownership">}}). + +## API Versioning + +For details on how to configure API versions, refer to [configuring API versioning in Tyk Operator]({{< ref "getting-started/key-concepts/versioning#tyk-operator" >}}) \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-graphql.md b/tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-graphql.md new file mode 100644 index 0000000000..0f84a63a80 --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-graphql.md @@ -0,0 +1,108 @@ +--- +date: 2017-03-24T16:39:31Z +title: Sample GraphQL Proxy +tags: ["Tyk Operator", "Sample", "Kubernetes"] +description: "Tyk Operator manifest example" +--- + +This page provides a sample manifest for creating [GraphQL proxy APIs]({{}}). + +In the example below we can see that the configuration is contained within the `graphql` configuration object. A GraphQL schema is specified within the `schema` field and the execution mode is set to `proxyOnly`. The [GraphQL public playground]({{< ref "graphql/graphql-playground#enabling-public-graphql-playground" >}}) is enabled with the path set to `/playground`. + +```yaml {hl_lines=["15-17", "18-92"],linenos=false} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: trevorblades +spec: + name: trevorblades + use_keyless: true + protocol: http + active: true + proxy: + target_url: https://countries.trevorblades.com + listen_path: /trevorblades + strip_listen_path: true + graphql: + enabled: true + version: "2" + execution_mode: proxyOnly + schema: | + directive @cacheControl(maxAge: Int, scope: CacheControlScope) on FIELD_DEFINITION | OBJECT | INTERFACE + + enum CacheControlScope { + PUBLIC + PRIVATE + } + + type Continent { + code: ID! + name: String! + countries: [Country!]! + } + + input ContinentFilterInput { + code: StringQueryOperatorInput + } + + type Country { + code: ID! + name: String! + native: String! + phone: String! + continent: Continent! + capital: String + currency: String + languages: [Language!]! + emoji: String! + emojiU: String! + states: [State!]! + } + + input CountryFilterInput { + code: StringQueryOperatorInput + currency: StringQueryOperatorInput + continent: StringQueryOperatorInput + } + + type Language { + code: ID! + name: String + native: String + rtl: Boolean! + } + + input LanguageFilterInput { + code: StringQueryOperatorInput + } + + type Query { + continents(filter: ContinentFilterInput): [Continent!]! + continent(code: ID!): Continent + countries(filter: CountryFilterInput): [Country!]! + country(code: ID!): Country + languages(filter: LanguageFilterInput): [Language!]! + language(code: ID!): Language + } + + type State { + code: String + name: String! + country: Country! + } + + input StringQueryOperatorInput { + eq: String + ne: String + in: [String] + nin: [String] + regex: String + glob: String + } + + """The `Upload` scalar type represents a file upload.""" + scalar Upload + playground: + enabled: true + path: /playground +``` \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-http.md b/tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-http.md new file mode 100644 index 0000000000..70a26f019d --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-http.md @@ -0,0 +1,106 @@ +--- +date: 2017-03-24T16:39:31Z +title: Sample HTTP Proxy +tags: ["Tyk Operator", "Sample", "Kubernetes"] +description: "Tyk Operator manifest example" +--- + +This page provides some sample manifests for creating different types of HTTP proxy APIs. Follow these examples to learn how to configure your APIs. + +## HTTP Proxy + +This example creates a basic API definition that routes requests to listen path `/httpbin` to target URL `http://httpbin.org`. + +Traffic routing can be configured under `spec.proxy`: +- `target_url` defines the upstream address (or target URL) to which requests should be proxied. +- `listen_path` is the base path on Tyk to which requests for this API should be sent. Tyk listens out for any requests coming into the host at this path, on the port that Tyk is configured to run on and processes these accordingly. For example, `/api/` or `/` or `/httpbin/`. +- `strip_listen_path` removes the inbound listen path (as accessed by the client) when generating the outbound request for the upstream service. For example, consider the scenario where the Tyk base address is `http://acme.com/`, the listen path is `example/` and the upstream URL is `http://httpbin.org/`: If the client application sends a request to `http://acme.com/example/get` then the request will be proxied to `http://httpbin.org/example/get` + +```yaml {hl_lines=["10-13"],linenos=false} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin +spec: + name: httpbin + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin + strip_listen_path: true +``` + +## HTTP Host-based Proxy + +`spec.domain` is the domain to bind this API to. This enforces domain matching for client requests. + +In this example, requests to `httpbin.tyk.io` will be proxied to upstream URL `http://httpbin.org` + +```yaml {hl_lines=["10-10"],linenos=false} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin +spec: + name: httpbin + use_keyless: true + protocol: http + active: true + domain: httpbin.tyk.io + proxy: + target_url: http://httpbin.org + listen_path: / + strip_listen_path: true +``` + +## HTTPS Proxy + +This example creates a API definition that routes requests to a http://httpbin.org via port 8443. + +```yaml {hl_lines=["35-38"],linenos=false} +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: selfsigned-issuer +spec: + selfSigned: { } +--- +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: my-test-cert +spec: + secretName: my-test-tls + dnsNames: + - foo.com + - bar.com + privateKey: + rotationPolicy: Always + issuerRef: + name: selfsigned-issuer + # We can reference ClusterIssuers by changing the kind here. + # The default value is Issuer (i.e. a locally namespaced Issuer) + kind: Issuer + # This is optional since cert-manager will default to this value however + # if you are using an external issuer, change this to that issuer group. + group: cert-manager.io +--- +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin +spec: + name: httpbin + use_keyless: true + protocol: https + listen_port: 8443 + certificate_secret_names: + - my-test-tls + active: true + proxy: + target_url: http://httpbin.org + listen_path: /httpbin + strip_listen_path: true +``` \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-tcp.md b/tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-tcp.md new file mode 100644 index 0000000000..f098aab1d6 --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-tcp.md @@ -0,0 +1,24 @@ +--- +date: 2017-03-24T16:39:31Z +title: Sample TCP Proxy +tags: ["Tyk Operator", "Sample", "Kubernetes"] +description: "Tyk Operator manifest example" +--- + +This page provides sample manifest for creating TCP proxy APIs. Follow the example to learn how to configure your APIs. + +This example creates a API definition that proxies request from TCP port `6380` to `tcp://localhost:6379`. + +```yaml {hl_lines=["8-11"],linenos=false} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: redis-tcp +spec: + name: redis-tcp + active: true + protocol: tcp + listen_port: 6380 + proxy: + target_url: tcp://localhost:6379 +``` \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-udg.md b/tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-udg.md new file mode 100644 index 0000000000..b9b4c56f79 --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-operator/getting-started/quick-start-udg.md @@ -0,0 +1,162 @@ +--- +date: 2017-03-24T16:39:31Z +title: Sample TCP Proxy +tags: ["Tyk Operator", "Sample", "Kubernetes"] +description: "Tyk Operator manifest example" +--- + +This page provides sample manifest for creating [Universal Data Graph (UDG)]({{}}) APIs. Follow the example to learn how to configure your APIs. + +## UDG v2 (Tyk 3.2 and above) + +If you are on Tyk 3.2 and above, you can use the following manifest to create an UDG API. This example configures a Universal Data Graph from a [GraphQL datasource]({{}}) and a [REST Datasource]({{}}). + +```yaml {hl_lines=["20-39", "46-80"],linenos=false} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: udg +spec: + name: Universal Data Graph v2a + use_keyless: true + protocol: http + active: true + proxy: + target_url: "" + listen_path: /udg + strip_listen_path: true + version_data: + default_version: Default + not_versioned: true + versions: + Default: + name: Default + graphql: + enabled: true + execution_mode: executionEngine + schema: | + type Country { + name: String + code: String + restCountry: RestCountry + } + + type Query { + countries: [Country] + } + + type RestCountry { + altSpellings: [String] + subregion: String + population: Int + } + version: "2" + last_schema_update: "2022-10-12T14:27:55.511+03:00" + type_field_configurations: [] + playground: + enabled: true + path: /playground + engine: + field_configs: + - disable_default_mapping: false + field_name: countries + path: + - "countries" + type_name: Query + - disable_default_mapping: true #very important for rest APIs + field_name: restCountry + path: [] + type_name: Country + data_sources: + - kind: "GraphQL" + name: "countries" + internal: false + root_fields: + - type: Query + fields: + - "countries" + config: + url: "https://countries.trevorblades.com/" + method: "POST" + headers: {} + body: "" + - kind: "REST" + internal: false + name: "restCountries" + root_fields: + - type: "Country" + fields: + - "restCountry" + config: + url: "https://restcountries.com/v2/alpha/{{ .object.code }}" + method: "GET" + body: "" + headers: {} +``` + +## UDG v1 (Tyk 3.1 or before) + +If you are on Tyk 3.1, you can use the following manifest to create an UDG API. This example creates a Universal Data Graph with GraphQL datasource and HTTP JSON datasource. + +```yaml +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: udg +spec: + name: Universal Data Graph Example + use_keyless: true + protocol: http + active: true + proxy: + target_url: "" + listen_path: /udg + strip_listen_path: true + graphql: + enabled: true + execution_mode: executionEngine + schema: | + type Country { + name: String + code: String + restCountry: RestCountry + } + + type Query { + countries: [Country] + } + + type RestCountry { + altSpellings: [String] + subregion: String + population: String + } + type_field_configurations: + - type_name: Query + field_name: countries + mapping: + disabled: false + path: countries + data_source: + kind: GraphQLDataSource + data_source_config: + url: "https://countries.trevorblades.com" + method: POST + status_code_type_name_mappings: [] + - type_name: Country + field_name: restCountry + mapping: + disabled: true + path: "" + data_source: + kind: HTTPJSONDataSource + data_source_config: + url: "https://restcountries.com/v2/alpha/{{ .object.code }}" + method: GET + default_type_name: RestCountry + status_code_type_name_mappings: + - status_code: 200 + playground: + enabled: true + path: /playground +``` \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-operator/getting-started/tyk-operator-multiple-organisations.md b/tyk-docs/content/product-stack/tyk-operator/getting-started/tyk-operator-multiple-organisations.md index c84e4c38b7..c61052542d 100644 --- a/tyk-docs/content/product-stack/tyk-operator/getting-started/tyk-operator-multiple-organisations.md +++ b/tyk-docs/content/product-stack/tyk-operator/getting-started/tyk-operator-multiple-organisations.md @@ -1,7 +1,7 @@ --- -title: "Managing Multiple Organizations with Tyk Operator CRDs" +title: "Managing Multiple Organizations with OperatorContext" date: 2024-06-25 -tags: ["Tyk Operator", "Organizations", "Kubernetes"] +tags: ["Tyk Operator", "Environments", "Organizations", "Kubernetes"] description: "Learn how to use Tyk Operator Custom Resource Definitions (CRDs) to manage multiple organizations within Tyk. This guide explains how to leverage OperatorContext to efficiently manage resources for different teams. Examples and best practices are included for effective multi-tenant API management." --- diff --git a/tyk-docs/content/product-stack/tyk-operator/reference/api-definition.md b/tyk-docs/content/product-stack/tyk-operator/reference/api-definition.md new file mode 100644 index 0000000000..1874fc18d0 --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-operator/reference/api-definition.md @@ -0,0 +1,122 @@ +--- +title: "API Definition" +date: 2024-06-25 +tags: ["Tyk Operator", "Kubernetes", "API Definition"] +description: "Support features of APIDefinition CRD" +--- + +The ApiDefinition custom resource defines configuration of [Tyk Classic API Definition object]({{}}). + +Here are the supported features: + +## API Types + +| Type | Support | Supported From | Comments | Sample | +|--------------------------------|---------|----------------|------------------------------|--------------------------------------------------------------------------------------------| +| HTTP | ✅ | v0.1 | - | [HTTP Proxy]({{}}) | +| HTTPS | ✅ | v0.4 | - | [HTTPS Proxy]({{}}) | +| TCP | ✅ | v0.1 | - | [TCP Proxy]({{}}) | +| TLS | ✅ | v0.1 | - | | +| GraphQL - Proxy | ✅ | v0.1 | - | [GraphQL Proxy]({{}}) | +| Universal Data Graph v1 | ✅ | v0.1 | - | [UDG v1 Proxy]({{}}) | +| Universal Data Graph v2 | ✅ | v0.12 | - | [UDG v2 Proxy]({{}}) | +| GraphQL - Federation | ✅ | v0.12 | - | [GraphQL Federation]({{}}) | + +## Management of APIs + +| Type | Support | Supported From | Comments | Sample | +|--------------------------------|---------|----------------|------------------------------|--------| +| API Name | ✅ | v0.1 | - | [API Name]({{}}) | +| API Status (inactive/active) | ✅ | v0.2 | - | [API Active Status]({{}}) | +| API Categories | ✅ | v0.1 | - | [API Categories]({{}}) | +| API ID | ✅ | v0.1 | - | [API ID]({{}}) |- | | +| API Ownership | ✅ | v0.12 | - | [API Ownership]({{}}) | +| API Versioning | ✅ | v0.1 | - | [API Versioning]({{}}) | + +## Traffic Routing + + +| Type | Supported | Supported From | Comments | Sample | +| --------------------------- | --------- | -------------- | -------- | ------------- | +| Path-Based Proxy | ✅ | v0.1 | - | [HTTP Proxy]({{}}) | +| Host-Based Proxy | ✅ | v0.1 | - | [HTTP Host-based Proxy]({{}}) | +| Target URL | ✅ | v0.1 | - | [HTTP Proxy]({{}}) | + +## Client to Gateway Authentication and Authorization + +| Type | Supported | Supported From | Comments | Sample | +| ----------------------------- | --------- | -------------- | -------- | ------------- | +| Keyless | ✅ | v0.1 | - | [Keyless]({{}}) | +| Auth Token | ✅ | v0.1 | - | [Auth Token]({{}}) | +| JWT | ✅️ | v0.5 | - | [JWT]({{}}) | +| OpenID Connect | ❌ | - | JWT is the recommended way configuring OIDC. Please see [OpenID Connect]({{}}) documentation for details. | | +| OAuth2 | ❌ | - | JWT is the recommended way to configure OAuth2. Please see [OpenID Connect]({{}}) documentation for details. | | +| Client mTLS | ✅ | v0.11 | Only static client mTLS is supported | [mTLS]({{}}) | +| HMAC | ❌ | - | Not implemented | | +| Basic Authentication | ✅ | v0.12 | Only enabling with default metadata values is supported | [Basic Auth]({{}}) | +| Custom Authentication Plugin (Go) | ✅ | v0.11 | - | [Custom Auth (go)]({{}}) | +| Custom Authentication Plugin (gRPC) | ✅ | v0.1 | - | [Custom Auth (gRPC)]({{}}) | +| Multiple Authentication | ✅ | v0.14 | - | [Multiple Auth]({{}}) | +| IP Allowlist | ✅ | v0.5 | - | [IP Allowlist]({{}}) | +| IP Blocklist | ✅ | v0.5 | - | [IP Blocklist]({{}}) | + +## Gateway to Upstream Authentication + +| Type | Supported | Supported From | Comments | Sample | +|-------------------------------------------------|-----------|----------------|-----------------| ------------- | +| Upstream Certificates mTLS | ✅ | v0.9 | | [Upstream mTLS]({{}}) | +| Public Key Certificate Pinning | ✅ | v0.9 | | [Certificate Pinning]({{}}) | +| Upstream Request Signing | ❌ | - | Not implemented | | + +## API-level (Global) Features + +| Feature | Supported | Supported From | Comments | Sample | +|--------------------------------------|-----------|----------------|------------------------------------------------------------------------|-----------------------------------------------------------------| +| Detailed recording (in Log Browser) | ✅ | v0.4.0 | - | [Detailed recording]({{}}) | +| Config Data | ✅ | v0.8.2 | - | [Config Data]({{}}) | +| Context Variables | ✅ | v0.1 | - | [Context Variables]({{}}) | +| Cross Origin Resource Sharing (CORS) | ✅ | v0.2 | - | [CORS]({{}}) | +| Service Discovery | ⚠️ | - | Untested | | +| Segment Tags | ✅ | v0.1 | - | [Segment Tags]({{}}) | +| Internal API (not exposed by Gateway)| ✅ | v0.6.0 | - | [API Accessibility]({{< ref "product-stack/tyk-operator/advanced-configurations/management-of-api#api-accessibility" >}}) | +| Global (API-level) Header Transform | ✅ | v0.1.0 | - | [Global Header Transform]({{}}) | +| Global (API-level) Rate Limit | ✅ | v0.10 | - | [Global Rate Limit]({{}}) | +| Custom Plugins | ✅ | v0.1 | - | [Custom Plugins]({{< ref "product-stack/tyk-operator/advanced-configurations/custom-plugins" >}}) +| Analytics Plugin | ✅ | v0.16.0 | - | [Analytics Plugins]({{}})| +| Batch Requests | ❌ | - | - | | +| Custom Analytics Tags (Tag Headers) | ✅ | v0.10.0 | - | [Custom Analytics Tags (Tag Headers)]({{< ref "tyk-apis/tyk-gateway-api/api-definition-objects/custom-analytics#tyk-operator" >}}) | +| Expire Analytics After | ❌ | - | - | | +| Do not track Analytics (per API) | ✅ | v0.1.0 | - | [Do Not Track]({{< ref "product-stack/tyk-gateway/middleware/do-not-track-tyk-classic" >}}) |- | | +| Webhooks | ❌ | - | - | | +| Looping | ✅ | v0.6 | - | [Internal Looping]({{< ref "product-stack/tyk-operator/advanced-configurations/internal-looping" >}}) | +| Round Robin Load Balancing | ✅ | - | - | [Load Balancing]({{}}) | + +## Endpoint-level Features + +| Endpoint Middleware | Supported | Supported From | Comments | Sample | +|-----------------------------------|-----------|----------------|------------------------------------------------|---------------| +| Allow list | ✅️ | v0.8.2 | - | [Allow list]({{}}) | +| Block list | ✅️ | v0.8.2 | - | [Block list]({{}}) | +| Cache | ✅ | v0.1 | - | [Cache]({{}}) | +| Advance Cache | ✅ | v0.1 | - | [Advanced Cache]({{}}) | +| Circuit Breaker | ✅ | v0.5 | - | [Circuit Breaker]({{}}) | +| Track Endpoint | ✅ | v0.1 | | [Track Endpoint]({{}}) | +| Do Not Track Endpoint | ✅ | v0.1 | | [Do Not Track Endpoint]({{}}) | +| Enforced Timeouts | ✅ | v0.1 | - | [Enforced Timeouts]({{}}) | +| Ignore Authentication | ✅ | v0.8.2 | - | [Ignore Authentication]({{}}) | +| Internal Endpoint | ✅ | v0.1 | - | [Internal Endpoint]({{}}) | +| URL Rewrite | ✅️ | v0.1 | - | [URL Rewrite]({{}}) | +| Validate Request | ✅ | v0.8.2 | - | [Validate Request]({{}}) | +| Rate Limit | ❌ | - | - | | +| Request Size Limit | ✅️ | v0.1 | - | [Request Size Limit]({{}}) | +| Request Method Transform | ✅ | v0.5 | - | [Request Method Transform]({{}}) | +| Request Header Transform | ✅ | v0.1 | - | [Request Header Transform]({{}}) | +| Request Body Transform | ✅ | v0.1 | - | [Request Body Transform]({{}}) | +| Request Body JQ Transform | ⚠️ | v0.1 | Requires [JQ on Gateway Docker Image]({{}}) | | +| Response Header Transform | ✅ | v0.1 | - | [Response Header Transform]({{}}) | +| Response Body Transform | ✅ | v0.1 | - | [Response Body Transform]({{}}) | +| Response Body JQ Transform | ⚠️ | v0.1 | Requires [JQ on Gateway Docker Image]({{}}) | | +| Mock Response | ✅ | v0.1 | - | [Mock Response]({{}})| +| Virtual Endpoint | ✅ | v0.1 | - | [Virtual Endpoint]({{}}) | +| Per-Endpoint Plugin | ❌ | - | - | | +| Persist Graphql | ❌ | - | - | | \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-operator/reference/security-policy.md b/tyk-docs/content/product-stack/tyk-operator/reference/security-policy.md new file mode 100644 index 0000000000..1aaf3ab0d4 --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-operator/reference/security-policy.md @@ -0,0 +1,20 @@ +--- +title: "Security Policy" +date: 2024-06-25 +tags: ["Tyk Operator", "Kubernetes", "Security Policy"] +description: "Support features of SecurityPolicy CRD" +--- + +The SecurityPolicy custom resource defines configuration of [Tyk Security Policy object]({{}}). +Here are the supported features: + +| Feature | Supported | +|-----------------------------------------------------------|----------------------------------------------------------------| +| API Access | ✅ | +| Rate Limit, Throttling, Quotas | ✅ | +| Meta Data & Tags | ✅ | +| Path based permissions | ✅ | +| Partitions | ✅ | +| Per API limit | ❌ | + +Consult [Security Policy CRD]({{}}) to see examples of setting these features. \ No newline at end of file diff --git a/tyk-docs/content/security/certificate-pinning.md b/tyk-docs/content/security/certificate-pinning.md index d01496bcf7..ce2789695e 100644 --- a/tyk-docs/content/security/certificate-pinning.md +++ b/tyk-docs/content/security/certificate-pinning.md @@ -62,4 +62,91 @@ You can define certificate public key pinning from the **Advanced** tab of the A 1. Click **Attach Certificate** {{< img src="/img/2.10/add_public_keys.png" alt="Pinning Options" >}} 1. From the **Add upstream certificates** options add the domain details and then add a new certificate ID or the server path to a certificate, or select from any certificates you have added previously. -2. Click **Add** \ No newline at end of file +2. Click **Add** + +## Define via Tyk Operator + +Tyk Operator supports configuring certificate pinning using one of the following fields within the ApiDefinition object: + +- **pinned_public_keys**: Use public keys uploaded via the Certificate API. +- **pinned_public_keys_refs**: Uses public keys configured from Kubernetes secret objects. + +### pinned_public_keys + +Use the `pinned_public_keys` mapping to pin public keys to specific domains, referencing public keys that have been uploaded to Tyk Certificate storage via the Certificate API. + +```yaml +pinned_public_keys: + "foo.com": "", + "*": "," +``` + +Each `key-id` value should be set to the ID returned from uploading the public key via the Certificate API. Multiple public keys can be specified by separating their IDs by a comma. + +### pinned_public_keys_refs + +The `pinned_public_keys_refs` mapping should be used to configure pinning of public keys sourced from Kubernetes secret objects for different domains. + +Each key should be set to the name of the domain and the value should refer to the name of a Kuberenetes secret object that holds the corresponding public key for that domain. + +Wildcard domains are supported and "*" can be used to denote all domains. + +{{< warning >}} +**Caveats** + +- Only *kubernetes.io/tls* secret objects are allowed. +- Please use the *tls.crt* field for the public key. +- The secret that includes a public key must be in the same namespace as the ApiDefinition object. +{{< /warning >}} + +The example below illustrates a scenario where the public key from the Kubernetes secret object, *httpbin-secret*, is used for all domains, denoted by the wildcard character '*'. In this example the *tls.crt* field of the secret is set to the actual public key of *httpbin.org*. Subsequently, if you any URL other than https://httpbin.org is targetted (e.g. https://github.com/) a *public key pinning error* will be raised for that particular domain. This is because the public key of *httpbin.org* has been configured for all domains. + +```yaml +# ApiDefinition object 'pinned_public_keys_refs' field uses the following format: +# spec: +# pinned_public_keys_refs: +# "domain.org": # the name of the Kubernetes Secret Object that holds the public key for the 'domain.org'. +# +# In this way, you can refer to Kubernetes Secret Objects through 'pinned_public_keys_refs' field. +# +# In this example, we have an HTTPS upstream target as `https://httpbin.org`. The public key of httpbin.org is obtained +# with the following command: +# $ openssl s_client -connect httpbin.org:443 -servername httpbin.org 2>/dev/null | openssl x509 -pubkey -noout +# +# Note: Please set tls.crt field of your secret to actual public key of httpbin.org. +# +# We are creating a secret called 'httpbin-secret'. In the 'tls.crt' field of the secret, we are specifying the public key of the +# httpbin.org obtained through above `openssl` command, in the decoded manner. +# +apiVersion: v1 +kind: Secret +metadata: + name: httpbin-secret +type: kubernetes.io/tls +data: + tls.crt: # Use tls.crt field for the public key. + tls.key: "" +--- +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-certificate-pinning +spec: + name: httpbin - Certificate Pinning + use_keyless: true + protocol: http + active: true + pinned_public_keys_refs: + "*": httpbin-secret + proxy: + target_url: https://httpbin.org + listen_path: /pinning + strip_listen_path: true + version_data: + default_version: Default + not_versioned: true + versions: + Default: + name: Default +``` + diff --git a/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/cors.md b/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/cors.md index de80f413f9..ef9d2513a2 100644 --- a/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/cors.md +++ b/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/cors.md @@ -8,9 +8,15 @@ weight: 6 --- -It is possible to enable CORS for certain APIs so users can make browser-based requests. The `CORS` section is added to an API definition as follows: +It is possible to enable CORS for certain APIs so users can make browser-based requests. The `CORS` section is added to an API definition as listed in the examples below for Tyk Gateway and Tyk Operator. -```.json +--- + +## Examples + +{{< tabs_start >}} +{{< tab_start "Gateway API Definition" >}} +```json "CORS": { "enable": true, "allowed_origins": [ @@ -25,7 +31,41 @@ It is possible to enable CORS for certain APIs so users can make browser-based r "debug": false } ``` - +{{< tab_end >}} +{{< tab_start "Tyk Operator API Definition" >}} +```yaml {linenos=true, linenostart=1, hl_lines=["14-24"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-cors-sample +spec: + name: httpbin-cors-sample + use_keyless: true + protocol: http + active: true + proxy: + target_url: http://httpbin.org + listen_path: /cors + strip_listen_path: true + CORS: + enable: true + allowed_origins: + - "http://foo.com" + allowed_methods: null + allowed_headers: null + exposed_headers: null + allow_credentials: false + max_age: 24 + options_passthrough: false + debug: false +``` +{{< tab_end >}} +{{< tabs_end >}} + +--- + +## Configuration + The CORS middleware has the following options: * `CORS.allowed_origins`: A list of origin domains to allow access from. Wildcards are also supported, e.g. `http://*.foo.com` diff --git a/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/custom-analytics.md b/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/custom-analytics.md index 9d3adbc423..16c7f9a6c5 100644 --- a/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/custom-analytics.md +++ b/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/custom-analytics.md @@ -13,6 +13,8 @@ aliases: For example if you include `X-test-header` header in the `tag_headers` array, then, for each incoming request Tyk will add a `x-test-header-` tag to the list of tags in the request analytic record. +If you are using Tyk Operator please refer to [how to setup tag headers with Tyk Operator](#tyk-operator). + ## When is it useful? Example use cases are: @@ -70,3 +72,29 @@ curl http://tyk-gateway.localhost:8080/basic-open-api/get -H "X-Team-Name: devop {{< img src="/img/custom-analytics-tags/log-browser.png" alt="Log Browser" >}} ### We can now have Tyk track API requests which contain our business logic!!! + + +## How to setup tag headers with Tyk Operator {#tyk-operator} + +To setup tag headers with Tyk Operator add the list of headers to tag to the `tag_headers` object within the `spec` field of the API definition resource. An example is given below: + +```yaml {linenos=true, linenostart=1, hl_lines=["10-12"]} +apiVersion: tyk.tyk.io/v1alpha1 +kind: ApiDefinition +metadata: + name: httpbin-tag-headers +spec: + name: httpbin-tag-headers + use_keyless: true + protocol: http + active: true + tag_headers: + - Host + - User-Agent + proxy: + target_url: http://httpbin.org + listen_path: /httpbin-tag-headers + strip_listen_path: true +``` + +In this example we can see that the `Host` and `User-Agent` headers exist within the `tag_headers` array. For each incoming request Tyk will add a `host-` and `user-agent-` tags to the list of tags in the request analytic record. diff --git a/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/ip-blacklisting.md b/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/ip-blacklisting.md index 02df308bbf..13ed1af349 100644 --- a/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/ip-blacklisting.md +++ b/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/ip-blacklisting.md @@ -22,4 +22,8 @@ weight: 5 For more details on CIDR notation, see [this Wikipedia entry](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation). -

{{}}{{}}

\ No newline at end of file +

{{}}{{}}

+ +#### Tyk Operator + +Please consult the Tyk Operator supporting documentation for an example of how to [configure an IP block list]({{< ref "product-stack/tyk-operator/advanced-configurations/client-authentication#ip-blocklist" >}}) with Tyk Operator. \ No newline at end of file diff --git a/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/ip-whitelisting.md b/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/ip-whitelisting.md index 80b6648b7c..5d105531b2 100644 --- a/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/ip-whitelisting.md +++ b/tyk-docs/content/tyk-apis/tyk-gateway-api/api-definition-objects/ip-whitelisting.md @@ -22,4 +22,8 @@ weight: 5 } ``` -For more details on CIDR notation, see [this Wikipedia entry](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation). \ No newline at end of file +For more details on CIDR notation, see [this Wikipedia entry](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation). + +#### Tyk Operator + +Please consult the Tyk Operator supporting documentation for an example of how to [configure an IP allow list]({{< ref "product-stack/tyk-operator/advanced-configurations/client-authentication#ip-allowlist" >}}) with Tyk Operator. \ No newline at end of file diff --git a/tyk-docs/content/tyk-stack/tyk-operator/access-an-api.md b/tyk-docs/content/tyk-stack/tyk-operator/access-an-api.md index 49de07c6a2..9daf4a0883 100644 --- a/tyk-docs/content/tyk-stack/tyk-operator/access-an-api.md +++ b/tyk-docs/content/tyk-stack/tyk-operator/access-an-api.md @@ -1,10 +1,7 @@ --- date: 2017-03-24T16:39:31Z -title: Access an API with Tyk Operator +title: Secure an API with Auth token weight: 3 -menu: - main: - parent: "Getting started with Tyk Operator" --- ### Tutorial: Update an API to require a key @@ -81,7 +78,7 @@ Content-Length: 46 -Tyk Operator supported authentication types are listed [here](https://github.com/TykTechnologies/tyk-operator/blob/master/docs/api_definitions.md#client-to-gateway-authentication). +Tyk Operator supported authentication types are listed in the [API Definition features]({{}}) page. {{< /note >}} @@ -103,7 +100,7 @@ Metadata: ... Spec: ... - api_id: ZGVmYXVsdC9odHRwYmlu + Name: httpbin ... Status: api_id: ZGVmYXVsdC9odHRwYmlu diff --git a/tyk-docs/content/tyk-stack/tyk-operator/create-an-api.md b/tyk-docs/content/tyk-stack/tyk-operator/create-an-api.md index 0e5ba32303..6fb439ed10 100644 --- a/tyk-docs/content/tyk-stack/tyk-operator/create-an-api.md +++ b/tyk-docs/content/tyk-stack/tyk-operator/create-an-api.md @@ -8,7 +8,7 @@ menu: --- ### Tutorial: Create an API with Tyk Operator -Creating an API takes the same approach whether you are using Tyk Open Source or Self Managed. First, specify the details of your API using the [ApiDefinition CRD](https://github.com/TykTechnologies/tyk-operator/blob/master/docs/api_definitions.md), then deploy it to create corresponding Kubernetes resource. Tyk Operator will take control of the CRD and create the actual API in the Tyk data plane. +Creating an API takes the same approach whether you are using Tyk Open Source or Self Managed. First, specify the details of your API using the [ApiDefinition CRD]({{}}), then deploy it to create the corresponding Kubernetes resource. Tyk Operator will take control of the CRD and create the actual API in the Tyk data plane. #### Step 1: Create an ApiDefinition resource in YAML format Create a file called `httpbin.yaml`, then add the following: @@ -88,7 +88,7 @@ $ curl -i localhost:8080/httpbin/get We can walk you through the ApiDefinition that we created. We have an ApiDefinition called `httpbin`, as specified in `spec.name` field, which listens to path `/httpbin` and proxies requests to [http://httpbin.org](http://httpbin.org), as specified under `spec.proxy` field. Now, any requests coming to the `/httpbin` endpoint will be proxied to the target URL that we defined in `spec.proxy.target_url`, which is [http://httpbin.org](http://httpbin.org) in our example. -You can go to the [API Definitions](https://github.com/TykTechnologies/tyk-operator/blob/master/docs/api_definitions.md) page on GitHub to see all the latest API Definitions fields and features we support. +You can visit the [ApiDefinition CRD]({{}}) page to see all the latest API Definitions fields and features we support. ### Configure Kubernetes service as an upstream target diff --git a/tyk-docs/content/tyk-stack/tyk-operator/migration.md b/tyk-docs/content/tyk-stack/tyk-operator/migration.md index 5b41094024..72ece53026 100644 --- a/tyk-docs/content/tyk-stack/tyk-operator/migration.md +++ b/tyk-docs/content/tyk-stack/tyk-operator/migration.md @@ -1,6 +1,6 @@ --- date: 2017-03-24T16:39:31Z -title: Getting started with existing APIs and policies +title: Manage existing APIs and policies weight: 16 menu: main: diff --git a/tyk-docs/content/tyk-stack/tyk-operator/publish-an-api.md b/tyk-docs/content/tyk-stack/tyk-operator/publish-an-api.md index 593b80a47a..4e552404d3 100644 --- a/tyk-docs/content/tyk-stack/tyk-operator/publish-an-api.md +++ b/tyk-docs/content/tyk-stack/tyk-operator/publish-an-api.md @@ -1,10 +1,6 @@ --- date: 2017-03-24T16:39:31Z -title: Publish an API with Tyk Operator -weight: 5 -menu: - main: - parent: "Getting started with Tyk Operator" +title: Publish an API to Dev Portal --- ### Introduction diff --git a/tyk-docs/content/tyk-stack/tyk-operator/secure-an-api.md b/tyk-docs/content/tyk-stack/tyk-operator/secure-an-api.md index 0522158e2d..4117c6808e 100644 --- a/tyk-docs/content/tyk-stack/tyk-operator/secure-an-api.md +++ b/tyk-docs/content/tyk-stack/tyk-operator/secure-an-api.md @@ -1,10 +1,6 @@ --- date: 2017-03-24T16:39:31Z -title: Secure an API with Tyk Operator -weight: 4 -menu: - main: - parent: "Getting started with Tyk Operator" +title: Protect an API with a Security Policy --- ### Introduction @@ -44,10 +40,10 @@ spec: You can link this Security Policy to any APIs you have defined in `access_rights_array`. In this example, the security policy is applied to `httpbin` API in `default` namespace. #### Step 2: Deploy the SecurityPolicy resource -You can do so either by applying sample manifests defined in [our repository](https://github.com/TykTechnologies/tyk-operator/tree/master/docs/policies), for example: +You can do so by applying the above manifest: ```console -$ kubectl apply -f docs/policies/ratelimit.yaml +$ kubectl apply -f ratelimit.yaml ``` Or, if you don’t have the manifest with you, you can run the following command: @@ -169,4 +165,4 @@ Meta data: - `meta_data`: Metadata key and values. -You can go to the [Policies](https://github.com/TykTechnologies/tyk-operator/blob/master/docs/policies.md) page on GitHub to see all the latest Security Policies fields and features we support. +You can visit the [Security Policy features]({{}}) page to see all the latest Security Policies fields and features Tyk Operator supports. diff --git a/tyk-docs/data/menu.yaml b/tyk-docs/data/menu.yaml index 7d50fc3971..0d6f614ade 100644 --- a/tyk-docs/data/menu.yaml +++ b/tyk-docs/data/menu.yaml @@ -3855,18 +3855,46 @@ menu: category: Page show: True - title: "Create an API" - path: /tyk-stack/tyk-operator/create-an-api - category: Page - show: True - - title: "Access an API" - path: /tyk-stack/tyk-operator/access-an-api - category: Page + category: Directory show: True + menu: + - title: "Create an API with Tyk Operator" + path: /tyk-stack/tyk-operator/create-an-api + category: Page + show: True + - title: "HTTP Proxy example" + path: /product-stack/tyk-operator/getting-started/quick-start-http + category: Page + show: True + - title: "TCP Proxy example" + path: /product-stack/tyk-operator/getting-started/quick-start-tcp + category: Page + show: True + - title: "GraphQL Proxy example" + path: /product-stack/tyk-operator/getting-started/quick-start-graphql + category: Page + show: True + - title: "UDG example" + path: /product-stack/tyk-operator/getting-started/quick-start-udg + category: Page + show: True - title: "Secure an API" - path: /tyk-stack/tyk-operator/secure-an-api + category: Directory + show: True + menu: + - title: "Secure an API with Auth token" + path: /tyk-stack/tyk-operator/access-an-api + category: Page + show: True + - title: "Authentication types" + path: /product-stack/tyk-operator/advanced-configurations/client-authentication + category: Page + show: True + - title: "Protect an API with Policy" category: Page show: True - - title: "Publish an API" + path: /tyk-stack/tyk-operator/secure-an-api + - title: "Publish an API to Dev Portal" path: /tyk-stack/tyk-operator/publish-an-api category: Page show: True @@ -3874,22 +3902,38 @@ menu: category: Directory show: True menu: - - title: "Migration to Tyk Operator" + - title: "Management of APIs" + path: /product-stack/tyk-operator/advanced-configurations/management-of-api + category: Page + show: True + - title: "Manage existing APIs and policies" path: /tyk-stack/tyk-operator/migration category: Page show: True - - title: "Configure Tyk Operator as Ingress Controller" + - title: "Kubernetes Ingress Controller" path: /product-stack/tyk-operator/tyk-ingress-controller category: Page show: True - - title: "Manage Multiple Organisations With OperatorContext" + - title: "Manage multiple organisations" path: /product-stack/tyk-operator/getting-started/tyk-operator-multiple-organisations category: Page show: True - - title: "Manage API Ownership with OperatorContext" + - title: "Manage API Ownership" path: /product-stack/tyk-operator/getting-started/tyk-operator-api-ownership category: Page show: True + - title: "GraphQL Federation" + path: /product-stack/tyk-operator/advanced-configurations/graphql-federation + category: Page + show: True + - title: "Custom Plugins" + path: /product-stack/tyk-operator/advanced-configurations/custom-plugins + category: Page + show: True + - title: "Looping" + path: /product-stack/tyk-operator/advanced-configurations/internal-looping + category: Page + show: True - title: "Troubleshooting" category: Directory show: True @@ -3906,6 +3950,14 @@ menu: category: Directory show: True menu: + - title: "API Definition features" + path: /product-stack/tyk-operator/reference/api-definition + category: Page + show: True + - title: "Security Policy features" + path: /product-stack/tyk-operator/reference/security-policy + category: Page + show: True - title: "Version compatibility" path: /product-stack/tyk-operator/reference/version-compatibility category: Page