Tyk Operator - API Management in Kubernetes

Introduction

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.

What is Tyk Operator?

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.

Key Concepts

GitOps With Tyk

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.

What is GitOps?

“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.

Tyk Operator in your GitOps 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.

Single Source of Truth for API Configurations

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:

• GitOps-enabled API management in Kubernetes
• A practical guide using Tyk Operator, ArgoCD, and Kustomize

Custom Resources in Tyk

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.

Custom Resources for API and Policy Configuration

The following custom resources can be used to configure APIs and policies at Tyk Gateway or Tyk Dashboard.

Tyk Classic Developer Portal

The following custom resources can be used to configure Tyk Classic Developer Portal.

Reconciliation With Tyk Operator

Controllers & Operators

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.

Desired State vs Observed State

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

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.

CRD Versioning

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.

Operator User

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).

These would be the default credentials Tyk Operator uses to connect to Tyk.

Multi-tenancy in 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.

Example Scenarios Using OperatorContext

1. No OperatorContext Defined

   • 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.

2. 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.

3. 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.

TLS Certificates

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.

Benefits of Managing Certificates with Tyk Operator

• Reduced operational overhead: Automates the process of updating certificates when they rotate.
• Minimized risk of API downtime: Ensures that APIs continue to function smoothly, even when certificates are updated.
• Improved developer experience: Removes the need for API developers to manage certificate IDs manually.

Examples

What Features Are Supported By Tyk Operator?

APIDefinition CRD

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.

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.

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.

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.

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.

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.

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.

TykOasAPIDefinition CRD

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:

TykStreamsApiDefinition CRD

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:

Version Compatability

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.

Compatibility with Kubernetes Version

See Release notes to check for each Tyk Operator release, which version of Kubernetes it is tested against.

Security Policy CRD

The SecurityPolicy custom resource defines configuration of Tyk Security Policy object.

Here are the supported features:

Manage API MetaData

API Name

Tyk OAS API and Tyk Streams API

API name can be set through x-tyk-api-gateway.info.name field in Tyk OAS API Definition object.

Tyk Classic API

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
metadata:
  name: example-api # This is the metadata name of the Kubernetes resource
spec:
  name: Example API # This is the "API NAME" in Tyk
  use_keyless: true
  protocol: http
  active: true
  proxy:
    target_url: http://example.com
    listen_path: /example
    strip_listen_path: true

API Status

API Active Status

An active API will be loaded to the Gateway, while an inactive API will not, resulting in a 404 response when called.

Tyk OAS API and Tyk Streams API

API active state can be set through x-tyk-api-gateway.info.state.active field in Tyk OAS API Definition object.

Tyk Classic API

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
metadata:
  name: inactive-api
spec:
  name: Inactive API
  use_keyless: true
  protocol: http
  active: false
  proxy:
    target_url: http://inactive.example.com
    listen_path: /inactive
    strip_listen_path: true

API Accessibility

An API can be configured as internal so that external requests are not processed.

Tyk OAS API and Tyk Streams API

API accessibility can be set through x-tyk-api-gateway.info.state.internal field in Tyk OAS API Definition object.

Tyk Classic API

API accessibility can be set through the spec.internal configuration parameter as shown in the example below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
metadata:
  name: inactive-api
spec:
  name: Inactive API
  use_keyless: true
  protocol: http
  active: true
  internal: true
  proxy:
    target_url: http://inactive.example.com
    listen_path: /inactive
    strip_listen_path: true

API ID

Creating a new API

If you’re creating a new API using Tyk Operator, you don’t need to specify the ID. The API ID will be generated in a deterministic way.

Tyk OAS API and Tyk Streams API

The generated ID is stored in status.id field. Run the following command to inspect generated API ID of a Tyk OAS API.

% kubectl get tykoasapidefinition [API_NAME] --namespace [NAMESPACE] -o jsonpath='{.status.id}'
ZGVmYXVsdC9wZXRzdG9yZQ

In this example, the generated API ID is ZGVmYXVsdC9wZXRzdG9yZQ.

Tyk Classic API

The generated ID is stored in status.api_id field. Run the following command to inspect generated API ID of a Tyk Classic API.

% kubectl get apidefinition [API_NAME] --namespace [NAMESPACE] -o jsonpath='{.status.api_id}'
ZGVmYXVsdC90ZXN0

In this example, the generated API ID is ZGVmYXVsdC90ZXN0.

Updating an existing API

Tyk OAS API and Tyk Streams API

If you already have API configurations created in the Tyk Dashboard and want to start using Tyk Operator to manage these APIs, you can include the existing API ID in the manifest under the x-tyk-api-gateway.info.id field in Tyk OAS API Definition object.

Tyk Classic API

If you already have API configurations created in the Tyk Dashboard and want to start using Tyk Operator to manage these APIs, you can include the existing API ID in the manifest under the spec.api_id field. This way, when you apply the manifest, Tyk Operator will not create a new API in the Dashboard. Instead, it will update the original API with the Kubernetes spec.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
metadata:
  name: existing-api
  namespace: default
spec:
  name: Existing API
  api_id: 12345
  use_keyless: true
  protocol: http
  active: true
  proxy:
    target_url: http://existing.example.com
    listen_path: /existing
    strip_listen_path: true

In this example, the API with ID 12345 will be updated according to the provided spec instead of creating a new API.

API Categories

API categories are configured differently for Tyk OAS APIs and Tyk Classic APIs. Please see below for examples.

Tyk OAS API

API categories can be specified through categories field in TykOasApiDefinition CRD.

Here’s an example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

apiVersion: tyk.tyk.io/v1alpha1
kind: TykOasApiDefinition
metadata:
  name: oas-api-with-categories
  namespace: tyk
spec:
  categories:
  - category 1
  - category 2
  tykOAS:
    configmapRef:
      keyName: oas-api-definition.json
      name: tyk-oas-api-config
      namespace: tyk

Tyk Streams API

As of Tyk Operator v1.1, API categories is not supported in TykStreamsApiDefinition CRD.

Tyk Classic API

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
metadata:
  name: categorized-api
spec:
  name: "my-classic-api #global #staging"
  use_keyless: true
  protocol: http
  active: true
  proxy:
    target_url: http://categorized.example.com
    listen_path: /categorized
    strip_listen_path: true

API Versioning

API versioning are configured differently for Tyk OAS APIs and Tyk Classic APIs. Please see below for examples.

Configuring API Version in Tyk OAS API Definition

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

apiVersion: tyk.tyk.io/v1alpha1
kind: TykOasApiDefinition
metadata:
  name: order-api
  namespace: default
spec:
  tykOAS:
    configmapRef:
      namespace: default
      name: order-api
      keyName: order-api-definition-v1.json
  versioning:
    enabled: true
    location: header
    key: x-api-version
    name: v1
    default: v1
    fallbackToDefault: true
    stripVersioningData: true
    versions:
      - name: v2
        tykOasApiDefinitionRef:
          name: order-api-v2
          namespace: default
---
apiVersion: tyk.tyk.io/v1alpha1
kind: TykOasApiDefinition
metadata:
  name: order-api-v2
  namespace: default
spec:
  tykOAS:
    configmapRef:
      namespace: default
      name: order-api-v2
      keyName: order-api-definition-v2.json

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.

API Ownership

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.

How API Ownership works in Tyk Operator

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.

OperatorContext

Here’s how OperatorContext allows Tyk Operator to manage APIs under different ownerships:

apiVersion: tyk.tyk.io/v1alpha1
kind: OperatorContext
metadata:
  name: team-alpha
  namespace: default
spec:
  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

Tyk OAS API and Tyk Streams API

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

apiVersion: v1
data:
  test_oas.json: |-
    {
        "info": {
          "title": "Petstore",
          "version": "1.0.0"
        },
        "openapi": "3.0.3",
        "components": {},
        "paths": {},
        "x-tyk-api-gateway": {
          "info": {
            "name": "Petstore",
            "state": {
              "active": true
            }
          },
          "upstream": {
            "url": "https://petstore.swagger.io/v2"
          },
          "server": {
            "listenPath": {
              "value": "/petstore/",
              "strip": true
            }
          }
        }
      }
kind: ConfigMap
metadata:
  name: cm
  namespace: default
---
apiVersion: tyk.tyk.io/v1alpha1
kind: TykOasApiDefinition
metadata:
  name: petstore
spec:
  contextRef:
    name: team-alpha
    namespace: default
  tykOAS:
    configmapRef:
      name: cm
      namespace: default
      keyName: test_oas.json

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.

Tyk Classic API

Similarly, if you are using Tyk Classic API, you can reference it in your API Definition objects using contextRef. Below is an example:

apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
metadata:
  name: httpbin
  namespace: alpha
spec:
  contextRef:
    name: team-alpha
    namespace: default
  name: httpbin
  use_keyless: true
  protocol: http
  active: true
  proxy:
    target_url: http://httpbin.org
    listen_path: /httpbin
    strip_listen_path: true

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.

Troubleshooting and FAQ

    TYK_MODE: pro
    TYK_URL: http://external-tyk-dashboard
    TYK_AUTH: api-access-key
    TYK_ORG: org-id

$ kubectl delete tykapis httpbin 
apidefinition.tyk.tyk.io "httpbin" deleted 
^C%

$ kubectl get tykapis httpbin 
NAME      DOMAIN   LISTENPATH   PROXY.TARGETURL      ENABLED   STATUS
httpbin            /httpbin     http://httpbin.org   true      Failed

$ kubectl describe tykapis httpbin 
Name:         httpbin 
Namespace:    default 
API Version:  tyk.tyk.io/v1alpha1 
Kind:         ApiDefinition 
Metadata:
  ... 
Spec:
   ...
Status:
  api_id:                ZGVmYXVsdC9odHRwYmlu
  Latest CRD Spec Hash:  9169537376206027578
  Latest Transaction:
    Error:               unable to delete api due to security policy dependency=default/httpbin
    Status:              Failed
    Time:                2023-07-18T07:26:45Z
  Latest Tyk Spec Hash:  14558493065514264307
  linked_by_policies:
    Name:       httpbin
    Namespace:  default

$ 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"
}

apiVersion: tyk.tyk.io/v1alpha1
kind: OperatorContext
metadata:
  name: prod-context
spec:
  env:
    TYK_MODE: pro
    TYK_URL: http://tyk-dashboard-staging
    TYK_AUTH: prod-secret
---
apiVersion: tyk.tyk.io/v1alpha1
kind: OperatorContext
metadata:
  name: staging-context
spec:
  env:
    TYK_MODE: pro
    TYK_URL: http://tyk-dashboard-staging
    TYK_AUTH: staging-secret

apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
metadata:
  name: my-api
spec:
  name: My API
  context: prod-context
  # ... other API configuration