Using Tyk Operator within Kubernetes allows you to manage API lifecycles declaratively. This section provides instructions for setting up and configuring the Tyk Operator to automate API creation, updates, and security in Kubernetes clusters, ensuring your APIs align with Kubernetes management practices.
If you’re using Kubernetes, or if you’re building an API that operates within a Kubernetes environment, the Tyk Operator is a powerful tool for automating the API lifecycle.Tyk Operator is a native Kubernetes operator, allowing you to define and manage APIs as code. This means you can deploy, update, and secure APIs using the same declarative configuration approach Kubernetes uses for other application components.
With Tyk Operator, you can configure your APIs using Kubernetes native manifest files. You can use the manifest files in a GitOps workflow as the single source of truth for API deployment.
If you use Tyk Operator to manage your APIs, you should set up RBAC such that human users cannot have the “write” permission on the API definition endpoints using Tyk Dashboard.
“GitOps” refers to the operating model of using Git as the “single source of truth” to drive continuous delivery for infrastructure and software through automated CI/CD workflow.
You can install Argo CD, Flux CD or the GitOps tool of your choice in a cluster, and connect it to the Git repository where you version control your API manifests. The tool can synchronise changes from Git to your cluster. The API manifest updates in cluster would be detected by Tyk Operator, which has a Kubernetes controller to automatically reconcile the API configurations on your Tyk Gateway or Tyk Dashboard.Kubernetes-Native Developer Experience
API Developers enjoy a smoother Continuous Integration process as they can develop, test, and deploy the microservices. API configurations together use familiar development toolings and pipeline.Reliability
With declarative API configurations, you have a single source of truth to recover after any system failures, reducing the meantime to recovery from hours to minutes.
Tyk Operator will reconcile any divergence between the Kubernetes desired state and the actual state in Tyk Gateway or Tyk Dashboard. Therefore, you should maintain the API definition manifests in Kubernetes as the single source of truth for your system. If you update your API configurations using Tyk Dashboard, those changes would be reverted by Tyk Operator eventually.To learn more about Gitops with Tyk, refer the following blog posts:
In Kubernetes, a Custom Resource (CR) is an extension of the Kubernetes API that allows you to introduce custom objects in your cluster. Custom Resources enable you to define and manage custom configurations and settings specific to your applications, making Kubernetes highly extensible. These custom objects are defined using Custom Resource Definitions (CRDs), which specify the schema and structure of the resource.Tyk Operator manages multiple custom resources to help users create and maintain their API configurations:TykOasApiDefinition: Available from Tyk Operator v1.0. It represents a Tyk OAS API configuration. Tyk OAS API is based on the OpenAPI specification (OAS) and is the recommended format for standard HTTP APIs.ApiDefinition: Available on all versions of Tyk Operator. It represents a Tyk Classic API configuration. Tyk Classic API is the traditional format used for defining all APIs in Tyk, and now the recommended format for non-HTTP APIs such as TCP, GraphQL, and Universal Data Graph (UDG). Tyk Operator supports the major features of Tyk Classic API and the feature support details can be tracked here.TykStreamsApiDefinition: Available from Tyk Operator v1.1. It represents an Async API configuration which is based on Tyk OAS API Definition. Tyk Operator supports all Tyk Streams features as they become available on the Gateway.SecurityPolicy: Available on all versions of Tyk Operator. It represents a Tyk Security Policy configuration. Security Policies in Tyk provide a way to define and enforce security controls, including authentication, authorization, and rate limiting for APIs managed in Tyk. Tyk Operator supports essential features of Security Policies, allowing users to centrally manage access control and security enforcement for all APIs across clusters.These custom resources enable users to leverage Kubernetes’ declarative configuration management to define, modify, and version their APIs, seamlessly integrating with other Kubernetes-based workflows and tools.
Defines configuration of security policies. Operator supports linking ApiDefinition custom resources in SecurityPolicy’s access list so that API IDs do not need to be hardcoded in the resource manifest.
In Kubernetes, controllers watch one or more Kubernetes resources, which can be built-in types like Deployments or custom resources like ApiDefinition - in this case, we refer to Controller as Operator. The purpose of a controller is to match the desired state by using Kubernetes APIs and external APIs.
A Kubernetes operator is an application-specific controller that extends the functionality of the Kubernetes API to create, configure, and manage instances of complex applications on behalf of a Kubernetes user.
Let’s start with the Desired State. It is defined through Kubernetes Manifests, most likely YAML or JSON, to describe what you want your system to be in. Controllers will watch the resources and try to match the actual state (the observed state) with the desired state for Kubernetes Objects. For example, you may want to create a Deployment that is intended to run three replicas. So, you can define this desired state in the manifests, and Controllers will perform necessary operations to make it happen.How about Observed State? Although the details of the observed state may change controller by controller, usually controllers update the status field of Kubernetes objects to store the observed state. For example, in Tyk Operator, we update the status to include api_id, so that Tyk Operator can understand that the object was successfully created on Tyk.
Reconciliation is a special design paradigm used in Kubernetes controllers. Tyk Operator also uses the same paradigm, which is responsible for keeping our Kubernetes objects in sync with the underlying external APIs - which is Tyk in our case.When would reconciliation happen? Before diving into Tyk Operator reconciliation, let’s briefly mention some technical details about how and when reconciliation happens. Reconciliation only happens when certain events happen on your cluster or objects. Therefore, Reconciliation will NOT be triggered when there is an update or modification on Tyk’s side. It only watches certain Kubernetes events and is triggered based on them. Usually, the reconciliation happens when you modify a Kubernetes object or when the cache used by the controller expires - side note, controllers, in general, use cached objects to reduce the load in the Kube API server. Typically, caches expire in ~10 hours or so but the expiration time might change based on Operator configurations.So, in order to trigger Reconciliation, you can either
modify an object, which will trigger reconciliation over this modified object or,
restart Tyk Operator pod, which will trigger reconciliation over each of the objects watched by Tyk Operator.
What happens during Reconciliation? Tyk Operator will compare desired state of the Kubernetes object with the observed state in Tyk. If there is a drift, Tyk Operator will update the actual state on Tyk with the desired state. In the reconciliation, Tyk Operator mainly controls three operations; DELETE, CREATE, and UPDATE.
CREATE - an object is created in Kubernetes but not exists in Tyk
UPDATE - an object is in different in Kubernetes and Tyk (we compare that by hash)
DELETE - an object is deleted in Kubernetes but exists in Tyk
Drift Detection If human operators or any other system delete or modify API Definition from Tyk Gateway or Dashboard, Tyk Operator will restore the desired state back to Tyk during reconciliation. This is called Drift Detection. It can protect your systems from unauthorized or accidental modifications. It is a best practice to limit user access rights on production environment to read-only in order to prevent accidental updates through API Manager directly.
Tyk follows standard practices for naming and versioning custom resources as outlined by the Kubernetes Custom Resource Definition versioning guidelines. Although we are currently on the v1alpha1 version, no breaking changes will be introduced to existing Custom Resources without a version bump. This means that any significant changes or updates that could impact existing resources will result in a new version (e.g., v1beta1 or v1) and Operator will continue supporting all CRD versions for a reasonable time before deprecating an older version. This ensures a smooth transition and compatibility, allowing you to upgrade without disrupting your current configurations and workflows.For more details on Kubernetes CRD versioning practices, refer to the Kubernetes Custom Resource Definition Versioning documentation.
Tyk Operator is a Kubernetes Controller that manages Tyk Custom Resources (CRs) such as API Definitions and Security Policies. Developers define these resources as Custom Resource (CRs), and Tyk Operator ensures that the desired state is reconciled with the Tyk Gateway or Dashboard. This involves creating, updating, or deleting API configurations until the target state matches the desired state.For the Tyk Dashboard, Tyk Operator functions as a system user, bound by Organization and RBAC rules.During start up, Tyk Operator looks for these keys from tyk-operator-conf secret or from the environment variables (listed in the table below).
Key or Environment Variable
Description
TYK_MODE
”ce” for OSS or “pro” for licensed users
TYK_URL
URL of Tyk Gateway or Dashboard API
TYK_ORG
Organization ID of Operator user
TYK_AUTH
API key of Operator user
These would be the default credentials Tyk Operator uses to connect to Tyk.
Tyk Dashboard is multi-tenant capable, which means you can use a single Tyk Dashboard instance to host separate organizations for each team or department. Each organization is a completely isolated unit with its own:
API Definitions
API Keys
Users
Developers
Domain
Tyk Classic Portal
This structure is ideal for businesses with a complex hierarchy, where distinct departments operate independently but within the same overall infrastructure.
Define OperatorContext for Multi-Tenant API Management
The OperatorContext in Tyk Operator allows you to create isolated management environments by defining specific access parameters for different teams or departments within a shared Tyk Operator instance. It helps you specify:
The Tyk Dashboard with which the Operator interacts
The organization under which API management occurs
The user identity utilized for requests
The environment in which the Operator operates
By setting different OperatorContext configurations, you can define unique access and management contexts for different teams. These contexts can then be referenced directly in your ApiDefinition, TykOasApiDefinition, TykStreamsApiDefinition or SecurityPolicy custom resource definitions (CRDs) using the contextRef field, enabling precise control over API configurations.
If no OperatorContext is defined, Tyk Operator defaults to using credentials from the tyk-operator-conf secret or from environment variables. This means all API management actions are performed under the system’s default user credentials, with no specific contextual isolation.
OperatorContext Defined but Not Referenced
When an OperatorContext is defined but not referenced in an API configuration, Tyk Operator continues to use the default credentials from tyk-operator-conf. The specified OperatorContext is ignored, resulting in API operations being managed under default credentials.
OperatorContext Defined and Referenced
If a specific OperatorContext is both defined and referenced in an API or policy, Tyk Operator utilizes the credentials and parameters from the referenced OperatorContext to perform API operations. This allows each API or policy to be managed with isolated configurations, enabling team-based or department-specific API management within the same Kubernetes cluster.
Using OperatorContext offers flexibility for multi-tenancy, helping organizations manage and isolate API configurations based on their specific team or departmental needs.
Tyk Operator is designed to offer a seamless Kubernetes-native experience by managing TLS certificates stored within Kubernetes for your API needs. Traditionally, to use a certificate (e.g., as a client certificate, domain certificate, or certificate for accessing an upstream service), you would need to manually upload the certificate to Tyk and then reference it using a ‘Certificate ID’ in your API definitions. This process can become cumbersome, especially in a Kubernetes environment where certificates are often managed as secrets and may rotate frequently.To address this challenge, Tyk Operator allows you to directly reference certificates stored as Kubernetes secrets within your custom resource definitions (CRDs). This reduces operational overhead, minimizes the risk of API downtime due to certificate mismatches, and provides a more intuitive experience for API developers.
We assume you have already installed Tyk. If you don’t have it, check out Tyk
Cloud or Tyk Self
Managed page. Tyk Helm
Chart is the preferred (and easiest) way to install Tyk on Kubernetes.In order for policy ID matching to work correctly, Dashboard must have allow_explicit_policy_id and
enable_duplicate_slugs set to true and Gateway must have policies.allow_explicit_policy_id set to true.Tyk Operator needs a user credential to connect with
Tyk Dashboard. The Operator user should have write access to the resources it is going to manage, e.g. APIs, Certificates,
Policies, and Portal. It is the recommended practice to turn off write access for other users for the above resources. See
Using Tyk Operator to enable GitOps with Tyk about
maintaining a single source of truth for your API configurations.
Tyk Operator uses cert-manager to provision certificates for the webhook server. If you don’t have cert-manager
installed, you can follow this command to install it:Alternatively, you have the option to manually handle TLS certificates by disabling the cert-manager requirement. For more details, please refer to this configuration.
Since Tyk Operator supports Kubernetes v1.19+, the minimum cert-manager version you can use is v1.8. If you run into the
cert-manager related errors, please ensure that the desired version of Kubernetes version works with the chosen version
of cert-manager by checking supported releases page and
cert-manager documentation.Please wait for the cert-manager to become available before continuing with the next step.
Option 1: Install Tyk Operator via Tyk’s Umbrella Helm Charts
If you are using Tyk Stack, Tyk Control
Plane, or Tyk Open
Source Chart, you can install Tyk Operator alongside other Tyk
components by setting value global.components.operator to true.Starting from Tyk Operator v1.0, a license key is required to use the Tyk Operator. You can provide it while installing
Tyk Stack, Tyk Control Plane or Tyk OSS helm chart by setting global.license.operator field. You can also set license
key via a Kubernetes secret using global.secrets.useSecretName field. The secret should contain a key called
OperatorLicenseNote: If you are using global.secrets.useSecretName, you must configure the operator license in the referenced Kubernetes secret. global.license.operator will not be used in this case.
Configure Tyk Operator via environment variable or tyk-operator-conf secret
Tyk Operator configurations can be set using envVars field of helm chart. See the table below for a list of expected
environment variable names and example values.
It can also be set via a Kubernetes secret. The default K8s secret name is tyk-operator-conf. If you want to use
another name, configure it through Helm Chart envFrom value.The Kubernetes secret or envVars field should set the following keys:
Key
Mandatory
Example Value
Description
TYK_OPERATOR_LICENSEKEY
Yes
<JWT_ENCODED_LICENSE_KEY>
Tyk Operator license key
TYK_MODE
Yes
pro
“ce” for Tyk Open Source mode, “pro” for Tyk licensed mode.
Management URL of Tyk Gateway (Open Source) or Tyk Dashboard
TYK_AUTH
Yes
2d095c2155774fe36d77e5cbe3ac963b
Operator user API key.
TYK_ORG
Yes
5e9d9544a1dcd60001d0ed20
Operator user ORG ID.
TYK_TLS_INSECURE_SKIP_VERIFY
No
true
Set to “true” if the Tyk URL is HTTPS and has a self-signed certificate. If it isn’t set, the default value is false.
WATCH_NAMESPACE
No
foo,bar
Comma separated list of namespaces for Operator to operate on. The default is to operate on all namespaces if not specified.
WATCH_INGRESS_CLASS
No
customclass
Define the ingress class Tyk Operator should watch. Default is tyk
TYK_HTTPS_INGRESS_PORT
No
8443
Define the ListenPort for HTTPS ingress. Default is 8443.
TYK_HTTP_INGRESS_PORT
No
8080
Define the ListenPort for HTTP ingress. Default is 8080.
Connect to Tyk Gateway or DashboardIf you install Tyk using Helm Chart, tyk-operator-conf will have been created with the following keys:
TYK_OPERATOR_LICENSEKEY, TYK_AUTH, TYK_MODE, TYK_ORG, and TYK_URL by default. If you didn’t use Helm Chart for
installation, please prepare tyk-operator-conf secret yourself using the commands below:
User API key and Organization ID can be found under “Add / Edit User” page within Tyk Dashboard. TYK_AUTH corresponds
to Tyk Dashboard API Access Credentials. TYK_ORG corresponds to Organization ID.
If the credentials embedded in the tyk-operator-conf are ever changed or updated, the tyk-operator-controller-manager
pod must be restarted to pick up these changes.
Watch NamespacesTyk Operator is installed with cluster permissions. However, you can optionally control which namespaces it watches by
setting the WATCH_NAMESPACE through tyk-operator-conf secret or the environment variable to a comma separated list
of k8s namespaces. For example:
WATCH_NAMESPACE="" will watch for resources across the entire cluster.
WATCH_NAMESPACE="foo" will watch for resources in the foo namespace.
WATCH_NAMESPACE="foo,bar" will watch for resources in the foo and bar namespace.
Watch custom ingress classYou can configure Tyk Operator as Ingress Controller so
that Ingress resources can be managed by Tyk as
APIs. By default, Tyk Operator looks for the value tyk in Ingress resources kubernetes.io/ingress.class annotation
and will ignore all other ingress classes. If you want to override this default behavior, you may do so by setting
WATCH_INGRESS_CLASS through tyk-operator-conf or the environment variable.
This process will deploy Tyk Operator and its required Custom Resource Definitions (CRDs) into your Kubernetes cluster
in tyk-operator-system namespace.Helm configurations
Starting from Tyk Operator v1.2.0, webhookPort is deprecated in favor of webhooks.port.
Starting from Tyk Operator v1.0, a valid license key is required for the Tyk Operator to function. If Tyk Operator is
upgraded from v0.x versions to one of v1.0+ versions, Tyk Operator needs a valid license key that needs to be provided
during upgrade process. This section describes how to set Tyk Operator license key to make sure Tyk Operator continues
functioning.To provide the license key for Tyk Operator, Kubernetes secret used to configure Tyk Operator (typically named
tyk-operator-conf as described above) requires an additional field called TYK_OPERATOR_LICENSEKEY. Populate this field
with your Tyk Operator license key.To configure the license key:
Locate the Kubernetes Secret used to configure Tyk Operator (typically named tyk-operator-conf).
Add a new field called TYK_OPERATOR_LICENSEKEY to this Secret.
Set the value of TYK_OPERATOR_LICENSEKEY to your Tyk Operator license key.
After updating the Kubernetes secret with this field, proceed with the standard upgrade process outlined below.
Helm does not upgrade or delete CRDs
when performing an upgrade. Because of this restriction, an additional step is required when upgrading Tyk Operator with
Helm.
Replace TYKOPERATORVERSIONwiththeimagetagcorrespondingtotheTykOperatorversiontowhichtheCustomResourceDefinitions(CRDs)belong.Forexample,toinstallCRDscompatiblewithTykOperatorv1.0.0,setTYK_OPERATOR_VERSION to v1.0.0.
Starting from Operator v1.2.0 release, Kubernetes Webhooks can now be configured using the Helm chart by specifying the necessary settings in the values.yaml file of the operator.
Since webhooks are enabled by default, there will be no impact to existing users.
Setting up OpenAPI Specification (OAS) APIs with Tyk involves preparing an OAS-compliant API definition and configuring it within your Kubernetes cluster using Tyk Operator. This process allows you to streamline API management by storing the OAS definition in a Kubernetes ConfigMap and linking it to Tyk Gateway through a TykOasApiDefinition resource.
First, you need to have a complete Tyk OAS API definition file ready. This file will contain all the necessary configuration details for your API in OpenAPI Specification (OAS) format.Here is an example of what the Tyk OAS API definition might look like. Note that Tyk extension x-tyk-api-gateway section should be present.
Save this API definition file (e.g., oas-api-definition.json) locally.
TipsYou can create and configure your API easily using Tyk Dashboard in a developer environment, and then obtain the Tyk OAS API definition following these instructions:
Open the Tyk Dashboard
Navigate to the API you want to manage with the Tyk Operator
Click on the “Actions” menu button and select “View API Definition.”
This will display the raw Tyk OAS API definition of your API, which you can then copy and save locally.
You need to create a ConfigMap in Kubernetes to store your Tyk OAS API definition. The Tyk Operator will reference this ConfigMap to retrieve the API configuration.To create the ConfigMap, run the following command:
This command creates a ConfigMap named tyk-oas-api-config in the tyk namespace (replace tyk with your actual namespace if different).
NotesThere is inherent size limit to a ConfigMap. The data stored in a ConfigMap cannot exceed 1 MiB. In case your OpenAPI document exceeds this size limit, it is recommended to split your API into smaller sub-APIs for easy management. For details, please consult Best Practices for Describing Large APIs from the OpenAPI initiative.
NotesIf you prefer to create ConfigMap with a manifest using kubectl apply command, you may get an error that the annotation metadata cannot exceed 256KB. It is because by using kubectl apply, kubectl automatically saves the whole configuration in the annotation kubectl.kubernetes.io/last-applied-configuration for tracking changes. Your Tyk OAS API Definition may easily exceed the size limit of annotations (256KB). Therefore, kubectl create is used here to get around the problem.
Now, create a TykOasApiDefinition resource to tell the Tyk Operator to use the Tyk OAS API definition stored in the ConfigMap.Create a manifest file named tyk-oas-api-definition.yaml with the following content:
Copy
Ask AI
apiVersion: tyk.tyk.io/v1alpha1kind: TykOasApiDefinitionmetadata: name: petstorespec: tykOAS: configmapRef: name: tyk-oas-api-config # Metadata name of the ConfigMap resource that stores the Tyk OAS API Definition namespace: tyk # Metadata namespace of the ConfigMap resource keyName: oas-api-definition.json # Key for retrieving Tyk OAS API Definition from the ConfigMap
Use kubectl to apply the TykOasApiDefinition manifest to your cluster:
Copy
Ask AI
kubectl apply -f tyk-oas-api-definition.yaml
This command creates a new TykOasApiDefinition resource in your cluster. The Tyk Operator will watch for this resource and configures Tyk Gateway or Tyk Dashboard with a new API using the provided Tyk OAS API definition.
After the Tyk OAS API has been successfully created, you can test it by sending a request to the API endpoint defined in your OAS file.For example, if your API endpoint is /store/inventory", you can use curl or any API client to test it:
Copy
Ask AI
curl "TYK_GATEWAY_URL/petstore/store/inventory"
Replace TYK_GATEWAY_URL with a URL of Tyk Gateway.
The Tyk Operator will automatically detect the change and update the API in the Tyk Gateway.
Noteskubectl replace without --save-config option is used here instead of kubectl apply because we do not want to save the Tyk OAS API definition in its annotation. If you want to enable --save-config option or use kubectl apply, the Tyk OAS API definition size would be further limited to at most 262144 bytes.
Here, a ConfigMap is created that contains the Tyk OAS API Definition with the data field with key test_oas.json. This is linked to from a TykOasApiDefinition resource via spec.tykOAS.configmapRef.To apply it, simply save the manifest into a file (e.g., tyk-oas-api.yaml) and use kubectl apply -f tyk-oas-api.yaml to create the required resources in your Kubernetes cluster. This command will create the necessary ConfigMap and TykOasApiDefinition resources in the default namespace.
First, you’ll modify your existing Tyk OAS API Definition to include the API key authentication configuration.When creating the Tyk OAS API, you stored your OAS definition in a file named oas-api-definition.json and created a ConfigMap named tyk-oas-api-config in the tyk namespace.Modify your Tyk OAS API Definition oas-api-definition.json as follow.
In this example, we added the following sections to configure key authentication for this API.
components.securitySchemes defines the authentication method (in this case, apiKey in the header).
security: Applies the authentication globally to all endpoints.
x-tyk-api-gateway.server.authentication: Tyk-specific extension to enable the authentication scheme.
You can configure your API for any Tyk supported authentication method by following the Client Authentication documentation.Save your updated API definition in the same file, oas-api-definition.json.
This command updates the existing ConfigMap named tyk-oas-api-config in the tyk namespace (replace tyk with your actual namespace if different) with the new Tyk OAS API Definition stored in oas-api-definition.json.Since a TykOasApiDefinition resource has been created with reference to this ConfigMap in the previous tutorial:
Copy
Ask AI
apiVersion: tyk.tyk.io/v1alpha1kind: TykOasApiDefinitionmetadata: name: petstorespec: tykOAS: configmapRef: name: tyk-oas-api-config # Metadata name of the ConfigMap resource that stores the Tyk OAS API Definition namespace: tyk # Metadata namespace of the ConfigMap resource keyName: oas-api-definition.json # Key for retrieving Tyk OAS API Definition from the ConfigMap
Any changes in the ConfigMap would be detected by Tyk Operator. Tyk Operator will then automatically reconcile the changes and update the API configuration at Tyk.
Now, test your API endpoint to confirm that it requires an API key.For example, if your API endpoint is /store/inventory", you can use curl or any API client to test it:
Replace TYK_GATEWAY_URL with a URL of Tyk Gateway.Request should fail with a 401 Unauthorized response now as an API key is required for access. Your API has been secured by Tyk Gateway.
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.
We have an ApiDefinition called httpbin, as specified in spec.name field, which listens to path /httpbin and proxies requests to 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 in our example.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
Tyk Gateway deployed in your Kubernetes cluster can easily access other Kubernetes services as an upstream proxy target.
In the ApiDefinition manifest, set the proxy.target_url as a Kubernetes Service following DNS for Services and Pods guideline, so that the requests will be proxied to your service.
In general, Kubernetes Services have a <service-name>.<namespace-name>.svc.cluster.local DNS entry once they are created.
For example, if you have a service called httpbin in default namespace, you can contact httpbin service with httpbin.default.svc DNS record in the cluster, instead of IP addresses.
Please visit the official Kubernetes documentation for more details.
Suppose you want to create a Deployment of httpbin service using ci/upstreams/httpbin.yaml file. You are going to expose the application through port 8000 as described under the Service specification.
You can create Service and Deployment by either applying the manifest defined in our repository:
Copy
Ask AI
$ kubectl apply -f ci/upstreams/httpbin.yaml
Or, if you don’t have the manifest with you, you can run the following command:
You need to wait until all pods reach READY 1/1 and STATUS Running state.
Once the pod is ready, you can update your httpbin API’s target_url field to proxy your requests to the Service that you created above.
You can check all services in the <ns> namespace as follows:
Pay attention to the value of the spec.proxy.target_url field.
It is set to http://httpbin.default.svc:8000 by following the convention described above (<service_name>.<namespace>.svc:<service_port>).
Now, if you send your request to the /httpbin endpoint of the Tyk Gateway, the request will be proxied to the httpbin Service:
You might already have realized that our httpbin API is keyless. If you check the APIDefinition’s specification, the use_keyless field is set to true.
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). Keyless access will enable all requests through.
You can disable keyless access by setting use_keyless to false.
If you have set use_keyless to false, the default authentication mode is Authentication token.Now, to access httpbin API, you need to include a key to the header. Otherwise, you will get a HTTP 401 Unauthorized response.
Copy
Ask AI
curl -i localhost:8080/httpbin/getHTTP/1.1 401 UnauthorizedContent-Type: application/jsonX-Generator: tyk.ioDate: Thu, 03 Mar 2022 15:47:30 GMTContent-Length: 46{ "error": "Authorization field missing"}
Tyk Operator supported authentication types are listed in the API Definition features section.
You need to generate a key to access the httpbin API now. Follow this guide to see how to create an API key for your installation.You can obtain the API name and API ID of our example httpbin API by following command:
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.
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.
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.
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.
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.
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 the Multi (Chained) Authentication section 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.
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 notation) that are allowed access via Tyk.
In this example, only requests coming from 127.0.0.2 is allowed.
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 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).
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 is enabled with the path set to /playground.
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
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
This example creates a API definition that routes requests to a http://httpbin.org via port 8443.
Copy
Ask AI
apiVersion: cert-manager.io/v1kind: Issuermetadata: name: selfsigned-issuerspec: selfSigned: { }---apiVersion: cert-manager.io/v1kind: Certificatemetadata: name: my-test-certspec: 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/v1alpha1kind: ApiDefinitionmetadata: name: httpbinspec: 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
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.
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.
Copy
Ask AI
apiVersion: tyk.tyk.io/v1alpha1kind: ApiDefinitionmetadata: name: udgspec: 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
Tyk Streams integrates natively with Tyk OpenAPI Specification (OAS), allowing you to manage APIs as code and automate processes in Kubernetes using Tyk Operator. Setting up Tyk Streams API is similar to configuring a standard Tyk OAS API. You can store the Tyk Streams OAS definition in a Kubernetes ConfigMap and connect it to Tyk Gateway through a TykStreamsApiDefinition resource.
To create a Tyk Streams API, start by preparing a complete Tyk Streams API definition in the OpenAPI Specification (OAS) format. This file must include:
The x-tyk-api-gateway extension for Tyk-specific settings.
The x-tyk-streaming extension for Tyk Streams configuration.
Here’s an example of a Tyk Streams API definition:
Once your Tyk Streams API definition is ready, use a Kubernetes ConfigMap to store the definition and link it to a TykStreamsApiDefinition custom resource.Example manifest:
Copy
Ask AI
apiVersion: tyk.tyk.io/v1alpha1kind: TykStreamsApiDefinitionmetadata: name: simple-streamspec: tykStreams: configmapRef: name: simple-stream-cm #k8s resource name of configmap namespace: default #The k8s namespace of the resource being targeted. If Namespace is not provided, #we assume that the ConfigMap is in the same namespace as TykStreamsApiDefinition resource. keyName: test_stream.json---apiVersion: v1kind: ConfigMapmetadata: name: simple-stream-cmdata: test_stream.json: |- { "components": {}, "info": { "title": "Simple streaming demo", "version": "1.0.0" }, "openapi": "3.0.3", "paths": {}, "x-tyk-api-gateway": { "info": { "name": "Simple streaming demo", "state": { "active": true } }, "server": { "detailedTracing": { "enabled": true }, "listenPath": { "strip": true, "value": "/streams/" } }, "upstream": { "url": "https://not-needed" } }, "x-tyk-streaming": { "streams": { "example-publisher": { "input": { "http_server": { "path": "/pub", "allowed_verbs": ["POST"], "timeout": "1s" } }, "output": { "http_server": { "ws_path": "/ws" } } } } } }
Use the kubectl command to apply the TykStreamsApiDefinition manifest to your Kubernetes cluster:
Copy
Ask AI
kubectl apply -f tyk-streams-api-definition.yaml
This will create a new TykStreamsApiDefinition resource. The Tyk Operator watches this resource and configures the Tyk Gateway or Tyk Dashboard with the new API.
To update your API configuration, modify the linked ConfigMap. The Tyk Operator will automatically detect changes and update the API in the Tyk Gateway.
To secure your Tyk Streams API, configure security fields in the OAS definition just as you would for a standard Tyk OAS API. For more details, refer to the Secure your Tyk OAS API guide.
To further protect access to your APIs, you will want to add a security policy.
Below, we take you through how to define the security policy but you can also find Security Policy Example below.
To create a security policy, you must define a Kubernetes manifest using the SecurityPolicy CRD. The following example illustrates how to configure a default policy for trial users for a Tyk Classic API named httpbin, a Tyk OAS API named petstore, and a Tyk Streams API named http-to-kafka.
Copy
Ask AI
apiVersion: tyk.tyk.io/v1alpha1kind: SecurityPolicymetadata: name: trial-policy # Unique Kubernetes namespec: name: Default policy for trial users # Descriptive name for the policy state: active active: true access_rights_array: - name: httpbin # Kubernetes name of referenced API namespace: default # Kubernetes namespace of referenced API kind: ApiDefinition # Omit this field or use `ApiDefinition` if you are referencing Tyk Classic API versions: - Default # The default version of Tyk Classic API is "Default" - name: petstore namespace: default kind: TykOasApiDefinition # Use `TykOasApiDefinition` if you are referencing Tyk OAS API versions: - "" # The default version of Tyk OAS API is "" - name: http-to-kafka namespace: default kind: TykStreamsApiDefinition # Use `TykStreamsApiDefinition` if you are referencing Tyk Streams API versions: - "" # The default version of Tyk Streams API is "" quota_max: 1000 quota_renewal_rate: 3600 rate: 120 per: 60 throttle_interval: -1 throttle_retry_limit: -1
Save the manifest locally in a file, e.g. trial-policy.yamlIn this example, we have defined a security policy as described below:Define Security Policy status and metadata
name: A descriptive name for the security policy.
active: Marks the policy as active (true or false).
state: The current state of the policy. It can have one of three values:
active: Keys connected to this policy are enabled and new keys can be created.
draft: Keys connected to this policy are disabled; no new keys can be created.
deny: Policy is not published to Gateway; no keys can be created.
tags: A list of tags to categorize or label the security policy, e.g.
Copy
Ask AI
tags: - Hello - World
meta_data: Key-value pairs for additional metadata related to the policy, e.g.
Copy
Ask AI
meta_data: key: value hello: world
Define Access Lists for APIs
access_rights_array: Defines the list of APIs that the security policy applies to and the versions of those APIs.
name: The Kubernetes metadata name of the API resource to which the policy grants access.
namespace: The Kubernetes namespace where the API resource is deployed.
kind: Tyk OAS APIs (TykOasApiDefinition), Tyk Streams (TykStreamsApiDefinition) and Tyk Classic APIs (ApiDefinition) can be referenced here. The API format can be specified by kind field. If omitted, ApiDefinition is assumed.
versions: Specifies the API versions the policy will cover. If the API is not versioned, include the default version here. The default version of a Classic API is “Default”. The default version of a Tyk OAS API is "".
In this example, the security policy will apply to an ApiDefinition resource named httpbin in the default namespace, a TykOasApiDefinition resource named petstore in the default namespace, and a TykStreamsApiDefinition resource named http-to-kafka in the default namespace. Note that with Tyk Operator, you do not need to specify API ID as in the raw Policy definition. Tyk Operator will automatically retrieve the API ID of referenced API Definition resources for you.Define Rate Limits, Usage Quota, and Throttling
rate: The maximum number of requests allowed per time period (Set to -1 to disable).
per: The time period (in seconds) for the rate limit (Set to -1 to disable).
throttle_interval: The interval (in seconds) between each request retry (Set to -1 to disable).
throttle_retry_limit: The maximum number of retry attempts allowed (Set to -1 to disable).
quota_max: The maximum number of requests allowed over a quota period (Set to -1 to disable).
quota_renewal_rate: The time, in seconds, after which the quota is renewed.
In this example, trial users under this security policy can gain access to the httpbin API at a rate limit of maximum 120 times per 60 seconds ("rate": 120, "per": 60), with a usage quota of 1000 every hour ("quota_max": 1000, "quota_renewal_rate": 3600), without any request throttling (throttle_interval: -1, throttle_retry_limit: -1).
From the status field, you can see that this security policy has been linked to httpbin, petstore, and http-to-kafka APIs.
Security policy example
Key-level per-API rate limits and quota
By configuring per-API limits, you can set specific rate limits, quotas, and throttling rules for each API in the access rights array. When these per-API settings are enabled, the API inherits the global limit settings unless specific limits and quotas are set in the limit field for that API.The following manifest defines a security policy with per-API rate limits and quotas for two APIs: httpbin and petstore.
Copy
Ask AI
apiVersion: tyk.tyk.io/v1alpha1kind: SecurityPolicymetadata: name: policy-per-api-limitsspec: name: Policy with Per API Limits state: active active: true access_rights_array: - name: httpbin # Kubernetes name of referenced API namespace: default # Kubernetes namespace of referenced API kind: ApiDefinition # `ApiDefinition` (Default), `TykOasApiDefinition` or `TykStreamsApiDefinition` versions: - Default # The default version of Tyk Classic API is "Default" limit: # APILimit stores quota and rate limit on ACL level rate: 10 # Max 10 requests per 60 seconds per: 60 # Time period for rate limit quota_max: 100 # Max 100 requests allowed over the quota period quota_renewal_rate: 3600 # Quota renewal period in seconds (1 hour) throttle_interval: -1 # No throttling between retries throttle_retry_limit: -1 # No limit on request retries - name: petstore namespace: default kind: TykOasApiDefinition # Use `TykOasApiDefinition` for Tyk OAS API versions: - "" # The default version of Tyk OAS API is "" limit: rate: 5 # Max 5 requests per 60 seconds per: 60 # Time period for rate limit quota_max: 100 # Max 100 requests allowed over the quota period quota_renewal_rate: 3600 # Quota renewal period in seconds (1 hour) throttle_interval: -1 # No throttling between retries throttle_retry_limit: -1 # No limit on request retries rate: -1 # Disable global rate limit per: -1 # Disable global rate limit period throttle_interval: -1 # Disable global throttling throttle_retry_limit: -1 # Disable global retry limit quota_max: -1 # Disable global quota quota_renewal_rate: 60 # Quota renewal rate in seconds (1 minute)
With this security policy applied:For the httpbin API:
The rate limit allows a maximum of 10 requests per 60 seconds.
The quota allows a maximum of 100 requests per hour (3600 seconds).
There is no throttling or retry limit (throttle_interval and throttle_retry_limit are set to -1).
For the petstore API:
The rate limit allows a maximum of 5 requests per 60 seconds.
The quota allows a maximum of 100 requests per hour (3600 seconds).
There is no throttling or retry limit (throttle_interval and throttle_retry_limit are set to -1).
Global Rate Limits and Quota:
All global limits (rate, quota, and throttling) are disabled (-1), so they do not apply.
By setting per-API rate limits and quotas, you gain granular control over how each API is accessed and used, allowing you to apply different limits for different APIs as needed. This configuration is particularly useful when you want to ensure that critical APIs have stricter controls while allowing more flexibility for others. Use this example as a guideline to tailor your security policies to your specific requirements.
Key-level per-endpoint rate limits
By configuring key-level per-endpoint limits, you can restrict the request rate for specific API clients to a specific endpoint of an API.The following manifest defines a security policy with per-endpoint rate limits for two APIs: httpbin and petstore.
Copy
Ask AI
apiVersion: tyk.tyk.io/v1alpha1kind: SecurityPolicymetadata: name: policy-per-api-limitsspec: name: Policy with Per API Limits state: active active: true access_rights_array: - name: httpbin # Kubernetes name of referenced API namespace: default # Kubernetes namespace of referenced API kind: ApiDefinition # `ApiDefinition` (Default), `TykOasApiDefinition` or `TykStreamsApiDefinition` versions: - Default # The default version of Tyk Classic API is "Default" endpoints: # Per-endpoint rate limits - path: /anything methods: - name: POST limit: rate: 5 per: 60 - name: PUT limit: rate: 5 per: 60 - name: GET limit: rate: 10 per: 60 - name: petstore namespace: default kind: TykOasApiDefinition # Use `TykOasApiDefinition` for Tyk OAS API versions: - "" # The default version of Tyk OAS API is "" endpoints: # Per-endpoint rate limits - path: /pet methods: - name: POST limit: rate: 5 per: 60 - name: PUT limit: rate: 5 per: 60 - name: GET limit: rate: 10 per: 60 rate: -1 # Disable global rate limit per: -1 # Disable global rate limit period throttle_interval: -1 # Disable global throttling throttle_retry_limit: -1 # Disable global retry limit quota_max: -1 # Disable global quota quota_renewal_rate: 60 # Quota renewal rate in seconds (1 minute)
Path based permissions
You can secure your APIs by specifying allowed URLs (methods and paths) for each API within a security policy. This is done using the allowed_urls field under access_rights_array.The following manifest defines a security policy that allows access only to specific URLs and HTTP methods for two APIs: httpbin(a Tyk Classic API) and petstore (a Tyk OAS API).
Copy
Ask AI
apiVersion: tyk.tyk.io/v1alpha1kind: SecurityPolicymetadata: name: policy-with-allowed-urlsspec: name: Policy with allowed URLs state: active active: true access_rights_array: - name: httpbin # Kubernetes name of referenced API namespace: default # Kubernetes namespace of referenced API kind: ApiDefinition # `ApiDefinition` (Default), `TykOasApiDefinition` or `TykStreamsApiDefinition` versions: - Default # The default version of Tyk Classic API is "Default" allowed_urls: # Define allowed paths and methods - url: /get # Only allow access to the "/get" path methods: - GET # Only allow the GET method - name: petstore namespace: default kind: TykOasApiDefinition # Use `TykOasApiDefinition` for Tyk OAS API versions: - "" # The default version of Tyk OAS API is "" allowed_urls: # Define allowed paths and methods - url: "/pet/(.*)" # Allow access to any path starting with "/pet/" methods: - GET # Allow GET method - POST # Allow POST method
With this security policy applied:
Allowed access:
curl -H "Authorization: Bearer $KEY_AUTH" http://tyk-gw.org/petstore/pet/10 returns a 200 OK response.
curl -H "Authorization: Bearer $KEY_AUTH" http://tyk-gw.org/httpbin/get returns a 200 OK response.
Restricted access:
curl -H "Authorization: Bearer $KEY_AUTH" http://tyk-gw.org/petstore/pet returns a 403 Forbidden response with the message:
Copy
Ask AI
{ "error": "Access to this resource has been disallowed" }
curl -H "Authorization: Bearer $KEY_AUTH" http://tyk-gw.org/httpbin/anything returns a 403 Forbidden response with the message:
Copy
Ask AI
{ "error": "Access to this resource has been disallowed" }
Partitioned policies
Partitioned policies allow you to selectively enforce different segments of a security policy, such as quota, rate limiting, access control lists (ACL), and GraphQL complexity rules. This provides flexibility in applying different security controls as needed.To configure a partitioned policy, set the segments you want to enable in the partitions field:
Copy
Ask AI
apiVersion: tyk.tyk.io/v1alpha1kind: SecurityPolicymetadata: name: partitioned-policy-examplespec: name: Partitioned Policy Example state: active active: true access_rights_array: - name: httpbin # Kubernetes name of referenced API namespace: default # Kubernetes namespace of referenced API kind: ApiDefinition # `ApiDefinition` (Default), `TykOasApiDefinition` or `TykStreamsApiDefinition` versions: - Default # The default version of Tyk Classic API is "Default" - name: petstore namespace: default kind: TykOasApiDefinition # Use `TykOasApiDefinition` if you are referencing Tyk OAS API versions: - "" # The default version of Tyk OAS API is "" partitions: quota: false # Do not enforce quota rules rate_limit: false # Do not enforce rate limiting rules acl: true # Enforce access control rules complexity: false # Do not enforce GraphQL complexity rules
quota: Set to true to enforce quota rules (limits the number of requests allowed over a period).
rate_limit: Set to true to enforce rate limiting rules (limits the number of requests per second or minute).
acl: Set to true to enforce access control rules (controls which APIs or paths can be accessed).
complexity: Set to true to enforce GraphQL complexity rules (limits the complexity of GraphQL queries to prevent resource exhaustion).
If you have existing APIs and Policies running on your Tyk platform, and you want to start using Tyk Operator to manage them, you probably would not want to re-create the APIs and Policies on the platform using Operator CRDs. It is because you will lose keys, policies, and analytics linked to the APIs. You can instead link existing APIs and Policies to a CRD by specifying the API ID or Policy ID in the CRD spec. This way, Operator will update the existing API or Policy according to the CRD spec. Any keys, policies and analytics linked to the API will continue to operate the same. This is great for idempotency.
Instead of creating the API and Policy CRDs from scratch, you can try exporting them from Dashboard using a snapshot tool. You can find the detail usage guide here. This is great if you want to have a quick start. However, this is still a PoC feature so we recommend you to double check the output files before applying them to your cluster.
If there are existing APIs that you want to link to a CRD, it’s very easy to do so. You need to simply add the api_id from your API Definition to the YAML of your ApiDefinition type. Then, the Operator will take care of the rest.Example:
From the existing API Definition, grab the following field:
Copy
Ask AI
"api_id": "5e0fac4845bb46c77543be28300fd9d7"
Simply add this value to your YAML, in the spec.api_idfield:
If you have existing pre-Operator policies, you can easily link them to a CRD, which will allow you to modify them through the YAML moving forward.
Simply set the id field in the SecurityPolicy YAML to the _id field in the existing Policy’s JSON. This will allow the Operator to make the link.
Note that the YAML becomes the source of truth and will overwrite any changes between it and the existing Policy.Example:
Find out your existing Policy ID, e.g. 5f8f3933f56e1a5ffe2cd58c
Stick the policy ID 5f8f3933f56e1a5ffe2cd58c into the YAML’s spec.id field like below
Copy
Ask AI
my-security-policy.yaml:apiVersion: tyk.tyk.io/v1alpha1kind: SecurityPolicymetadata: name: new-httpbin-policyspec: id: 5f8f3933f56e1a5ffe2cd58c name: My New HttpBin Policy state: active active: true access_rights_array: - name: new-httpbin-api # name of your ApiDefinition object. namespace: default # namespace of your ApiDefinition object. versions: - Default
The spec.access_rights_array field of the YAML must refer to the ApiDefinition object that the policy identified by the id will affect.To find available ApiDefinition objects:
Copy
Ask AI
$ kubectl get tykapis -ANAMESPACE NAME DOMAIN LISTENPATH PROXY.TARGETURL ENABLEDdefault new-httpbin-api /httpbin http://httpbin.org true
And then apply this file:
Copy
Ask AI
$ kubectl apply -f my-security-policy.yamlsecuritypolicy.tyk.tyk.io/new-httpbin-policy created
Now the changes in the YAML were applied to the existing Policy. You can now manage this policy through the CRD moving forward.
Note, if this resource is unintentionally deleted, the Operator will recreate it with the same id field as above, allowing keys to continue to work as before the delete event.
Because of the ability to declaratively define the api_id, this gives us the ability to preserve Keys that are tied to APIs or policies which are tied to APIs.
Imagine any use case where you have keys tied to policies, and policies tied to APIs.
Now imagine that these resources are unintentionally destroyed. Our database goes down, or our cluster, or something else.
Well, using the Tyk Operator, we can easily re-generate all our resources in a non-destructive fashion. That’s because the operator intelligently constructs the unique ID using the unique namespaced name of our CRD resources. For that reason.
Alternatively, if you don’t explicitly state it, it will be hard-coded for you by Base64 encoding the namespaced name of the CRD.For example:
we have keys tied to policies tied to APIs in production.
Our production DB gets destroyed, all our Policies and APIs are wiped
The Tyk Operator can resync all the changes from our CRDs into a new environment, by explicitly defining the Policy IDs and API IDs as before.
This allows keys to continue to work normally as Tyk resources are generated idempotently through the Operator.
For Tyk Self Managed or Tyk Cloud, you can set up a Developer Portal to expose a facade of your APIs and then allow third-party developers to register and use your APIs.
You can make use of Tyk Operator CRDs to publish the APIs as part of your CI/CD workflow. If you have followed this Getting Started guide to create the httpbin example API, you can publish it to your Tyk Classic Developer Portal in a few steps.
Currently Operator only supports publishing Tyk Classic API to the Tyk Classic Portal.
When you publish an API to the Portal, Tyk actually publishes a way for developers to enroll in a policy, not into the API directly. Therefore, you should first set up a security policy for the developers, before proceeding with the publishing.To do that, you can use the following command:
The above command will create a basic security policy and attribute it to the httpbin API that was previously created.
Creating an API description
The Tyk Classic Developer Portal enables you to host your API documentation in Swagger/OpenAPI or API Blueprint for developers to use. In the case of Swagger/OpenAPI, you can either paste your Swagger content (JSON or YAML) in the CRD, or via a link to a public Swagger hosted URL, which can then be rendered by using Swagger UI.Create a file called apidesc.yaml, then add the following;
Unlike other platforms, Tyk will not auto-publish your APIs to the Portal, instead they are presented as a facade, you choose what APIs and what Policies to expose to the Portal. You can configure what APIs and what Policies to expose to the Portal via Tyk Operator by creating a PortalAPICatalog resource.Create a file called api_portal.yaml, then add the following:
Now your new API and its documentation is loaded to the Developer Portal.APIDescription CRDDifferent types of documents are supported:Swagger Documents:
In Kubernetes, the Ingress resource defines routing rules for external HTTP/S traffic to services within a cluster, based on domains or paths. An Ingress Controller, like NGINX or HAProxy, interprets these rules and configures the network infrastructure to route traffic, handling SSL termination and load balancing.The Tyk Operator builds upon the idea of Kubernetes Ingress by allowing you to reuse existing Ingress definitions while adding advanced API management features like authentication, rate limiting, and monitoring. This approach provides seamless ingress traffic management with powerful API gateway capabilities in a unified solution.
When you use Tyk Operator as an Ingress Controller, each “path” defined in your existing Ingress resource is treated as an “API” within Tyk.Using this Ingress spec as example:
"13-13", "15-24"],linenos=true}
Copy
Ask AI
apiVersion: networking.k8s.io/v1kind: Ingressmetadata: name: httpbin-ingress annotations: kubernetes.io/ingress.class: tyk # Specify Tyk as Ingress Controller tyk.io/template: myapideftemplate # The metadata name of the ApiDefinition or TykOasApiDefinition resource in the same namespace tyk.io/template-kind: ApiDefinition # Can be "ApiDefinition" (Default) or "TykOasApiDefinition"spec: tls: - hosts: - myingress.do.poc.tyk.technology secretName: httpbin-ingress-tls rules: - host: myingress.do.poc.tyk.technology http: paths: - path: /httpbin # Corresponds to API listen path pathType: Prefix backend: # Corresponds to upstream URL service: name: httpbin port: number: 8000
Here’s how it works:
Path Mapping: Tyk Operator will automatically create APIs in Tyk for each path for a specific rule defined in Ingress resource. Just as with traditional Ingress, incoming requests are routed to the correct backend service within the cluster based on the host and paths defined in the Ingress rules.In the given example, Tyk Operator is designated as the Ingress Controller for this Ingress resource. Tyk Operator reads this Ingress definition and automatically creates a corresponding API in the Tyk Gateway. The API will have:
A custom domain set to myingress.do.poc.tyk.technology, as defined by the host field in the Ingress rule.
The TLS certificate from secret httpbin-ingress-tls uploaded to Tyk and certificates field set to the resulting certificate ID.
A listen path set to /httpbin, which is defined by the path field in the Ingress rule.
An upstream URL set to http://httpbin.default.svc:8000, which corresponds to the backend service defined in the Ingress (httpbin service running on port 8000).
API Management Through Tyk: At the same time, Tyk allows you to apply API management features by referencing a configuration template. This template is defined using either an ApiDefinition or TykOasApiDefinition resource. These resources provide a reference configuration that includes details on how the API should be managed, such as security policies, traffic controls, and transformations.In the given example, there are two important annotations in the Ingress metadata:
These annotations specify that Tyk Operator should use a resource named myapideftemplate in the same namespace as the reference for API configuration. The tyk.io/template-kind annotation indicates that this reference is of type ApiDefinition. Alternatively, it could be a TykOasApiDefinition, depending on the user’s choice. Tyk Operator detects these annotations and looks for the specified resource in the same namespace. For each path defined in the Ingress, Tyk Operator creates a corresponding API in Tyk by copying the specification from myapideftemplate resource (such as authentication type, rate limiting, etc.) and then updates only the relevant fields like custom domain, certificates, listen path, and upstream URL based on the Ingress spec.Note that ApiDefinition or TykOasApiDefinition created for use as a template for Ingress resources should have a special label set so that Tyk Operator would not manage it as ordinary APIs. Here is the required label for ApiDefinition and TykOasApiDefinition respectively:Label for ApiDefinition indicating it is a resource template.
Copy
Ask AI
labels: template: "true"
Label for TykOasApiDefinition indicating it is a resource template.
Copy
Ask AI
labels: tyk.io/ingress-template: "true"
Note that use of TykStreamsApiDefinition as resource template is not supported.
Automated Resource Handling: Tyk Operator handles the automatic discovery and management of existing Ingress resources, eliminating the need for manual migration of all Ingress rules into API definitions. You can simply define an API configuration template as a TykOasApiDefinition resource or ApiDefinition resource and then let Tyk Operator creates all the APIs from your existing Ingress rules using the referenced resource as template, streamlining the transition process.Additionally, the Tyk Operator also handles any changes to the Ingress resources it manages. If an Ingress resource is updated — whether through the addition, removal, or modification of paths in the Ingress rules — Tyk Operator automatically reconfigures the corresponding Tyk APIs to ensure they remain in sync with the updated Ingress configuration. This dynamic updating capability ensures that your API management remains consistent and up-to-date with the latest changes in your Kubernetes environment.
This approach enables you to quickly and easily integrate advanced API management functionalities into your existing Kubernetes environment without needing to change your current configurations significantly.
To configure Tyk Operator to handle Ingress resources, specify ingress class as tyk in the Ingress resource. You can also optionally create a ApiDefinition or TykOasApiDefinition resource template that provides default API configurations. This allows Tyk Operator to read the Ingress resource and create API Definition resources based on ingress path and referenced template.The following sections shows some example of Tyk ApiDefinition or TykOasApiTemplate template and Ingress specification.
apiVersion: networking.k8s.io/v1kind: Ingressmetadata: name: httpbin-ingress annotations: kubernetes.io/ingress.class: tyk # <----------------- REFERENCES TYK INGRESS CONTROLLERspec: rules: - host: httpbin.ahmet http: paths: - path: / # host routing: http://httpbin.ahmet/ pathType: Prefix backend: service: name: httpbin1 port: number: 8000 - path: /httpbin # host + path routing: http://httpbin.ahmet/httpbin pathType: Prefix backend: service: name: httpbin2 port: number: 8000 - http: paths: - path: /pathonly # path only routing: http://IPADDRESS/pathonly pathType: Prefix backend: service: name: httpbin3 port: number: 8000 - host: "*.foo.com" # wildcard # curl http://bar.foo.com/httpbin/get === OK Matches based on shared suffix # curl http://baz.bar.foo.com/httpbin/get === NOK No match, wildcard only covers a single DNS label # curl http://foo.com/httpbin/get === NOK No match, wildcard only covers a single DNS label http: paths: - path: /httpbin pathType: Prefix backend: service: name: httpbin4 port: number: 8000
In this example, 4 APIs will be created by Tyk Operator. It illustrates how different Ingress rules: host based routing, path based routing, host + path based routing, and wildcard hosts are handled by Tyk Operator.
apiVersion: networking.k8s.io/v1kind: Ingressmetadata: name: httpbin-ingress-tls annotations: kubernetes.io/ingress.class: tyk # <----------------- REFERENCES TYK INGRESS CONTROLLER cert-manager.io/cluster-issuer: "letsencrypt-staging" # this annotation indicates the issuer to use. acme.cert-manager.io/http01-edit-in-place: "true"spec: tls: - hosts: # < placing a host in the TLS config will determine what ends up in the cert's subjectAltNames - myingress.do.poc.tyk.technology secretName: httpbin-ingress-tls-secret # < cert-manager will store the created certificate in this secret. rules: - host: myingress.do.poc.tyk.technology http: paths: - path: /httpbin pathType: Prefix backend: service: name: httpbin port: number: 8000---apiVersion: cert-manager.io/v1kind: ClusterIssuermetadata: name: letsencrypt-stagingspec: acme: server: https://acme-staging-v02.api.letsencrypt.org/directory email: ahmet@tyk.io privateKeySecretRef: name: letsencrypt-staging solvers: - http01: ingress: class: tyk---apiVersion: v1kind: Servicemetadata: name: ingress-gateway namespace: tykspec: ports: - name: http targetPort: 8000 port: 80 protocol: TCP - name: https targetPort: 443 port: 443 protocol: TCP selector: app: gateway-tyk-stack-tyk-gateway type: LoadBalancer externalTrafficPolicy: Local
A common use-case for cert-manager is requesting TLS signed certificates to secure your ingress resources. This can be done by simply adding annotations, such as cert-manager.io/cluster-issuer, to your Ingress resources and cert-manager will facilitate creating the Certificate resource for you.In this example, cert-manager watches the ingress resource httpbin-ingress-tls and ensures a TLS secret named httpbin-ingress-tls-secret (provided by the tls.secretName field) in the same namespace will be created and configured as described on the Ingress. This example also exposes Tyk Gateway as a LoadBalancer service with the ingress-gateway resource. This is essential for completing the ACME challenge from Let’s Encrypt.With this configuration, Tyk Gateway can serve HTTPS requests via port 443, with a TLS certificate provisioned by cert-manager. An API is created by Tyk Operator to serve the ingress traffic at https://myingress.do.poc.tyk.technology/httpbin, and forwards the request to http://httpbin.default.svc:8000 within the cluster.
apiVersion: tyk.tyk.io/v1alpha1kind: ApiDefinitionmetadata: name: myapideftemplate labels: template: "true" # Instructs Tyk Operator to skip reconciliation for this resourcespec: name: foo protocol: http use_keyless: true proxy: target_url: http://example.com
This example defines an ApiDefinition resource that can be used as configuration template for APIs created for Ingresses. It has a label template: "true" which let Tyk Operator knows that it is not a real resource, and hence does not require reconciliation. This will allow the ApiDefinition to be stored inside Kubernetes as a resource, but will not reconcile the ApiDefinition inside Tyk. All mandatory fields inside the ApiDefinition spec are still mandatory, but can be replaced with placeholders as they will be overwritten by the Ingress reconciler.
Copy
Ask AI
apiVersion: networking.k8s.io/v1kind: Ingressmetadata: name: my-ingress annotations: kubernetes.io/ingress.class: tyk # <----------------- REFERENCES TYK INGRESS CONTROLLER tyk.io/template: myapideftemplate # The metadata name of the ApiDefinition or TykOasApiDefinition resource in the same namespace tyk.io/template-kind: ApiDefinition # Can be "ApiDefinition" (Default) or "TykOasApiDefinition"...
To make use of the ApiDefinition template, make sure to add annotations tyk.io/template and tyk.io/template-kind to your Ingress resource. Here, we specify that the template to be used is named “myapideftemplate”, and the resource represents a Tyk Classic API “ApiDefinition”.
Here provides a minimum template as TykOasApiDefinition. The TykOasApiDefinition must have a label tyk.io/ingress-template: "true" so that Tyk Operator will not reconcile it with Tyk.
Copy
Ask AI
apiVersion: networking.k8s.io/v1kind: Ingressmetadata: name: my-ingress annotations: kubernetes.io/ingress.class: tyk # <----------------- REFERENCES TYK INGRESS CONTROLLER tyk.io/template: oasapitemplate # The metadata name of the ApiDefinition or TykOasApiDefinition resource in the same namespace tyk.io/template-kind: TykOasApiDefinition # Can be "ApiDefinition" (Default) or "TykOasApiDefinition"...
To make use of the TykOasApiDefinition template, make sure to add annotations tyk.io/template and tyk.io/template-kind to your Ingress resource. Here, we specify that the template to be used is named “oasapitemplate”, and the resource represents a Tyk OAS API “TykOasApiDefinition”.
The value of the kubernetes.io/ingress.class annotation identifies the IngressClass that will process Ingress objects.Tyk Operator by default looks for the value tyk and will ignore all other ingress classes. If you wish to override this default behavior,
you may do so by setting the environment variable WATCH_INGRESS_CLASS in the operator manager deployment. See Installing Tyk Operator for further information.
Tyk Ingress Controller will create APIs in Tyk for each path defined for a specific rule in Ingress resource. Each API created inside Tyk will follow a special naming convention as follows:
For example, the following ingress resource will create an ApiDefinition called default-httpbin-ingress-78acd160d inside Tyk’s Gateway.
ApiDefinition’s name comes from:
default: The namespace of this Ingress resource,
httpbin-ingress: The name of this Ingress resource,
78acd160d: Short hash (first 9 characters) of Host ("") and Path (/httpbin). The hash algorithm is SHA256.
Each path in an Ingress must have its own particular path type. Kubernetes offers three types of path types: ImplementationSpecific, Exact, and Prefix. Currently, not all path types are supported. The below table shows the unsupported path types for Sample HTTP Ingress Resource based on the examples in the Kubernetes Ingress documentation.
Kind
Path(s)
Request path(s)
Expected to match?
Works as Expected
Exact
/foo
/foo/
No
No.
Prefix
/foo/
/foo, /foo/
Yes
No, /foo/ matches, /foo does not match.
Prefix
/aaa/bb
/aaa/bbb
No
No, the request forwarded to service.
Prefix
/aaa/bbb/
/aaa/bbb
Yes, ignores trailing slash
No, /aaa/bbb does not match.
Prefix
/aaa/bbb
/aaa/bbbxyz
No, does not match string prefix
No, the request forwarded to service.
Please bear in mind that if proxy.strip_listen_path is set to true on API Definition, Tyk strips the listen-path (for example, the listen-path for the Ingress under Sample HTTP Ingress Resource is /httpbin) with an empty string.The following table shows an example of path matching if the listen-path is set to /httpbin or /httpbin/.
Kind
Path(s)
Request path(s)
Matches?
Exact
/httpbin
/httpbin, /httpbin/
Yes. The request forwarded as / to your service.
Prefix
/httpbin
/httpbin, /httpbin/
Yes. The request forwarded as / to your service.
ImplementationSpecific
/httpbin
/httpbin, /httpbin/
Yes. The request forwarded as / to your service.
Exact
/httpbin
/httpbinget, /httpbin/get
Yes. The request forwarded as /get to your service.
Prefix
/httpbin
/httpbinget, /httpbin/get
Yes. The request forwarded as /get to your service.
ImplementationSpecific
/httpbin
/httpbinget, /httpbin/get
Yes. The request forwarded as /get to your service.
Exact
/httpbin/
/httpbin/, /httpbin/get
Yes. The request forwarded as /get to your service.
Prefix
/httpbin/
/httpbin/, /httpbin/get
Yes. The request forwarded as /get to your service.
ImplementationSpecific
/httpbin/
/httpbin/, /httpbin/get
Yes. The request forwarded as /get to your service.
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.
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 and SuperGraph, that allows users to model the relationship between Subgraphs and Supergraphs.
apiVersion: tyk.tyk.io/v1alpha1kind: SubGraphmetadata: name: users-subgraphspec: schema: | <Schema of your SubGraph> sdl: | <SDL of the SubGraph>
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:
apiVersion: tyk.tyk.io/v1alpha1kind: SuperGraphmetadata: name: social-media-supergraphspec: subgraph_refs: - name: users-subgraph namespace: default schema: |- <Schema of your Supergraph>
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:
Copy
Ask AI
apiVersion: tyk.tyk.io/v1alpha1kind: ApiDefinitionmetadata: name: federation-supergraphspec: 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.
ApiDefinition and SuperGraph must be in the same namespace,
graphql.execution_mode must be set to supergraph,
graphql.graph_ref must be set to the metdata name of the SuperGraph resource that you would like to refer.
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.
Let’s assume that a developer responsible for the Users SubGraph would like to delete username field from the Users SubGraph.
Also, the Supergraph 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:
Update Users SubGraph CRD,
Update Social Media Supergraph ApiDefinition since it is referencing the Users SubGraph CRD.
SubGraph without any referenceIf the subgraph is not referenced in any ApiDefinition CRD or SuperGraph CRD, it is easy to delete SubGraph CRDs as follows:
SubGraph referenced in ApiDefinitionIf 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 SuperGraphAlthough 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.
SuperGraph referenced in ApiDefinitionIf 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.
Using Tyk Classic APIs, developers can implement API-level custom plugins that can be optionally setup to execute for
each of the following hooks in the API request
lifecycle: Pre (Request), Authentication,
Post (Request), Post
Authentication, Response
and Analytics. 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 to learn how to configure Analytics
plugins using Tyk Operator.
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:
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 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.
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 level plugins are not currently
supported by Tyk Operator.
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.
Implement PluginThe first step is to create the plugin source code.
Copy
Ask AI
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
Create API Definition ResourceThe example API Definition resource listed below listens on path /httpbin and forwards requests to upstream
http://httpbin.org.
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.
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 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:
Copy
Ask AI
$ kubectl apply -f path_to_your_apidefinition.yamlapidefinition.tyk.tyk.io/httpbin created
Test PluginWe can test that our plugin injects a Hello header with a corresponding value of World by using the curl command:
Configure Custom Plugins (Python) using plugin bundles via Tyk Operator
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.For a detailed guide, check out our blog post
How to Deploy Python Plugins in Tyk Running on Kubernetes,
which walks you through all the steps required to create Python plugin
bundles, load them into the Tyk Gateway, and configure an API
Definition to use them with the Tyk Operator.
If you want to set up multi-tenant API management with Tyk, follow these steps to define an OperatorContext for connecting and authenticating with a Tyk Dashboard and reference it in your API definitions for specific configurations.
An OperatorContext specifies the parameters for connecting and authenticating with a Tyk Dashboard. Below is an example of how to define an OperatorContext:
Copy
Ask AI
apiVersion: tyk.tyk.io/v1alpha1kind: OperatorContextmetadata: name: team-alpha namespace: defaultspec: env: # The mode of the admin api # ce - community edition (open source gateway) # pro - dashboard (requires a license) mode: pro # Org ID to use org: *YOUR_ORGANIZATION_ID* # The authorization token this will be set in x-tyk-authorization header on the # client while talking to the admin api auth: *YOUR_API_ACCESS_KEY* # The url to the Tyk Dashboard API url: http://dashboard.tyk.svc.cluster.local:3000 # Set this to true if you want to skip tls certificate and host name verification # this should only be used in testing insecureSkipVerify: true # For ingress the operator creates and manages ApiDefinition resources, use this to configure # which ports the ApiDefinition resources managed by the ingress controller binds to. # Use this to override default ingress http and https port ingress: httpPort: 8000 httpsPort: 8443
For better security, you can also replace sensitive data with values contained within a referenced secret with .spec.secretRef.In this example, API access key auth and organization ID org are not specified in the manifest. They are provided through a Kubernetes secret named tyk-operator-conf in alpha namespace. The secret contains keys TYK_AUTH and TYK_ORG which correspond to the auth and org fields respectively.
You can provide the following fields through secret as referenced by secretRef. The table shows mappings between .spec.env properties and secret .spec.data keys. If a value is configured in both the secret and OperatorContext spec.env field, the value from secret will take precedence.
The concept of internal 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://<API_ID>/<path> 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_IDs by its Kubernetes metedata name and namespace.
Configuring looping to internal ApiDefinition resources
Looping can be configured within Tyk Operator for URL Rewrites, URL Rewrite Triggers and 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://<API_ID>/<path>. 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 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:
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:
Copy
Ask AI
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.
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.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:
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:
Copy
Ask AI
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.
Internal looping can also be used for proxying to internal APIs.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:
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:
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:
Entry Point API
BasicAuth Internal API
AuthToken Internal API
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.
There are no actual HTTP redirects in this scenario, meaning that there is no performance penalty in performing any of these Internal Redirects.
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.comWe 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/<path>.
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/<path>.
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.
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.
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.
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:
Copy
Ask AI
apiVersion: tyk.tyk.io/v1alpha1kind: ApiDefinitionmetadata: name: example-api # This is the metadata name of the Kubernetes resourcespec: 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
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.
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 x-tyk-api-gateway.info.id field in Tyk OAS API Definition object.
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
For a Tyk Classic API, you can specify the category name using the name field with a # qualifier. This will categorize the API in the Tyk Dashboard. See How API categories work to learn about limitations on API names.Example
In the Tyk OAS API Definition, versioning can be configured via x-tyk-api-gateway.versioning object of the Base API, where the child API’s IDs are specified. In the Kubernetes environment with Tyk Operator, where we reference API resources through its Kubernetes name and namespace, this is not desired. Therefore, we add support for versioning configurations through the field versioning in TykOasApiDefinition custom resource definition (CRD).Here’s an example:
In this example, two different versions of an API are defined: order-api (v1) and order-api-v2 (v2).versioning is configured at order-api (v1), the Base API, and it has similiar structure as Tyk OAS API Definition:
versioning: This object configures API versioning for the order-api.
enabled: Set to true to enable versioning.
name: an identifier for this version of the API (v1).
default: Specifies the default version (v1), which will be used if no version is specified in the request.
location: Specifies where the version key is expected (in this case, in the header). It can be set to header or url-param.
key: Specifies the versioning identifier key (x-api-version) to identify the version. In this example, the version is determined by an HTTP header named x-api-version.
fallbackToDefault: When set to true, if an unspecified or invalid version is requested, the default version (v1) will be used.
stripVersioningData: When true, removes versioning identifier (like headers or query parameters) from the upstream request to avoid exposing internal versioning details.
urlVersioningPattern: Specifies a regex that matches the format that you use for the versioning identifier (name) if you are using stripVersioningData and fallBackToDefault with location=url with Tyk 5.5.0 or later
versions: Defines the list of API versions available:
name: an identifier for this version of the API (v2).
tykOasApiDefinitionRef: Refers to a separate TykOasApiDefinition resource that represent a new API version.
name: Kubernetes metadata name of the resource (order-api-v2).
namespace: Kubernetes metadata namespace of the resource (default).
With Tyk Operator, you can easily associate different versions of your APIs using their Kubernetes names. This eliminates the need to include versioning information directly within the base API’s definition (x-tyk-api-gateway.versioning object), which typically requires referencing specific API IDs. Instead, the Operator allows you to manage versioning declaratively in the TykOasApiDefinition CRD, using the versioning field to specify versions and their Kubernetes references (names and namespaces).When using the CRD for versioning configuration, you don’t have to worry about knowing or managing the unique API IDs within Tyk. The Tyk Operator handles the actual API definition configuration behind the scenes, reducing the complexity of version management.In case if there is original versioning information in the base API Definition, the versioning information will be kept and be merged with what is specified in CRD. If there are conflicts between the Tyk OAS API Definition and CRD, we will make use of CRD values as the final configuration.Tyk Operator would also protect you from accidentally deleting a version of an API that is being referenced by another API, maintaining your API integrity.
Configuring API Version in Tyk Streams API Definition
As of Tyk Operator v1.1, API versioning is not supported in TykStreamsApiDefinition CRD. This can be configured natively in the Tyk Streams API Definition.
Configuring API Version in Tyk Classic API Definition
For Tyk Classic API, versioning can be configured via ApiDefinition custom resource definition (CRD). See Tyk Classic versioning for a comprehensive example of configuring API versioning for Tyk Classic API with Tyk Operator.
Please consult the API Ownership documentation for the fundamental concepts of API Ownership in Tyk and Operator Context documentation for an overview of the use of OperatorContext to manage resources for different teams effectively.The guide includes practical examples for managing API ownership via OperatorContext. Key topics include defining user owners and user group owners in OperatorContext for connecting and authenticating with a Tyk Dashboard, and using contextRef in TykOasApiDefinition or ApiDefinition objects to ensure configurations are applied within specific organizations. The provided YAML examples illustrate how to set up these configurations.
In Tyk Dashboard, API Ownership ensures that only designated ‘users’ who own an API can modify it. This security model is crucial for maintaining control over API configurations, especially in a multi-tenant environment where multiple teams or departments may have different responsibilities and permissions.Tyk Operator is designed to interact with Tyk Dashboard as a system user. For the Tyk Dashboard, Tyk Operator is just another user that must adhere to the same access controls and permissions as any other user. This means:
Tyk Operator needs the correct access rights to modify any APIs.
It must be capable of managing APIs according to the ownership rules set in Tyk Dashboard.
To facilitate API ownership and ensure secure operations, Tyk Operator must be able to ‘impersonate’ different users for API operations. This is where OperatorContext comes into play. Users can define different OperatorContext objects that act as different agents to connect to Tyk Dashboard. Each OperatorContext can specify different access parameters, including the user access key and organization it belongs to. Within OperatorContext, users can specify the IDs of owner users or owner user groups. All APIs managed through that OperatorContext will be owned by the specified users and user groups, ensuring compliance with Tyk Dashboard’s API ownership model.
Here’s how OperatorContext allows Tyk Operator to manage APIs under different ownerships:
Copy
Ask AI
apiVersion: tyk.tyk.io/v1alpha1kind: OperatorContextmetadata: name: team-alpha namespace: defaultspec: env: # The mode of the admin api # ce - community edition (open source gateway) # pro - dashboard (requires a license) mode: pro # Org ID to use org: *YOUR_ORGANIZATION_ID* # The authorization token this will be set in x-tyk-authorization header on the # client while talking to the admin api auth: *YOUR_API_ACCESS_KEY* # The url to the Tyk Dashboard API url: http://dashboard.tyk.svc.cluster.local:3000 # Set this to true if you want to skip tls certificate and host name verification # this should only be used in testing insecureSkipVerify: true # For ingress the operator creates and manages ApiDefinition resources, use this to configure # which ports the ApiDefinition resources managed by the ingress controller binds to. # Use this to override default ingress http and https port ingress: httpPort: 8000 httpsPort: 8443 # Optional - The list of users who are authorized to update/delete the API. # The user pointed by auth needs to be in this list, if not empty. user_owners: - a1b2c3d4e5f6 # Optional - The list of groups of users who are authorized to update/delete the API. # The user pointed by auth needs to be a member of one of the groups in this list, if not empty. user_group_owners: - 1a2b3c4d5e6f
Once an OperatorContext is defined, you can reference it in your Tyk OAS or Tyk Streams API Definition objects using contextRef. Below is an example with TykOasApiDefinition:
In this example, the TykOasApiDefinition object references the team-alpha context, ensuring that it is managed under the ownership of the specified users and user groups.
In this example, the ApiDefinition object references the team-alpha context, ensuring that it is managed under the ownership of the specified users and user groups.
Can I use Tyk Operator with non-Kubernetes Tyk installations?
While Tyk Operator is designed to work within a Kubernetes environment, you can still use it to manage non-Kubernetes Tyk installations. You’ll need to:
Run Tyk Operator in a Kubernetes cluster.
Configure Tyk Operator to point to your external Tyk installation, e.g. via tyk-operator-conf, environment variable, or OperatorContext:
Copy
Ask AI
TYK_MODE: pro TYK_URL: http://external-tyk-dashboard TYK_AUTH: api-access-key TYK_ORG: org-id
This allows you to manage your external Tyk installation using Kubernetes resources.
From Tyk Operator v0.15.0, we introduce a new status subresource in APIDefinition CRD, called latestTransaction which holds information about reconciliation status.
The Status subresource in Kubernetes is a specialized endpoint that allows developers and operators to retrieve the real-time status of a specific Kubernetes resource. By querying this subresource, users can efficiently access essential information about a resource’s current state, conditions, and other relevant details without fetching the entire resource, simplifying monitoring and aiding in prompt decision-making and issue resolution.
The new status subresource latestTransaction consists of a couple of fields that show the latest result of the reconciliation:
.status.latestTransaction.status: shows the status of the latest reconciliation, either Successful or Failed;
.status.latestTransaction.time: shows the time of the latest reconciliation;
.status.latestTransaction.error: shows the message of an error if observed in the latest transaction.
Example: Find out why an APIDefinition resource cannot be deleted
Consider the scenario when APIDefinition and SecurityPolicy are connected. Usually, APIDefinition cannot be deleted directly since it is protected by SecurityPolicy. The proper approach to remove an APIDefinition is to first remove the reference to the SecurityPolicy (either by deleting the SecurityPolicy CR or updating SecurityPolicy CR’s specification), and then remove the APIDefinition itself. However, if we directly delete this APIDefinition, Tyk Operator won’t delete the APIDefinition unless the link between SecurityPolicy and APIDefinition is removed. It is to protect the referential integrity between your resources.
After deleting APIDefinition, the operation hangs, and we suspect that something is wrong.
Users might still look through the logs to comprehend the issue, as they did in the past, but they can now examine their APIDefinition’s status subresource to make their initial, speedy issue diagnosis.
Copy
Ask AI
$ kubectl get tykapis httpbin NAME DOMAIN LISTENPATH PROXY.TARGETURL ENABLED STATUShttpbin /httpbin http://httpbin.org true Failed
As seen in the STATUS column, something went wrong, and the STATUS is Failed.To get more information about the APIDefinition resource, we can use kubectl describe or kubectl get:
$ kubectl get tykapis httpbin -o json | jq .status.latestTransaction{ "error": "unable to delete api due to security policy dependency=default/httpbin", "status": "Failed", "time": "2023-07-18T07:26:45Z"}
Instead of digging into Tyk Operator’s logs, we can now diagnose this issue simply by looking at the .status.latestTransaction field. As .status.latestTransaction.error implies, the error is related to SecurityPolicy dependency.
Tyk stores API configurations as JSON objects called API Definitions. If you are using Tyk Dashboard to manage Tyk, then these are stored in either Postgres or MongoDB, as specified in the database settings. On the other hand, if you are using Tyk OSS, these configurations are stored as files in the /apps directory of the Gateway which is located at the default path /opt/tyk-gateway.An API definition includes various settings and middleware that control how incoming requests are processed.
API Types
Tyk supports various API types, including HTTP, HTTPS, TCP, TLS, and GraphQL. It also includes Universal Data Graph versions for unified data access and federation, allowing seamless querying across multiple services.
Type
Support
Supported From
Comments
HTTP
✅
v0.1
Standard HTTP proxy for API requests.
HTTPS
✅
v0.4
Secure HTTP proxy using SSL/TLS encryption.
TCP
✅
v0.1
Handles raw TCP traffic, useful for non-HTTP APIs.
TLS
✅
v0.1
Handles encrypted TLS traffic for secure communication.
GraphQL - Proxy
✅
v0.1
Proxy for GraphQL APIs, routing queries to the appropriate service.
Universal Data Graph v1
✅
v0.1
Supports Universal Data Graph v1 for unified data access.
Universal Data Graph v2
✅
v0.12
Supports the newer Universal Data Graph v2 for more advanced data handling.
GraphQL - Federation
✅
v0.12
Supports GraphQL Federation for querying multiple services as one API.
Management of APIs
Tyk offers flexible API management features such as setting active/inactive status, categorizing and naming APIs, versioning, and defining ownership within teams or organizations for streamlined administration.
Type
Support
Supported From
Comments
API Name
✅
v0.1
Assign and manage names for your APIs.
API Status (inactive/active)
✅
v0.2
Toggle API status between active and inactive.
API Categories
✅
v0.1
Categorize APIs for easier management.
API ID
✅
v0.1
Assign unique IDs to APIs for tracking and management.
API Ownership
✅
v0.12
Define ownership of APIs within teams or organizations.
API Versioning
✅
v0.1
Enable version control for APIs.
Traffic Routing
Tyk enables traffic routing through path-based or host-based proxies and allows redirection to specific target URLs, providing control over how requests are directed to backend services.
Type
Supported
Supported From
Comments
Path-Based Proxy
✅
v0.1
Route traffic based on URL path.
Host-Based Proxy
✅
v0.1
Route traffic based on the request host.
Target URL
✅
v0.1
Redirect traffic to a specific target URL.
Client to Gateway Authentication and Authorization
Tyk provides multiple authentication options for client-to-gateway interactions, including keyless access, JWT, client mTLS, IP allow/block lists, and custom authentication plugins for enhanced security.
Type
Supported
Supported From
Comments
Keyless
✅
v0.1
No authentication required, open access.
Auth Token
✅
v0.1
Requires an authentication token (Bearer token).
JWT
✅️
v0.5
Uses JSON Web Tokens for secure authentication.
OpenID Connect
❌
-
Recommended to use JWT for OIDC authentication.
OAuth2
❌
-
OAuth2 not supported, JWT is recommended.
Client mTLS
✅
v0.11
Supports static client mutual TLS authentication.
HMAC
❌
-
HMAC authentication is not implemented.
Basic Authentication
✅
v0.12
Only supports enabling with default metadata.
Custom Authentication Plugin (Go)
✅
v0.11
Custom authentication plugin written in Go.
Custom Authentication Plugin (gRPC)
✅
v0.1
Custom authentication plugin using gRPC.
Multiple Authentication
✅
v0.14
Chain multiple authentication methods.
IP Allowlist
✅
v0.5
Allows access only from specific IP addresses.
IP Blocklist
✅
v0.5
Blocks access from specific IP addresses.
Gateway to Upstream Authentication
Tyk supports secure upstream connections through mutual TLS, certificate pinning, and public key verification to ensure data integrity between the gateway and backend services. For full details, please see the Upstream Authentication section.
Type
Supported
Supported From
Mutual TLS for upstream connectioons
✅
v0.9
Mutual TLS authentication for upstream connections.
Public Key Certificate Pinning
✅
v0.9
Ensures that the upstream certificate matches a known key.
Upstream Request Signing using HMAC
✅
v1.2.0
Attach an encrypted signature to requests to verify the gateway as the sender.
API-level (Global) Features
Tyk offers global features for APIs, such as detailed traffic logging, CORS management, rate limiting, header transformations, and analytics plugins, with support for tagging, load balancing, and dynamic variables.
Feature
Supported
Supported From
Comments
Detailed recording (in Log Browser)
✅
v0.4.0
Records detailed API traffic logs for analysis.
Config Data
✅
v0.8.2
Stores additional configuration data for APIs.
Context Variables
✅
v0.1
Enables dynamic context-based variables in APIs.
Cross Origin Resource Sharing (CORS)
✅
v0.2
Manages CORS settings for cross-domain requests.
Service Discovery
⚠️
-
Service discovery is untested in this version.
Segment Tags
✅
v0.1
Tags APIs for segmentation across environments.
Internal API (not exposed by Gateway)
✅
v0.6.0
Internal APIs are not exposed via the Gateway.
Global (API-level) Header Transform
✅
v0.1.0
Transforms request and response headers at the API level.
Global (API-level) Rate Limit
✅
v0.10
Sets rate limits globally for APIs.
Custom Plugins
✅
v0.1
Supports the use of custom plugins for API processing.
Analytics Plugin
✅
v0.16.0
Integrates analytics plugins for API monitoring.
Batch Requests
❌
-
Batch requests are not supported.
Custom Analytics Tags (Tag Headers)
✅
v0.10.0
Custom tags for API analytics data.
Expire Analytics After
❌
-
Not supported in this version.
Do not track Analytics (per API)
✅
v0.1.0
Disable analytics tracking on specific APIs.
Webhooks
❌
-
Webhook support is not available.
Looping
✅
v0.6
Enables internal looping of API requests.
Round Robin Load Balancing
✅
-
Supports round-robin load balancing across upstream servers.
Endpoint-level Features
For specific API endpoints, Tyk includes features like caching, circuit breaking, request validation, URL rewriting, and response transformations, allowing for precise control over request processing and response handling at an endpoint level.
The TykOasApiDefinition Custom Resource Definition (CRD) manages Tyk OAS API Definition objects within a Kubernetes environment. This CRD enables the integration and management of Tyk API definitions using Kubernetes-native tools, simplifying the process of deploying and managing OAS APIs on the Tyk Dashboard.
TykOasApiDefinition Features
TykOasApiDefinition can support all features of the Tyk OAS API definition. You just need to provide the Tyk OAS API definition via a ConfigMap. In addition to managing the CRUD (Create, Read, Update, Delete) of Tyk OAS API resources, the Tyk Operator helps you better manage resources through object linking to Ingress, Security Policies, and certificates stored as Kubernetes secrets. See below for a list of Operator features and examples:
The TykStreamsApiDefinition Custom Resource Definition (CRD) manages Async API configuration within a Kubernetes environment.
TykStreamsApiDefinition Features
TykStreamsApiDefinition can support all features of Tyk Streams. You just need to provide the Tyk Streams API definition via a ConfigMap. In addition to managing the CRUD (Create, Read, Update, Delete) of Tyk Streams API resources, the Tyk Operator helps you better manage resources through object linking to Security Policies. See below for a list of Operator features and examples:
Ensuring compatibility between different versions is crucial for maintaining stable and efficient operations. This document provides a comprehensive compatibility matrix for Tyk Operator with various versions of Tyk and Kubernetes. By understanding these compatibility details, you can make informed decisions about which versions to deploy in your environment, ensuring that you leverage the latest features and maintain backward compatibility where necessary.
Compatibility with Tyk
Tyk Operator can work with all version of Tyk beyond Tyk 3.x+. Since Tyk is backward compatible, you can safely use the
latest version of Tyk Operator to work with any version of Tyk.
However, if you’re using a feature that was not yet available on an earlier version of Tyk, e.g. Defining a Subgraph with Tyk 3.x, you’ll see error in Tyk Operator controller manager logs.See Release notes to check for each Tyk Operator release,
which version of Tyk it is tested against.
Tyk Version
3.2
4.0
4.1
4.2
4.3
5.0
5.2
5.3
5.4
5.5
5.6
5.7
Tyk Operator v0.13
Y
Y
Tyk Operator v0.14
Y
Y
Y
Y
Tyk Operator v0.14.1
Y
Y
Y
Y
Tyk Operator v0.15.0
Y
Y
Y
Y
Tyk Operator v0.15.1
Y
Y
Y
Y
Tyk Operator v0.16.0
Y
Y
Y
Y
Y
Tyk Operator v0.17.0
Y
Y
Y
Y
Y
Y
Tyk Operator v0.17.1
Y
Y
Y
Y
Y
Tyk Operator v0.18.0
Y
Y
Y
Y
Y
Y
Tyk Operator v1.0.0
Y
Y
Y
Y
Y
Y
Tyk Operator v1.1.0
Y
Y
Y
Y
Y
Y
Y
Compatibility with Kubernetes Version
See Release notes to check for each Tyk Operator release,
which version of Kubernetes it is tested against.
