tyk-oss

Tyk Open Source

Tyk-oss provides the default deployment of the Tyk Open Source stack. It includes the Tyk Gateway, an open source Enterprise API Gateway, supporting REST, GraphQL, TCP and gRPC protocols; and Tyk Pump, an analytics purger that moves the data generated by your Tyk gateways to any back-end.

Introduction

By default, this chart installs following components as subcharts on a Kubernetes cluster using the Helm package manager.

Component	Enabled by Default	Flag
Tyk Gateway	true	n/a
Tyk Pump	false	global.components.pump

To enable or disable each component, change the corresponding enabled flag.

Also, you can set the version of each component through image.tag. You could find the list of version tags available from Docker hub.

Prerequisites

• Kubernetes 1.19+
• Helm 3+
• Redis should already be installed or accessible by the gateway. For Redis installations instruction, follow the Redis installation guide below.

Quick Start

Quick start using tyk-oss and Bitnami Redis chart

NAMESPACE=tyk-oss
APISecret=foo

helm upgrade tyk-redis oci://registry-1.docker.io/bitnamicharts/redis -n $NAMESPACE --create-namespace --install --set image.tag=6.2.13

helm upgrade tyk-oss tyk-helm/tyk-oss -n $NAMESPACE --create-namespace \
  --install \
  --set global.secrets.APISecret="$APISecret" \
  --set global.redis.addrs="{tyk-redis-master.$NAMESPACE.svc.cluster.local:6379}" \
  --set global.redis.passSecret.name=tyk-redis \
  --set global.redis.passSecret.keyName=redis-password

Gateway is now accessible through service gateway-svc-tyk-oss-tyk-gateway at port 8080.

Installing the Chart

To install the chart from the Helm repository in namespace tyk with the release name tyk-oss:

First, add our Helm repo and get default values:

    helm repo add tyk-helm https://helm.tyk.io/public/helm/charts/
    helm repo update
    helm show values tyk-helm/tyk-oss > values-oss.yaml

See Configuration section for the available config options and modify your local values-oss.yaml file accordingly. Then install the chart:

helm install tyk-oss tyk-helm/tyk-oss -n tyk --create-namespace -f values-oss.yaml

Uninstalling the Chart

helm uninstall tyk-oss -n tyk

This removes all the Kubernetes components associated with the chart and deletes the release.

Upgrading Chart

helm upgrade tyk-oss tyk-helm/tyk-oss -n tyk

Note: tyk-headless chart users

If you were using tyk-headless chart for existing release, you cannot upgrade directly. Please modify the values.yaml base on your requirements and install using the new tyk-oss chart.

Configuration

To get all configurable options with detailed comments:

helm show values tyk-helm/tyk-oss > values.yaml

You can update any value in your local values.yaml file and use -f [filename] flag to override default values during installation. Alternatively, you can use --set flag to set it in Tyk installation.

Set Redis Connection Details (Required)

Tyk uses Redis for distributed rate-limiting and token storage. You may use the Bitnami chart to install or Tyk's simple-redis chart for POC purpose.

Set the following values after installing Redis:

Name	Description
global.redis.addrs	Redis addresses
global.redis.pass	Redis password in plain text
global.redis.passSecret.name	If global.redis.pass is not provided, you can store it in a secret and provide the secret name here
global.redis.passSecret.keyName	key name to retrieve redis password from the secret

Recommended: via Bitnami chart

For Redis you can use these rather excellent charts provided by Bitnami. Copy the following commands to add it:

helm upgrade tyk-redis oci://registry-1.docker.io/bitnamicharts/redis -n tyk --create-namespace --install --set image.tag=6.2.13

Follow the notes from the installation output to get connection details and password.

  Redis(TM) can be accessed on the following DNS names from within your cluster:

    tyk-redis-master.tyk.svc.cluster.local for read/write operations (port 6379)
    tyk-redis-replicas.tyk.svc.cluster.local for read-only operations (port 6379)

  export REDIS_PASSWORD=$(kubectl get secret --namespace tyk tyk-redis -o jsonpath="{.data.redis-password}" | base64 --decode)

The Redis address as set by Bitnami is tyk-redis-master.tyk.svc.cluster.local:6379

You can reference the password secret generated by Bitnami chart by --set global.redis.passSecret.name=tyk-redis and --set global.redis.passSecret.keyName=redis-password, or just set global.redis.pass=$REDIS_PASSWORD

Evaluation only: via simple-redis chart

Another option for Redis, to get started quickly, is to use our simple-redis chart.

⚠️ Please note that these provided charts must never be used in production or for anything but a quick start evaluation only. Use Bitnami Redis or Official Redis Helm chart in any other case. We provide this chart, so you can quickly deploy Tyk gateway, but it is not meant for long term storage of data.

helm install redis tyk-helm/simple-redis -n tyk

The Tyk Helm Chart can connect to simple-redis in the same namespace by default. You do not need to set Redis address and password in values.yaml.

Enable gateway autoscaling

This chart allows for easy configuration of autoscaling parameters. To simply enable autoscaling it's enough to add --set tyk-gateway.gateway.autoscaling.enabled=true. That will enable Horizontal Pod Autoscaler resource with default parameters (avg. CPU load at 60%, scaling between 1 and 3 instances). To customize those values you can add --set tyk-gateway.gateway.autoscaling.averageCpuUtilization=75 or use values.yaml file:

tyk-gateway:
  gateway:
    autoscaling:
      enabled: true
      minReplicas: 3
      maxReplicas: 30

Built-in rules include tyk-gateway.gateway.autoscaling.averageCpuUtilization for CPU utilization (set by default at 60%) and tyk-gateway.gateway.autoscaling.averageMemoryUtilization for memory (disabled by default). In addition to that you can define rules for custom metrics using tyk-gateway.gateway.autoscaling.autoscalingTemplate list:

tyk-gateway:
  gateway:
    autoscaling:
      autoscalingTemplate:
        - type: Pods
          pods:
            metric:
              name: nginx_ingress_controller_nginx_process_requests_total
            target:
              type: AverageValue
              averageValue: 10000m

Gateway Configurations

Configure below inside tyk-gateway section.

Update Tyk Gateway Version

Set version of gateway at tyk-gateway.gateway.image.tag. You can find the list of version tags available from Docker hub. Please check Tyk Release notes carefully while upgrading or downgrading.

Enabling TLS

Enable TLS

We have provided an easy way to enable TLS via the global.tls.gateway flag. Setting this value to true will automatically enable TLS using the certificate provided under tyk-gateway/certs/.

Configure TLS secret

If you want to use your own key/cert pair, please follow the following steps:

1. Create a TLS secret using your cert and key pair.
2. Set global.tls.gateway to true.
3. Set tyk-gateway.gateway.tls.useDefaultTykCertificate to false.
4. Set tyk-gateway.gateway.tls.secretName to the name of the newly created secret.

Add Custom Certificates

To add your custom Certificate Authority(CA) to your containers, you can mount your CA certificate directly into /etc/ssl/certs folder.

   extraVolumes:
     - name: self-signed-ca
       secret:
         secretName: self-signed-ca-secret
   extraVolumeMounts:
     - name: self-signed-ca
       mountPath: "/etc/ssl/certs/myCA.pem"
       subPath: myCA.pem

Accessing Gateway

Service port

Default service port of gateway is 8080. You can change this at global.servicePorts.gateway.

If you want to use your own key/cert pair, you must follow the following steps:

1. Create a tls secret using your cert and key pair.
2. Set .Values.global.tls.gateway to true.
3. Set .Values.global.tls.useDefaultTykCertificate to false.
4. Set .Values.tyk-gateway.tls.secretName to the name of the newly created secret.

Ingress

An Ingress resource is created if tyk-gateway.gateway.ingress.enabled is set to true.

    ingress:
      # if enabled, creates an ingress resource for the gateway
      enabled: true

      # specify ingress controller class name
      className: "nginx"

      # annotations for ingress
      annotations: {}

      # ingress rules
      hosts:
        - host: tyk-gw.local
          paths:
            - path: /
              pathType: ImplementationSpecific

      # tls configuration for ingress
      #  - secretName: chart-example-tls
      #    hosts:
      #      - chart-example.local
      tls: []

Control Port

Set tyk-gateway.gateway.control.enabled to true will allow you to run the Gateway API on a separate port and protect it behind a firewall if needed.

Mounting APIs, Policies, and Middlewares

By default, Gateway stores API configurations at /mnt/tyk-gateway/apps inside the Gateway container. There are a few challenges:

• Multiple gateways do not share app configs
• The configuration is not persistent. It will get lost whenever pod restarts.

The same applies to security policies and middleware too which is stored at /mnt/tyk-gateway/policies and /mnt/tyk-gateway/middleware respectively. This can be solved by instantiating a Persistent Volume as shared storage for the gateway instances. As each gateway is reload, they would get the API configurations from the same storage, solving the synchronisation issue between gateways. Also, the storage is persistent and can be designed to be not impacted by cluster failure, your API configurations can be maintained after pod restart.

You can configure persistent volume for APIs, Policies, and middlewares using extraVolumes and extraVolumeMounts:

    extraVolumes:
    - name: tyk-app-storage
      persistentVolumeClaim:
        claimName: tyk-app-claim
    - name: tyk-policies-storage
      persistentVolumeClaim:
        claimName: tyk-policies-claim
    - name: tyk-middleware-storage
      persistentVolumeClaim:
        claimName: tyk-middleware-claim

    extraVolumeMounts:
    - name: tyk-app-storage
      mountPath: /mnt/tyk-gateway/apps
    - name: tyk-policies-storage
      mountPath: /mnt/tyk-gateway/policies
    - name: tyk-middleware-storage
      mountPath: /mnt/tyk-gateway/middleware

See Running multiple instances of Tyk Gateway for a step-by-step guide on scaling Tyk Gateway on Kubernetes.

Setting Environment Variable

You can add environment variables for Tyk Gateway under extraEnvs. This can be used to override any default settings in the chart, e.g.

    extraEnvs:
      - name: TYK_GW_HASHKEYS
        value: "false"

Here is a reference of all Tyk Gateway Configuration Options.

Pump Configurations

To enable Pump, set global.components.pump to true, and configure below inside tyk-pump section.

Pump	Configuration
Prometheus Pump (Default)	Add prometheus to tyk-pump.pump.backend, and add connection details for prometheus under tyk-pump.pump.prometheusPump.
Mongo Pump	Add mongo to tyk-pump.pump.backend, and add connection details for mongo under global.mongo.
SQL Pump	Add postgres to tyk-pump.pump.backend, and add connection details for postgres under global.postgres.
Uptime Pump	Set tyk-pump.pump.uptimePumpBackend to 'mongo' or 'postgres'
Other Pumps	Add the required environment variables in tyk-pump.pump.extraEnvs

Prometheus Pump

Add prometheus to tyk-pump.pump.backend, and add connection details for prometheus under tyk-pump.pump.prometheusPump.

We also support monitoring using Prometheus Operator. All you have to do is set tyk-pump.pump.prometheusPump.prometheusOperator.enabled to true. This will create a PodMonitor resource for your Pump instance.

Mongo Pump

If you are using the MongoDB pumps in the tyk-oss installation you will require MongoDB installed for that as well.

To install Mongo you can use these rather excellent charts provided by Bitnami:

helm install tyk-mongo bitnami/mongodb --version {HELM_CHART_VERSION} --set "replicaSet.enabled=true" -n tyk

(follow notes from the installation output to get connection details and update them in values.yaml file)

NOTE: Here is list of supported MongoDB versions. Please make sure you are installing mongo helm chart that matches these version.

Important Note regarding MongoDB: This helm chart enables the PodDisruptionBudget for MongoDB with an arbiter replica-count of 1. If you intend to perform system maintenance on the node where the MongoDB pod is running and this maintenance requires for the node to be drained, this action will be prevented due the replica count being 1. Increase the replica count in the helm chart deployment to a minimum of 2 to remedy this issue.

Add following under the global section in values.yaml:

 # Set mongo connection details if you want to configure mongo pump.
 mongo:
    # The mongoURL value will allow you to set your MongoDB address.
    # Default value: mongodb://mongo.{{ .Release.Namespace }}.svc.cluster.local:27017/tyk_analytics
    # mongoURL: mongodb://mongo.tyk.svc.cluster.local:27017/tyk_analytics
    # If your MongoDB has a password you can add the username and password to the url
    # mongoURL: mongodb://root:[email protected]:27017/tyk_analytics?authSource=admin
    mongoURL: <MongoDB address>

    # Enables SSL for MongoDB connection. MongoDB instance will have to support that.
    # Default value: false
    # useSSL: false

SQL Pump

If you are using the SQL pumps in the tyk-oss installation you will require PostgreSQL installed for that as well.

To install PostgreSQL you can use these rather excellent charts provided by Bitnami:

helm install tyk-postgres bitnami/postgresql --set "auth.database=tyk_analytics" -n tyk

(follow notes from the installation output to get connection details and update them in values.yaml file)

Add following under the global section in values.yaml:

    # Set postgres connection details if you want to configure postgres pump.
    # Postgres connection string parameters.
    postgres:
        host: tyk-postgres-postgresql.tyk.svc.cluster.local
        port: 5432
        user: postgres
        password:
        database: tyk_analytics
        sslmode: disable

Uptime Pump

Uptime Pump can be configured by setting tyk-pump.pump.uptimePumpBackend in values.yaml file. It supports the following values

1. mongo: Used to set mongo pump for uptime analytics. Mongo Pump should be enabled.
2. postgres: Used to set postgres pump for uptime analytics. Postgres Pump should be enabled.
3. empty: Used to disable uptime analytics.

Other Pumps

To setup other backends for pump, refer to this document and add the required environment variables in tyk-pump.pump.extraEnvs

Protect Confidential Fields with Kubernetes Secrets

In the values.yaml file, some fields are considered confidential, such as APISecret, connection strings, etc. Declaring values for such fields as plain text might not be desired for all use cases. Instead, for certain fields, Kubernetes secrets can be referenced, and Kubernetes by itself configures values based on the referred secret.

This section describes how to use Kubernetes secrets to declare confidential fields.

APISecret

APISecret field configures a header value used in every interaction with Tyk Gateway API.

It can be configured via global.secrets.APISecret as a plain text or Kubernetes secret which includes APISecret key in it. Then, this secret must be referenced via global.secrets.useSecretName.

global:
    secrets:
        APISecret: CHANGEME
        useSecretName: "mysecret" # where mysecret includes `APISecret` key with the desired value.

Note: Once global.secrets.useSecretName is declared, it takes precedence over global.secrets.APISecret.

Redis Password

Redis password can also be provided via a secret. Store Redis password in Kubernetes secret and refer to this secret via global.redis.passSecret.name and global.redis.passSecret.keyName field, as follows:

global:
  redis:
     passSecret:
       name: "yourSecret"
       keyName: "redisPassKey"