Tyk Upgrading Guide

Overview

This section provides guides and recommendations for upgrading your Tyk installation.

When upgrading Tyk, consider the following:

1. Deployment model: SaaS, Self-Managed, Hybrid, or OSS.
2. Installation type: Docker, Helm, K8S, or various Linux distributions.
3. Components: Depending on your model, upgrade relevant components such as Gateway, Pump, Dashboard, or Go Plugins.

These considerations are reflected in our structured upgrade guides, ensuring you have all necessary information in one place.

Tyk Upgrade Standards and Recommendations

Our upgrade process adheres to the following standards:

• Breaking changes: Breaking changes are rare and will be explicitly stated in the release notes.

• Configuration files: Upgrades do not overwrite your configuration files. However, it’s good practice to routinely back up these files (using git or another tool) before upgrading, so any customizations are saved.

• Migration scripts: Migration scripts for your APIs, policies, or other assets are generally not required unless specified in the release notes.

• Long Term Support: Refer to our versioning and long-term support policies for details on major and minor releases, patches, and support dates.

• Preparations: Review the preparation guidelines before starting the upgrade.

• Release notes: Always check the “Upgrade Instructions” section in the relevant release notes.

• Backups: Follow our comprehensive backup guide before starting the upgrade.

• Docker: Upgrading with Docker is straightforward—pull the new images from public repositories. Refer to the following links for our releases:

• Docker: Upgrading with Docker is straightforward - pull the new images from public repositories. Refer to the following links for our releases:

  • Docker & Kubernetes - Docker Hub - https://hub.docker.com/u/tykio
  • Helm install - Artifact Hub - https://artifacthub.io/packages/search?repo=tyk-helm
  • Linux - Packagecloud - https://packagecloud.io/tyk

  The above repositories will be updated when new versions are released

• If you experience issues with the new version you pulled, contact Tyk Support or visit Tyk community forum.

Tyk Upgrade Guides for different Deployment Models

Use the table below to find the appropriate upgrade guide for your platform:

Supporting Tools

Tyk offers supporting tools for database migration and backing up APIs and policies.

Migrating from MongoDB to SQL

Use our migration tool to manage the switch from MongoDB to SQL.

Backup APIs Script

Utilize our bash backup script to export and restore all Tyk API Definitions and Policies.

Preparations

Upgrade Guidelines

When considering upgrading your current configuration to a new Tyk release, we recommend you consider the following:

Upgrade strategy

Which strategy do you intend to use?

• If following the Blue-Green upgrade strategy, has the green environment been configured and verified as production-ready?
• If pursuing the Rolling upgrade strategy, do all Tyk components have a second instance?
• If you’ll have downtime, estimate the expected duration of the upgrade process and plan for potential downtime.

Backups

Have backups been performed?

• Databases: Have databases been properly backed up?
• configuration files: Have you safely back up these file (using version control system such as git)?
• Testing: Have you tested the backups to verify they can be successfully restored in a separate environment?
• Backup guide: Have you checke our comprehensive guide for backing up Tyk?

Go plugins

Do you use custom go plugins with your APIs?

• Go plugin must be recompiled for the new version.
• Identify all Go plugins in use with all your API definitions.
• Allow sufficient time for testing and troubleshooting Go plugins after the upgrade.

Linux users

Which Linux distributions is currently in use?

• Was Tyk deployed via a repository or a local package file .rpm (used be CentOS and RHEL) or .deb (Debian and its derivative Ubuntu)?
• Is the targeted version available on packagecloud.io/tyk or in an intended repository?

Communication

Communicate with stakeholders and users about the upgrade schedule and expected impact on services.

Upgrade Checklist:

• Choose an upgrade strategy or manage downtime
• Check Linux distribution and Tyk version availability
• Perform and test backups
• Identify and plan for custom Go plugin recompilation and testing
• Communicate with stakeholders

Next Steps

Use the Upgrade Guides ToC to choose the appropriate upgrade guide for your platform.

Upgrade Strategies

Tyk is compatible with both rolling and blue-green upgrade strategies.

Rolling Upgrade

A rolling upgrade updates servers incrementally rather than simultaneously. This approach helps reduce application downtime and mitigates the risk of unforeseen consequences or errors during software updates.

Steps for Rolling Upgrade:

1. Redundancy: Ensure there are at least two instances of each Tyk component that needs upgrading.
2. Load Balancer: Use a load balancer to distribute traffic for the Dashboard and Gateway components, ensuring continuous availability during the upgrade process. Note that the Pump operates with one-way traffic and does not require load balancing.
3. Upgrade Process:
   • Direct traffic to one instance while upgrading the other.
   • Once the first instance is upgraded, switch traffic to it and upgrade the remaining instance.
   • After both instances are upgraded, configure the load balancer to route traffic to both instances simultaneously.

Blue-Green Upgrade

A blue-green deployment involves two identical production environments, labeled blue and green. At any time, only one environment is live and serving traffic, while the other is inactive. For example, if the blue environment is live, the green environment will be inactive, and vice versa.

Steps for Blue-Green Upgrade:

1. Replication: Replicate the entire environment into a separate environment.
2. Traffic Routing: Use a load balancer or DNS to route traffic to the green environment (current production) while the blue environment undergoes the upgrade.
3. Upgrade Process:
   • A VM snapshot is a recommended method for replication, but other methods such as a new deployment process can also be used.
   • If using a new deployment process, follow the deployment instructions appropriate for your platform.
4. Switch Environments: Once the upgrade is complete, switch the traffic to the upgraded environment.

Deployment Model

Tyk Cloud Upgrade Guide

Tyk Cloud

Preparations

Before proceeding with the upgrade process, ensure that you have thoroughly reviewed and completed the steps outlined in the upgrade guidelines. Once you have adequately prepared, follow the instructions below to upgrade your Tyk components and plugins in this specified order. Adhering to the provided sequence is crucial for a smooth and successful upgrade.

Step 1. Upgrade Control Plane

Follow our guide for upgrading Cloud Control Planes.

Step 2. Upgrade Go Plugins

Follow our guide for deploying your Go plugins on Tyk Cloud. Subsequently, follow the steps below according to the target upgrade version of the Gateway.

Gateway Versions < 4.1.0.

1. Proceed with upgrading your Tyk Data Plane (Gateway)
2. Update the custom_middleware_bundle field in the API Definitions of all APIs that use your plugin. The field should be updated to use the new bundle file containing your upgrade plugin.
3. Validate that your plugin is working per your expectations.

Gateway Versions >= 4.1.0

1. Update the custom_middleware_bundle field in the API Definitions of all APIs that use your plugin. The field should be updated to use the new bundle file containing your upgraded plugin.

2. Validate that your plugin is working per your expectations as at this stage, your Gateway will be running the plugin for your current version still.

3. Proceed with upgrading your Tyk Data Plane (Gateway). Given that you loaded your target version plugin in step 1, this version will be loaded automatically once you upgrade.
4. Validate that your plugin is working per your expectations, as the Gateway now should have loaded the plugin for the target version automatically.

Step 3. Upgrade Cloud Data Plane

Follow our guide for upgrading Cloud Data Planes.

Upgrade Guide Video Please refer to our upgrade guide video below for visual guidance:

Tyk Hybrid

A Hybrid SaaS deployment is a shared responsibility model where Tyk is responsible for hosting the Control Plane while the client is responsible hosting their Data Plane, be it hosted on a public cloud provider or on their own infrastructure.

The control plane includes the following components:

• Tyk Dashboard
• Tyk Control Plane
• MDCB
• MongoDB
• Redis (Master Instance)

The self-managed data plane includes the following components:

• Hybrid Gateway(s)
• Redis instance
• Tyk Pump (optional)

After following the guidelines for preparing for upgrade, follow the instructions below to upgrade your self-managed Tyk components and plugins.

Upgrade Order

1. Upgrade the control plane on Tyk Cloud
2. Upgrade your Tyk self-managed data plane. When upgrading your data plane, upgrade the components in the following order:
   1. Go Plugins (if applicable)
   2. Hybrid Pump (if applicable)
   3. Hybrid Gateway(s)

Step 1. Upgrade your control plane

See Tyk Guide for how to upgrade Control Planes

Step 2 Upgrade Go plugins

Follow our guide for upgrading your Go plugins on Tyk Cloud. Subsequently, follow the steps below according to the target upgrade version of the Gateway.

Gateway Versions < 4.1.0

1. Proceed with upgrading your Tyk Data Plane Hybrid Gateways.
2. Update the custom_middleware_bundle field in the API Definitions of all APIs that use your plugin. The field should be updated to use the new bundle file containing your upgrade plugin.
3. Validate that your plugin is working per your expectations.

Gateway Versions >= 4.1.0

1. Update the custom_middleware_bundle field in the API Definitions of all APIs that use your plugin. The field should be updated to use the new bundle file containing your upgraded plugin.
2. Validate that your plugin is working per your expectations as at this stage, your Gateway will be running the plugin for your current version still.

3. Proceed with upgrading your Tyk Data Plane Hybrid Gateways. Given that you loaded your target version plugin in step 1, this version will be loaded automatically once you upgrade.
4. Validate that your plugin is working per your expectations.

Step 3. Upgrade your Tyk Data Plane Hybrid Gateway(s)

Follow the instructions for component deployment type:

• Docker
• Helm
• Linux Debian
• Linux RHEL/CENTOS

Upgrade Guide Video

Please refer to our video for further supporting with upgrading Tyk Self-Managed (RPM).

Go Plugin

This guide explains how to deploy your custom Go plugins on Tyk Cloud:

1. Navigate into the plugins directory that contains your Go module
2. Compile your custom Go plugins.
3. Use the table below to follow the deployment process for the version of Tyk you are upgrading to:

Path 1 - Current Version < 4.1.0 and Target Version < 4.1.0

1. Create a plugin bundle that includes the newly compiled version

   

   Your manifest.json will look something like this:

   {
     "file_list": [
         "CustomGoPlugin.so"
     ],
     "custom_middleware": {
       "pre": [
       {
         "name": "AddHeader",
         "path": "CustomGoPlugin.so",
         "require_session": false,
         "raw_body_only": false
       }],
       "driver": "goplugin",
       "id_extractor": {
       "extract_from": "",
       "extract_with": "", 
       "extractor_config": {}}
     },
     "checksum": "",
     "signature": ""
   }
   

2. Upload this bundle to your configured S3 bucket if using Cloud SaaS. If you’re using Hybrid SaaS, upload this bundle to your bundle server.

Path 2 - Current Version >= 4.1.0 and Target Version >= 4.2.0

1. Create a plugin bundle that includes both your current version’s plugin along with the newly compiled version

   

   Your manifest.json will look something like this:

   {
     "file_list": [
         "CustomGoPlugin.so",
         "CustomGoPlugin_v4.3.3_linux_amd64.so"
     ],
     "custom_middleware": {
       "pre": [
       {
         "name": "AddHeader",
         "path": "CustomGoPlugin.so",
         "require_session": false,
         "raw_body_only": false
       }],
       "driver": "goplugin",
       "id_extractor": {
         "extract_from": "",
         "extract_with": "", 
         "extractor_config": {}
       }
     },
     "checksum": "",
     "signature": ""
   }
   

   In this example -

   • the CustomGoPlugin.so in the file list would be the filename of the plugin you’re using with your current version. You will already have this file available as this is what has been running in your environment.
   • The CustomGoPlugin_v4.3.3_linux_amd64.so file represents the plugin compiled for the target version.
   • “_v4.3.3_linux_amd64” postfix is generated automatically by the compiler. If your target version was 5.2.0, then “_v5.2.0_linux_amd64” would be appended to the shared object filename that the compiler creates
   • Your bundle zip file should include both the current version and target versions of the plugin.

2. Upload this bundle to your configured S3 bucket if using Cloud SaaS. If you’re using Hybrid SaaS, upload this bundle to your bundle server.

Tyk Self Managed Upgrade Guide

Preparations

Before proceeding with the upgrade process, ensure that you have thoroughly reviewed and completed the steps outlined in the upgrade guidelines. Once you have adequately prepared, follow the instructions below to upgrade your Tyk components and plugins in this specified order. Adhering to the provided sequence is crucial for a smooth and successful upgrade.

Upgrade Order

In a production environment where the Dashboard, Gateway, and Pump are installed on separate machines, you should always upgrade components in the following sequence:

1. Tyk Dashboard
2. Tyk Gateway
3. Tyk Pump

Upgrade order with Multi Data Center Bridge (MDCB)

For Enterprise customers, the Tyk control plane contains all the standard components of a Self-Managed installation with the addition of the Multi Data Center Bridge (MDCB).

Our recommended sequence for upgrading a self-managed MDCB installation is as follows:

Stage 1: Upgrade the components of the Tyk control plane in this order:

1. MDCB
2. Tyk Pump (if applicable)
3. Tyk Dashboard
4. Tyk Gateway

Stage 2: Next, upgrade the components in Tyk data planes, in this order:

1. Go Plugins (if applicable)
2. Tyk Pump (if applicable)
3. Tyk Gateway

This sequence of control plane first and data plane second ensures:

1. Forward compatibility - ensures that we don’t have forward-compatibility issues of new Gateway using old MDCB.
2. Connectivity issues - It’s extremely fast to see if there are connectivity issues and gateways (in Hybrid mode) will continue to function even if disconnected from their control plane.

Upgrade guides

We provide upgrade guides for Linux, Docker, Helm and K8S. To continue the upgrade process, please refer to the relevant installation guide under this section.

Docker

Step 1. Upgrade Tyk Dashboard

Upgrading Tyk Dashboard is the same as Tyk Gateway just with the name of the docker image of tyk dashboard tykio/tyk-dashboard. Please check the instruction for Tyk Gateway in the next section.

Step 2. Upgrade Tyk Gateway and Tyk Pump

Follow our Tyk OSS guide for upgrading Tyk Gateway and Tyk Pump

Helm

Upgrade Tyk Gateway

1. Backup your gateway config file (tyk.conf or the name you chose for it), .env and values.yaml. Even if you’re using the environment variables from the values.yaml to define your configuration, there still might be a config file used and loaded with field values you relay on.
2. Backup your .env and values.yaml
3. Update the image version in your values.yaml
   For example, in this values.yaml change the version of the tag tag: v5.3 to the version you want.
4. Run Helm upgrade with your relevant values.yaml file/s.
   Check the helm upgrade docs for more details on the upgrade command.

Kubernetes

Simple Kubernetes Environment Upgrade

When upgrading a non-production environment, where it’s okay to have a brief downtime and you can simply restart your gateways, the upgrade is trivial as with any other image you want to upgrade in Kubernetes:

In a similar way to docker:

1. Backup your gateway config file (tyk.conf or the name you chose for it)
2. Update the image version in the manifest file.
3. Apply the file/s using kubectl

$ kubectl apply -f .

You will see that the deployment has changed.

Now you can check the gateway pod to see the latest events (do kubectl get pods to get the pod name):

$ kubectl describe pods <gateway pod name>

You should see that the image was pulled, the container got created and the gateway started running again, similar to the following output:

Events:
  Type    Reason     Age   From               Message
  ----    ------     ----  ----               -------
  Normal  Scheduled  118s  default-scheduler  Successfully assigned tyk/tyk-gtw-89dc9f554-5487c to docker-desktop
  Normal  Pulling    117s  kubelet            Pulling image "tykio/tyk-gateway:v5.0"
  Normal  Pulled     70s   kubelet            Successfully pulled image "tykio/tyk-gateway:v5.0" in 47.245940479s
  Normal  Created    70s   kubelet            Created container tyk-gtw
  Normal  Started    70s   kubelet            Started container tyk-gtw

4. Check the log to see that the new version is used and if the gateway is up and running

$ kubectl logs service/gateway-svc-tyk-gateway-tyk-headless --tail=100 --follow 
Defaulted container "gateway-tyk-headless" out of: gateway-tyk-headless, setup-directories (init)
time="Jul 17 20:58:27" level=info msg="Tyk API Gateway 5.1.0" prefix=main
...

5. Check the gateway is healthy

$ curl  localhost:8080/hello | jq .
{
  "status": "pass",
  "version": "5.1.0",
  "description": "Tyk GW",
  "details": {
    "redis": {
      "status": "pass",
      "componentType": "datastore",
      "time": "2023-07-17T21:07:27Z"
    }
  }
}

Upgrade Tyk K8S Demo deployment

1. In the Tyk k8s Demo repo, change the version in .env file, GATEWAY_VERSION=v5.1 to the version you want
2. Restart the deployment
3. Check the log file

Linux - Debian

The following guide explains how to upgrade Tyk Self-Managed running on Debian

Upgrade Guide Video

Please refer to our upgrade guide video below for visual guidance of upgrading Tyk Self-Managed (DEB).

Preparations

After reviewing guidelines for preparing for upgrade, follow the instructions below to upgrade your Tyk components and plugins.

Upgrade order:

Please note that upgrade order is as explained in the upgrade overview

Distro versions

Tyk supports the following version for Debian and its derivative Ubuntu:

Our repositories will be updated at https://packagecloud.io/tyk when new versions are released.

During the initial deployment of Tyk, your team may have utilized APT repositories or directly downloaded the .deb files. To verify the presence of APT repositories on the server, inspect the following locations:

• Dashboard: /etc/apt/sources.list.d/tyk_tyk-dashboard.list
• Gateway: /etc/apt/sources.list.d/tyk_tyk-gateway.list
• Pump: /etc/apt/sources.list.d/tyk_tyk-pump.list

If the above files are not present, it could be worth checking internally that the initial deployment was done by manually downloading and installing the .deb files. This is common in airtight environments without internet access.

Verify Target Package Availability

Depending on the Linux distribution that you are using, ensure that you are pulling the correct version and distribution from the packagecloud.io/tyk repository.

The package name contains the version number and the distro/version column displays the specific distribution release.

Backups

Configuration files:

Please take a backup of below configuration files of each Tyk component. This will be useful in case you need to cross reference configuration changes or need to rollback your deployment.

• Dashboard Configuration File: /opt/tyk-dashboard/tyk_analytics.conf
• Gateway Configuration File: /opt/tyk-gateway/tyk.conf
• Pump Configuration File: /opt/tyk-pump/pump.conf

Databases

Redis

For more detailed instructions on managing Redis backups, please refer to the official Redis documentation: https://redis.io/docs/management/persistence/

The Redis SAVE command is used to create a backup of the current redis database. The SAVE command performs a synchronous save of the dataset producing a point in time snapshot of all the data inside the Redis instance, in the form of an RDB file.

# Using SAVE, if the previous dump.rdb file exists in the working directory, it will be overwritten with the new snapshot

SAVE

Example - SAVE

To restore Redis data, follow these steps:

• Move the Redis backup file (dump.rdb) to your Redis directory.
• Start the Redis server

To locate your Redis directory, you can use the CONFIG command. Specifically, the CONFIG GET command allows you to read the configuration parameters of a running Redis server.

Example - CONFIG

MongoDB

For detailed instructions on performing backups in MongoDB, please refer to the official MongoDB documentation: https://www.mongodb.com/docs/manual/core/backups/

To capture a snapshot of a MongoDB database from a remote machine and store it locally, utilize the mongodump command on the primary node. Specify the host and port number (default is 27017) of the remote server, along with additional parameters such as the database name, user credentials and password. Lastly, designate the directory where the snapshot should be created.

mongodump --db tyk_analytics --out /path/to/dump/directory

Example

To restore a database using a previously saved snapshot, simply employ the mongorestore command.

mongorestore --host <hostname> --port <port> --username <username> --password <password> /path/to/dump/directory

Steps for Upgrading Tyk Packages

Before executing the upgrade, ensure that you have consulted and performed all the necessary steps in the pre upgrade checklist.

Step 1. Update Tyk Repositories

Fetch and update information about the available packages from the specified repositories.

sudo apt-get update

Step 2. Verify availability of target upgrade packages

List current versions of Tyk using the command below:

dpkg -l | grep -i tyk

Example

List available versions of upgradable packages of Tyk components and ensure that the version you are planning to upgrade to is listed in the output of the above command.

apt list -a 'tyk*'

Example

Step 3. Upgrade Tyk Components

Note: Please specify the exact version you are upgrading into.

sudo apt-get install tyk-dashboard=<desired-version>

sudo apt-get install tyk-gateway=<desired-version>

sudo apt-get install tyk-pump=<desired-version>

Example

Step 4. Restart Components

After upgrading Tyk, restart the services

# Restart Services
systemctl restart tyk-dashboard
systemctl restart tyk-gateway
systemctl restart tyk-pump

# Check status of Tyk Components
systemctl status tyk-dashboard
systemctl status tyk-gateway
systemctl status tyk-pump

Step 5. Health check on upgraded Tyk components

Perform a health check on all 3 Tyk Components. The host and port number varies on your setup.

Tyk Dashboard

curl http://localhost:3000/hello

Tyk Gateway

curl http://localhost:8080/hello

Tyk Pump

curl http://localhost:8083/health

Reverting the Upgrade

If the upgrade fails you can revert to the old version by following the steps below.

Step 1. Inspect package logs

In case the upgrade fails for some reason, you can use the command below to check your history of package installs:

cat /var/log/apt/history.log

Step 2. Revert

Manually reverting to a previous version can be done by installing or uninstalling a package. For instance, to roll back to the previous version, you can use this command:

sudo apt-get install tyk-dashboard=<previous version>

Linux - RedHat (CentOS)

The following guide explains how to upgrade Tyk Self-Managed running on RHL

Upgrade guide video

Please refer to our upgrade guide video below for visual guidance of upgrading Tyk Self-Managed (RPM).

Preparations

After reviewing guidelines for preparing for upgrade, follow the instructions below to upgrade your Tyk components and plugins.

Upgrade order: Please note that upgrade order is as explained in the upgrade overview

Distro versions

Tyk supports the following Centos and Rhel distributions:

Our repositories will be updated at https://packagecloud.io/tyk when new versions are released.

During the initial deployment of Tyk, your team may have utilized YUM repositories or directly downloaded the .rpm files. To verify the presence of YUM repositories on the server, inspect the following locations:

• Dashboard: /etc/yum.repos.d/tyk_tyk-dashboard.repo
• Gateway: /etc/yum.repos.d/tyk_tyk-gateway.repo
• Pump: /etc/yum.repos.d/tyk_tyk-pump.repo

If the above files are not present, it is worthwhile checking internally that the initial deployment was done by manually downloading and installing the .rpm files. This is common in airtight environments without internet access.

Verify Target Package Availability

Depending on the Linux distribution that you are using, ensure that you are pulling the correct version and distribution from the packagecloud.io/tyk repository.

The package name contains the version number and the distro/version column displays the specific distribution release.

Backups

Before upgrading, ensure that the configuration files and databases are backed up.

Configuration files

Please take a backup of the following configuration files for each Tyk component. This will be useful in case you need to cross reference configuration changes or need to rollback your deployment.

• Dashboard Configuration File: /opt/tyk-dashboard/tyk_analytics.conf
• Gateway Configuration File: /opt/tyk-gateway/tyk.conf
• Pump Configuration File: /opt/tyk-pump/pump.conf

Databases

Redis

For more detailed instructions on managing Redis backups, please refer to the official Redis documentation: https://redis.io/docs/management/persistence/

The Redis SAVE command is used to create a backup of the current Redis database. The SAVE command performs a synchronous save of the dataset producing a point in time snapshot of all the data inside the Redis instance, in the form of an RDB file.

# Using SAVE, if the previous dump.rdb file exists in the working directory, it will be overwritten with the new snapshot

SAVE

Example

To restore Redis data, follow these steps:

• Move the Redis backup file (dump.rdb) to your Redis directory.
• Start the Redis server

To locate your Redis directory, you can use the CONFIG command. Specifically, the CONFIG GET command allows you to read the configuration parameters of a running Redis server. Example:

MongoDB

For detailed instructions on performing backups in MongoDB, please refer to the official MongoDB documentation: https://www.mongodb.com/docs/manual/core/backups/

To capture a snapshot of a MongoDB database from a remote machine and store it locally, utilize the mongodump command on the primary node. Specify the host and port number (default is 27017) of the remote server, along with additional parameters such as the database name, user credentials and password. Lastly, designate the directory where the snapshot should be created.

mongodump --db tyk_analytics --out /path/to/dump/directory

Example

To restore a database using a previously saved snapshot, simply employ the mongorestore command.

mongorestore --host <hostname> --port <port> --username <username> --password <password> /path/to/dump/directory

Upgrade Tyk Packages

Before executing the upgrade, ensure that you have consulted and performed all the necessary steps in the pre upgrade checklist.

Step 1. Update Tyk Repositories

Fetch and update information about the available packages from the specified repositories.

sudo yum -q makecache -y --disablerepo='*' --enablerepo='tyk_tyk-dashboard'
sudo yum -q makecache -y --disablerepo='*' --enablerepo='tyk_tyk-gateway'
sudo yum -q makecache -y --disablerepo='*' --enablerepo='tyk_tyk-pump'

Or
# To update ALL repositories in your system instead

sudo yum -q makecache -y

Step 2. Verify availability of target upgrade packages

List current versions of Tyk using the command below:

rpm -qa | grep -i tyk

Example

List available versions of upgradable packages of Tyk components and ensure that the version you are planning to upgrade to is listed in the output of the above command.

yum --showduplicates list tyk*

Example:

Step 3. Upgrade Tyk Components

Note: Please specify the exact version you are upgrading into.

yum update tyk-dashboard-<desired-version>
yum update tyk-gateway-<desired-version>
yum update tyk-pump-<desired-version>

Example

Step 4. Restart Tyk Components

After upgrading Tyk, restart the services

# Restart Services
systemctl restart tyk-dashboard
systemctl restart tyk-gateway
systemctl restart tyk-pump

# Check status of Tyk Components
systemctl status tyk-dashboard
systemctl status tyk-gateway
systemctl status tyk-pump

Step 5. Health check on upgraded Tyk components

Perform a health check on all 3 Tyk Components. The host and port number varies on your setup.

Tyk Dashboard

curl http://localhost:3000/hello

Tyk Gateway

curl http://localhost:8080/hello

Tyk Pump

curl http://localhost:8083/health

Reverting the Upgrade

If the upgrade fails you can revert to the old version by following the steps below.

Step 1. Inspect package logs

Use the command below to fetch information for all updates, noting the ID for the specific “update” action to revert to allow verifiying the packages:

yum history

Step 2. Verify update

Display details of the specific “update” transaction, replacing ID noted in the previous step

yum history info <ID>

Example

Step 3. Revert

If you encounter difficulties after an upgrade and wish to revert the changes, you can use the following commands as a guide.

If you’re experiencing issues specifically related to the upgrade and want to undo those changes only, you can use the yum history undo command. This will undo the changes for a specific update transaction only.

yum history undo <ID>

If you encounter issues after the upgrade and wish to revert your system to its previous state entirely, you can use the yum history rollback command. This command will rollback the system to a specific point in time, undoing all transactions that occurred after that point.

yum history rollback <ID>

Open Source Upgrade Guide

The following guide explains how to upgrade Tyk Gateway when using Docker. For guides of other installation types check the “Self-manged” section, and look for the instruction regarding Tyk Gateway.

Before proceeding with the upgrade process, ensure that you have thoroughly reviewed and completed the steps outlined in the pre-upgrade guidelines. Once you have adequately prepared, follow the instructions below to upgrade your Tyk components and plugins in this specified order. Adhering to the provided sequence is crucial for a smooth and successful upgrade.

Upgrade Order

In a production environment, where we recommend installing the Dashboard, Gateway, and Pump on separate machines, you should upgrade components in the following sequence:

1. Tyk Gateway
2. Tyk Pump

Steps for Upgrading Tyk Gateway

Development Environment Upgrade

In a development environment where you can simply restart your gateways, follow these steps:

1. Backup your gateway config file (tyk.conf or the name you chose for it)
2. Update the image version in the docker command or script
3. Restart the gateway. For example, update the following command to v5.1 and run it as follows:

$ docker run \
  --name tyk_gateway \
  --network tyk \
  -p 8080:8080 \
  -v $(pwd)/tyk.standalone.conf:/opt/tyk-gateway/tyk.conf \
  -v $(pwd)/apps:/opt/tyk-gateway/apps \
  docker.tyk.io/tyk-gateway/tyk-gateway:v5.3

For full installation details, check the usual installation page.

Docker compose upgrade in a simple environment

For non-production environments where brief downtime is acceptable, you can upgrade by simply restarting your gateways. Follow these steps:

1. Backup your gateway config file (tyk.conf or the name you chose for it)
2. Update the image version in the docker-compose.yaml file.
   For example, Tyk Gateway version 4.3.3 is defined in this docker-compose.yaml image: docker.tyk.io/tyk-gateway/tyk-gateway:v4.3.3. Change 4.3.3 to the version you want to use.
3. Restart the gateway (or stop and start it)

$ docker compose restart

4. Check the log to see that the new version is used and if the gateway is up and running
5. Check that the gateway is healthy

$ curl  localhost:8080/hello | jq .
{
  "status": "pass",
  "version": "5.3.0",
  "description": "Tyk GW",
  "details": {
    "redis": {
      "status": "pass",
      "componentType": "datastore",
      "time": "2023-07-17T21:07:27Z"
    }
  }
}

Production Environment Upgrade

1. Backup your Gateway config file
2. Use Docker’s best practices for a rolling update
3. Review and complete the steps outlined in the pre-upgrade guidelines.
4. Define the version in your setup script (for example in .env file). The new image will be pulled once it’s executed. If your script is doing docker pull, update the version of the gateway in that command to the target version.
5. Check the log to see that the new version is used and if the gateway is up and running
6. Check that the Gateway is healthy using the open /hello API ( run curl localhost:8080/hello | jq .)

Upgrade Tyk Pump

Docker Instructions for upgrading Tyk Pump is the same as the above for Tyk Gateway just with the name of the docker image of Tyk Pump tykio/tyk-pump-docker-pub

Go Plugins Upgrade Guide

This guide shows you how to compile your custom Go plugins for upgrade.

The table below links you to the upgrade steps for the version of Tyk you are upgrading from and to:

Path 1 - Current Version < 4.1.0 and Target Version < 4.1.0

1. Open a terminal/command prompt in the directory of your plugin source file(s)
2. Run the following commands to initialise your plugin:

go get 
github.com/TykTechnologies/tyk@6c76e802a29838d058588ff924358706a078d0c5

# Tyk Gateway versions < 4.2 have a dependency on graphql-go-tools
go mod edit -replace github.com/jensneuse/graphql-go-tools=github.com/TykTechnologies/[email protected]

go mod tidy
go mod vendor

Path 2 - Current Version < 4.1.0 and Target Version >= 4.1.0

1. Open a terminal/command prompt in the directory of your plugin source file(s)
2. Based on your Target Version run the appropriate commands to initialize your plugin:

• Target Version <= v4.2.0

  go get github.com/TykTechnologies/tyk@6c76e802a29838d058588ff924358706a078d0c5
  # Tyk Gateway versions < 4.2 have a dependency on graphql-go-tools
  go mod edit -replace github.com/jensneuse/graphql-go-tools=github.com/TykTechnologies/[email protected]
  go mod tidy
  go mod vendor
  

• Target Version > v4.2.0 and < v5.1

  go get github.com/TykTechnologies/tyk@54e1072a6a9918e29606edf6b60def437b273d0a
  # For Gateway versions earlier than 5.1 using the go mod vendor tool is required
  go mod tidy
  go mod vendor
  

• Target Version >= v5.1.0

  go get github.com/TykTechnologies/tyk@ffa83a27d3bf793aa27e5f6e4c7106106286699d
  # In Gateway version 5.1, the Gateway and plugins transitioned to using Go modules builds and don't use Go mod vendor anymore
  go mod tidy
  

Path 3 - Current Version >= 4.1.0 and Target Version >= 5.1.0

1. Open a terminal/command prompt in the directory of your plugin source file(s)
2. Based on your Target Version run the appropriate commands to initialise your plugin:

• Target Version > v4.2.0 and < v5.1.0

  go get github.com/TykTechnologies/tyk@54e1072a6a9918e29606edf6b60def437b273d0a
  # For Gateway versions earlier than 5.1 using the go mod vendor tool is required
  go mod tidy
  go mod vendor
  

  • Target Version >= v5.1.0

  go get github.com/TykTechnologies/tyk@ffa83a27d3bf793aa27e5f6e4c7106106286699d
  # In Gateway version 5.1, the Gateway and plugins transitioned to using
  # Go modules builds and don't use Go mod vendor anymore
  go mod tidy
  

Compile the plugins

Download the plugin compiler for the target Gateway version you’re upgrading to (e.g. 5.2.5). Docker images for plugin compiler versions are available in the Tyk Docker Hub.

docker pull tykio/tyk-plugin-compiler:v5.2.5

Recompile your plugin with this version

docker run --rm -v "$(pwd)":/plugin-source \
           --platform=linux/amd64 \
           tykio/tyk-plugin-compiler:v5.2.5 plugin.so

Example:

You can remove the plugin complier images once your plugin has been successfully recompiled:

docker rmi plugin_compiler_image_name_or_id

Backup APIs and Policies

Backing up Tyk APIs and Policies is crucial for ensuring business continuity and data integrity. It safeguards against accidental data loss, system failures or corruption. This provides the opportunity to rollback to a stable state during upgrades or migrations, allowing you to restore configurations to a previous state to prevent disruptions with your API infrastructure. If you are using Self Managed deployment then we recommend that you use Tyk Sync to backup your Tyk APIs and policies.

Export And Restore APIs and Policies

To facilitate backing up APIs and policies we have provided a Bash script backup that can be used to export and restore all Tyk API definitions and Policies from Tyk Dashboard. This will be done by the export and import commands respectively. The script can be used on both Tyk Cloud and Self Managed deployments. The script is helpful for Tyk Cloud users who want to export their Tyk OAS APIs since tyk-sync does not currently support it on Tyk Cloud.

Export APIs and Policies

To export all APIs and Policies use the export command:

./backup.sh export --url https://my-tyk-dashboard.com --secret mysecretkey --api-output apis.json --policy-output policies.json

This will export all your API definitions and policies to apis.json and policies.json files.

Import APIs and Policies

To import all your APIs and Policies, use the import command:

./backup.sh import --url https://my-tyk-dashboard.com --secret mysecretkey --api-file apis.json --policy-file policies.json

This will restore the API definitions and policies from the apis.json and policies.json files.