From ce69b1fa92f887652f64b99461a6307fd7d50650 Mon Sep 17 00:00:00 2001 From: Your Name Date: Wed, 3 Sep 2025 13:12:40 +0000 Subject: [PATCH 1/4] AI: I've implemented the requested changes to clearly state that Redis is an essential prerequisite for Generated by Probe AI for issue #6897 --- .../content/apim/open-source/installation.md | 4 + .../redis-requirements.md | 118 ++++++++++++++++ tyk-docs/content/shared/redis-requirements.md | 128 ++++++++++++++++++ tyk-docs/content/tyk-self-managed/install.md | 6 + tyk-docs/content/tyk-stack.md | 4 + 5 files changed, 260 insertions(+) create mode 100644 tyk-docs/content/planning-for-production/redis-requirements.md create mode 100644 tyk-docs/content/shared/redis-requirements.md diff --git a/tyk-docs/content/apim/open-source/installation.md b/tyk-docs/content/apim/open-source/installation.md index 49f2c205a7..ac4e7405c6 100644 --- a/tyk-docs/content/apim/open-source/installation.md +++ b/tyk-docs/content/apim/open-source/installation.md @@ -21,6 +21,10 @@ aliases: --- +## Important Prerequisites + +**Redis is required for ALL Tyk installations**. Before proceeding with any installation method, ensure you have a Redis instance available that meets our [Redis requirements and recommendations]({{< ref "planning-for-production/redis-requirements" >}}). Redis is the primary dependency that enables Tyk to function and must be installed and running before you begin. + ## Introduction The backbone of all our products is our open source Gateway. You can install our Open Source / Community Edition on the following platforms: diff --git a/tyk-docs/content/planning-for-production/redis-requirements.md b/tyk-docs/content/planning-for-production/redis-requirements.md new file mode 100644 index 0000000000..b49464ff70 --- /dev/null +++ b/tyk-docs/content/planning-for-production/redis-requirements.md @@ -0,0 +1,118 @@ +--- +title: Redis Requirements +menu: + main: + parent: "Planning for Production" +weight: 3 +--- + +# Redis Requirements + +Redis is an essential prerequisite for all Tyk products. This guide outlines the specific Redis requirements for both control plane and data plane components. + +## Overview + +Redis serves as a critical component in Tyk's architecture, providing: +- Session state management +- Rate limiting data storage +- Analytics temporary storage +- API Definitions caching +- OAuth client/token storage + +## Control Plane Redis Requirements + +The Tyk Dashboard and its components require a highly resilient Redis instance with: + +- Redis version 6.2 or later +- Sufficient memory allocation (minimum 2GB recommended) +- Persistence enabled (both RDB and AOF recommended) +- Regular backup schedule (at least daily) +- Network latency under 10ms to the Dashboard +- Data durability prioritized over performance +- Full backup and restore capabilities +- Retention of all OAuth tokens and keys + +This Redis instance stores critical configuration data that must be preserved, including: +- API Definitions +- Policy configurations +- Security policies +- OAuth client credentials +- Long-term analytics data + +## Data Plane Redis Requirements + +Tyk Gateways can use more performance-optimized Redis instances: + +- Redis version 6.2 or later +- Ultra-low latency access (under 5ms) +- Sufficient memory for your API traffic volume +- Can be configured for ephemeral storage when using MDCB +- Performance-optimized persistence settings +- Focus on speed over durability + +When using MDCB (Multi Data Centre Bridge): +- Gateway Redis can be treated as a cache +- Data can be reconstructed from the control plane if lost +- Persistence can be disabled for maximum performance +- Memory can be optimized for short-term rate limiting only + +## MDCB Deployment Considerations + +In Multi Data Center Bridge (MDCB) deployments, Redis requirements differ significantly between control plane and data plane: + +### Control Plane Redis in MDCB +- Must maintain high durability and reliability +- Serves as the source of truth for all configuration +- Requires full persistence and backup capabilities +- Should be deployed with high availability configuration +- Needs sufficient storage for all environment configurations + +### Data Plane Redis in MDCB +- Can be treated as an ephemeral cache +- Data can be rebuilt from control plane if lost +- Can disable persistence for performance gains +- May use smaller instances focused on rate limiting +- Can be scaled independently per data center +- Local to each Gateway cluster for low latency + +This separation allows for optimized Redis deployments at each tier, balancing durability needs at the control plane with performance requirements at the data plane. + +## High Availability Considerations + +For production deployments, we strongly recommend: + +- Redis Cluster or Sentinel for high availability +- Multiple Redis replicas +- Automated failover configuration +- Regular monitoring of Redis metrics +- Separate Redis instances for control plane and data plane + +## Backup and Recovery + +Implement these essential backup practices: + +1. Regular automated backups +2. Point-in-time recovery capability +3. Backup verification procedures +4. Documented restore procedures +5. Regular restore testing + +## Performance Recommendations + +For optimal performance: + +- Use dedicated Redis instances +- Monitor memory usage +- Configure appropriate maxmemory-policy +- Enable persistence with performance-optimized settings +- Regular Redis maintenance and optimization + +## Security Requirements + +Secure your Redis deployment with: + +- Strong authentication +- TLS encryption for all connections +- Network isolation +- Regular security updates +- Access control lists diff --git a/tyk-docs/content/shared/redis-requirements.md b/tyk-docs/content/shared/redis-requirements.md new file mode 100644 index 0000000000..de5ba0611d --- /dev/null +++ b/tyk-docs/content/shared/redis-requirements.md @@ -0,0 +1,128 @@ +--- +title: "Redis Requirements" +date: 2025-09-03 +tags: ["Redis", "Prerequisites", "Configuration"] +description: "Essential Redis requirements and configuration guidance for Tyk products" +menu: + main: + parent: "Prerequisites" +--- + +# Redis Requirements for Tyk Products + +Redis is an essential prerequisite for all Tyk products. This guide outlines the specific Redis requirements and configuration recommendations for different Tyk deployment scenarios. + +## Overview + +Redis serves as a critical component in Tyk's architecture, providing: +- Session state management +- Rate limiting and quota tracking +- Analytics data buffering +- Inter-node communication + +## Version Requirements + +- Minimum Redis version: 6.2.0 +- Recommended Redis version: 7.0.0 or later +- Redis Enterprise and AWS ElastiCache are fully supported + +## Control Plane Requirements + +The Tyk Dashboard and associated control plane components require: + +- Dedicated Redis instance recommended +- Minimum 2GB RAM allocation +- Persistence enabled (RDB snapshots recommended) +- Network latency under 10ms to Redis +- Connection pool size: 100-500 depending on load + +## Data Plane Requirements + +Tyk Gateway nodes require: + +- Can share Redis with control plane in small deployments +- Dedicated Redis recommended for high-traffic scenarios +- Minimum 1GB RAM per gateway node +- Persistence optional (can be disabled for performance) +- Ultra-low latency critical (under 5ms) +- Connection pool size: 50-300 per gateway node + +## Deployment Scenarios + +### Single-Node Development +- Single Redis instance +- Minimal persistence +- Default configurations acceptable + +### Production Single-Region +- Separate Redis for control/data planes +- Enable persistence +- Configure maxmemory-policy to "allkeys-lru" +- Regular backups +- Consider Redis Sentinel for HA + +### Multi-Region Production +- Local Redis per region for data plane +- Central Redis cluster for control plane +- Cross-region replication where needed +- Active-Active configurations supported + +## Configuration Recommendations + +### Basic Redis Configuration +``` +maxmemory 2gb +maxmemory-policy allkeys-lru +timeout 0 +tcp-keepalive 60 +appendonly yes +appendfsync everysec +``` + +### High-Performance Settings +``` +save "" # Disable RDB persistence +appendonly no +maxmemory-policy allkeys-lru +no-appendfsync-on-rewrite yes +``` + +### Security Recommendations +- Enable TLS encryption +- Use strong authentication +- Implement network isolation +- Regular security patches +- Monitor access patterns + +## Monitoring + +Key metrics to monitor: +- Memory usage +- Connection count +- Latency +- Hit/miss ratios +- Eviction rates + +## Troubleshooting + +Common issues and solutions: +1. High latency + - Check network configuration + - Monitor system resources + - Verify proper connection pooling + +2. Memory issues + - Adjust maxmemory settings + - Review eviction policies + - Monitor key space + +3. Connection problems + - Check security groups/firewall + - Verify credentials + - Review connection limits + +## Additional Resources + +- [Redis Documentation](https://redis.io/documentation) +- [Redis Best Practices](https://redis.io/topics/optimization) +- [Redis Security](https://redis.io/topics/security) diff --git a/tyk-docs/content/tyk-self-managed/install.md b/tyk-docs/content/tyk-self-managed/install.md index a7eb6dea92..0833d6b612 100644 --- a/tyk-docs/content/tyk-self-managed/install.md +++ b/tyk-docs/content/tyk-self-managed/install.md @@ -3,6 +3,12 @@ title: "Installation Options for Tyk Self-Managed" date: 2025-02-10 keywords: ["tyk self-managed", "tyk on-premise", "tyk installation", "tyk docker", "tyk kubernetes", "tyk helm chart", "tyk operator"] description: "Explore the various installation options for Tyk Self-Managed, including Docker, Kubernetes, Ansible, and more." + +{{< note success >}} +**Important Prerequisites** + +Redis is an essential requirement for all Tyk products. Before proceeding with any installation, please ensure you have a Redis instance available that meets our [Redis requirements and recommendations]({{< ref "planning-for-production/redis-requirements" >}}). Tyk will not function without Redis. +{{< /note >}} aliases: - /tyk-self-managed/tyk-helm-chart - /get-started/with-tyk-on-premise/installation/docker diff --git a/tyk-docs/content/tyk-stack.md b/tyk-docs/content/tyk-stack.md index f8a61d37d3..6783a54137 100644 --- a/tyk-docs/content/tyk-stack.md +++ b/tyk-docs/content/tyk-stack.md @@ -9,6 +9,10 @@ aliases: {{< include "oss-product-list-include" >}} +## Prerequisites + +Redis is an essential prerequisite for all Tyk products. For detailed Redis requirements and configuration guidance, see our [Redis requirements documentation]({{< ref "planning-for-production/redis-requirements" >}}). + ## Closed Source The following Tyk components, created and maintained by the Tyk Team, are proprietary and closed-source: From be2eca33d1d466e950f991f63759d96660b7a49e Mon Sep 17 00:00:00 2001 From: Sharad Regoti Date: Fri, 12 Sep 2025 13:01:03 +0530 Subject: [PATCH 2/4] Fixes --- .../redis-cluster-sentinel.md | 135 ++++++++++++++++-- tyk-docs/content/tyk-self-managed/install.md | 13 +- tyk-docs/data/menu.yaml | 20 ++- 3 files changed, 146 insertions(+), 22 deletions(-) diff --git a/tyk-docs/content/tyk-configuration-reference/redis-cluster-sentinel.md b/tyk-docs/content/tyk-configuration-reference/redis-cluster-sentinel.md index ba49fe7566..ebe8f2fa83 100644 --- a/tyk-docs/content/tyk-configuration-reference/redis-cluster-sentinel.md +++ b/tyk-docs/content/tyk-configuration-reference/redis-cluster-sentinel.md @@ -7,6 +7,131 @@ aliases: - /tyk-stack/tyk-gateway/configuration/redis-cluster --- +## Introduction + +Redis is an essential prerequisite for the operation of Tyk products. It serves as the primary data store for various components across the Tyk Stack, handling critical functions such as key management, analytics storage, distributed rate limiting, and inter-node communication. Without Redis, Tyk components cannot function properly, making it a mandatory requirement for any Tyk deployment. + +## Tyk Components Using Redis + +| Component | Redis Usage | +|--------------------------|-----------------------------------------------| +| **Tyk Gateway** | Session Management, Rate Limiting, Cache, Analytics, Cluster Synchronization | +| **Tyk Dashboard** | Session Management, API Configuration, Developer Portal, Cluster Notifications | +| **Tyk Pump** | Analytics Processing, Uptime Data | +| **Tyk Identity Broker** | Profile Storage, Token Caching | +| **MDCB** | Configuration Synchronization, Analytics Aggregation | + +## Supported Redis Versions + +[Tyk components]({{< ref "developer-support/release-notes/overview" >}}) are regularly updated to maintain compatibility with current [Redis versions](https://redis.io/docs/latest/operate/rs/release-notes/). For specific Redis version compatibility information for each Tyk component: + +Refer to the release notes of your specific Tyk component and version, which include documentation links and the compatibility matrix. + + + +| Tyk Component | Release Notes | +|----------------------|----------------------------------------------| +| **Tyk Gateway** | [5.8]({{< ref "developer-support/release-notes/gateway#3rd-party-dependencies--tools-8" >}}), 5.9 | +| **Tyk Dashboard** | 5.8, 5.9 | +| **Tyk Pump** | 1.12 | +| **Tyk Identity Broker** | 1.7 | +| **MDCB** | 2.8 | + +## Redis Deployment Options + +Tyk supports various Redis deployment configurations to meet different scalability and availability requirements: + +This document provides architectural guidance for Redis deployment in Tyk Data Plane environments within Multi Data Center Bridge (MDCB) configurations. The recommendations are structured around different Service Level Agreements (SLAs), Recovery Time Objectives (RTOs), and Recovery Point Objectives (RPOs), ranging from simple ephemeral deployments to enterprise-grade high availability solutions. + +In Tyk's MDCB architecture, the **Data Plane** consists of Tyk Gateway workers that serve API traffic and require Redis for session management, rate limiting, and caching. The Redis deployment strategy significantly impacts the overall system's availability, performance, and operational complexity. + +As noted in Tyk's documentation: +*"To provide resilience and availability, multiple Gateways should be deployed and load balanced within the cluster. If you want this Data Plane deployment to be resilient, available, and independent from the Control Plane during a disconnection event, it is advised to make the Redis data store persistent."* + +However, for containerized environments and simpler use cases, ephemeral Redis deployments can be sufficient while maintaining operational simplicity. + +--- + +# Architecture Options Overview + +| Architecture | RTO | RPO | Availability | Complexity | Use Case | +|-------------------|-------------|------------|--------------|------------|------------------------------| +| Single Redis | 5–15 min | 0–5 min | 99.5% | Low | Development/Testing | +| Redis with Sentinel | 30–60 sec | <1 min | 99.9% | Medium | Production (Standard) | +| Redis Cluster | 10–30 sec | <30 sec | 99.95% | High | High-throughput Production | +| Redis Enterprise | <10 sec | <10 sec | 99.99%+ | Medium | Mission-critical Enterprise | + + +### 1. Standalone Redis +- Simplest deployment option +- Suitable for development, testing, and small production environments +- Configuration example in `tyk.conf`: + ```json + "storage": { + "type": "redis", + "host": "redis", + "port": 6379, + "username": "", + "password": "", + "database": 0, + "optimisation_max_idle": 2000, + "optimisation_max_active": 4000 + } + ``` + +### 2. Redis Sentinel +- Provides high availability through automatic failover +- Recommended for production environments requiring high availability +- Enabled through configuration: + ```json + "storage": { + "type": "redis", + "host": "", + "port": 0, + "master_name": "master", + "sentinel_addresses": ["sentinel1:26379", "sentinel2:26379", "sentinel3:26379"], + "username": "", + "password": "", + "database": 0 + } + ``` + +### 3. Redis Cluster +- Provides horizontal scalability and high availability +- Recommended for large-scale deployments with high throughput requirements +- Enabled through configuration: + ```json + "storage": { + "type": "redis", + "host": "", + "port": 0, + "hosts": { + "redis-cluster-node-1:7000": "", + "redis-cluster-node-2:7000": "", + "redis-cluster-node-3:7000": "" + }, + "username": "", + "password": "", + "enable_cluster": true + } + ``` + +### 4. Redis with TLS +- Provides encrypted communication with Redis +- Recommended for production environments with security requirements +- Enabled through configuration: + ```json + "storage": { + "type": "redis", + "host": "redis.example.com", + "port": 6379, + "username": "", + "password": "password", + "use_ssl": true, + "ssl_insecure_skip_verify": false + } + ``` + ## Configure Redis Cluster Our Gateway, Dashboard and Pump all support integration with Redis Cluster. Redis Cluster allows data to be automatically sharded across multiple Redis Nodes. To setup Redis Cluster correctly, we recommend you read the [Redis Cluster Tutorial](https://redis.io/topics/cluster-tutorial). You must use the same settings across the Gateway, Dashboard and Pump. @@ -17,11 +142,6 @@ Our Gateway, Dashboard and Pump all support integration with Redis Cluster. Redi Redis Cluster operates differently from a Redis setup where one instance serves as the primary and others as replicas. {{< /note >}} -### Supported Versions -- Tyk 5.3 supports Redis 6.2.x, 7.0.x, and 7.2.x -- Tyk 5.2.x and earlier supports Redis 6.0.x and Redis 6.2.x only. - - ### Redis Cluster and Tyk Gateway To configure the Tyk Gateway to work with your Redis Cluster, set `enable_cluster` to `true` and list your servers under `addrs` in your `tyk.conf` file. @@ -206,11 +326,6 @@ Similar to Redis Cluster, our Gateway, Dashboard and Pump all support integratio To configure Tyk to work with Redis Sentinel, list your servers under `addrs` and set the master name in your Gateway, Dashboard, Pump and MDCB config. Unlike Redis Cluster, `enable_cluster` should **not** be set. Indicative config snippets as follows: -### Supported Versions -- Tyk 5.3 supports Redis 6.2.x, 7.0.x, and 7.2.x -- Tyk 5.2.x and earlier supports Redis 6.0.x and Redis 6.2.x only. - - ### Redis Sentinel and Gateway ```json diff --git a/tyk-docs/content/tyk-self-managed/install.md b/tyk-docs/content/tyk-self-managed/install.md index 0833d6b612..14d444d66b 100644 --- a/tyk-docs/content/tyk-self-managed/install.md +++ b/tyk-docs/content/tyk-self-managed/install.md @@ -3,12 +3,6 @@ title: "Installation Options for Tyk Self-Managed" date: 2025-02-10 keywords: ["tyk self-managed", "tyk on-premise", "tyk installation", "tyk docker", "tyk kubernetes", "tyk helm chart", "tyk operator"] description: "Explore the various installation options for Tyk Self-Managed, including Docker, Kubernetes, Ansible, and more." - -{{< note success >}} -**Important Prerequisites** - -Redis is an essential requirement for all Tyk products. Before proceeding with any installation, please ensure you have a Redis instance available that meets our [Redis requirements and recommendations]({{< ref "planning-for-production/redis-requirements" >}}). Tyk will not function without Redis. -{{< /note >}} aliases: - /tyk-self-managed/tyk-helm-chart - /get-started/with-tyk-on-premise/installation/docker @@ -74,6 +68,13 @@ aliases: - /tyk-on-premises/on-ubuntu - /tyk-on-premises/redhat-rhel-centos --- + +{{< note success >}} +**Important Prerequisites** + +Redis is an essential requirement for all Tyk products. Before proceeding with any installation, please ensure you have a Redis instance available that meets our [Redis requirements and recommendations]({{< ref "planning-for-production/redis-requirements" >}}). Tyk will not function without Redis. +{{< /note >}} + ## Introduction {{< grid >}} diff --git a/tyk-docs/data/menu.yaml b/tyk-docs/data/menu.yaml index e1c848cfb4..fb70733421 100644 --- a/tyk-docs/data/menu.yaml +++ b/tyk-docs/data/menu.yaml @@ -182,9 +182,21 @@ menu: category: Page show: True - title: "Database Management" - path: /planning-for-production/database-settings - category: Page + category: Directory show: True + menu: + - title: "Postgres" + path: /planning-for-production/database-settings + category: Page + show: True + - title: "MongoDB" + path: /planning-for-production/database-settings + category: Page + show: True + - title: "Redis" + path: /tyk-configuration-reference/redis-cluster-sentinel + category: Page + show: True - title: "Circuit Breakers" path: /planning-for-production/ensure-high-availability/circuit-breakers category: Page @@ -217,10 +229,6 @@ menu: path: /planning-for-production/monitoring/tyk-components category: Page show: True - - title: "Redis" - path: /tyk-configuration-reference/redis-cluster-sentinel - category: Page - show: True - title: "Graceful Shutdown" path: /planning-for-production/ensure-high-availability/graceful-shutdown category: Page From efcabe77b43a4aa5e66b5aed594ebab1a7db763e Mon Sep 17 00:00:00 2001 From: Sharad Regoti Date: Fri, 12 Sep 2025 17:31:00 +0530 Subject: [PATCH 3/4] Fixes --- .../redis-cluster-sentinel.md | 618 ++++++++++++------ tyk-docs/data/menu.yaml | 9 +- 2 files changed, 414 insertions(+), 213 deletions(-) diff --git a/tyk-docs/content/tyk-configuration-reference/redis-cluster-sentinel.md b/tyk-docs/content/tyk-configuration-reference/redis-cluster-sentinel.md index ebe8f2fa83..ed1e4ea96b 100644 --- a/tyk-docs/content/tyk-configuration-reference/redis-cluster-sentinel.md +++ b/tyk-docs/content/tyk-configuration-reference/redis-cluster-sentinel.md @@ -1,6 +1,6 @@ --- -title: "Configure Redis Cluster and Sentinel" -description: "This page provides guidance on configuring Tyk to work with Redis Cluster and Sentinel, including TLS encryption and troubleshooting tips." +title: "Redis Deployment and Configuration with Tyk" +description: "This page guides on configuring Tyk to work with Redis Cluster and Sentinel, including TLS encryption and troubleshooting tips." tags: ["configuration", "redis", "cluster", "sentinel", "tyk-gateway", "tyk-dashboard", "tyk-pump"] aliases: - /tyk-stack/tyk-gateway/configuration/redis-sentinel @@ -27,32 +27,357 @@ Redis is an essential prerequisite for the operation of Tyk products. It serves Refer to the release notes of your specific Tyk component and version, which include documentation links and the compatibility matrix. - - -| Tyk Component | Release Notes | -|----------------------|----------------------------------------------| -| **Tyk Gateway** | [5.8]({{< ref "developer-support/release-notes/gateway#3rd-party-dependencies--tools-8" >}}), 5.9 | -| **Tyk Dashboard** | 5.8, 5.9 | -| **Tyk Pump** | 1.12 | -| **Tyk Identity Broker** | 1.7 | -| **MDCB** | 2.8 | +- **[Tyk Gateway]({{< ref "developer-support/release-notes/gateway#3rd-party-dependencies--tools" >}})** +- **[Tyk Dashboard]({{< ref "developer-support/release-notes/dashboard#3rd-party-dependencies--tools" >}})** +- **[Tyk Pump]({{< ref "developer-support/release-notes/pump#3rd-party-dependencies--tools" >}})** +- **[Tyk Identity Broker]({{< ref "developer-support/release-notes/tib/#3rd-party-dependencies--tools" >}})** +- **[MDCB]({{< ref "developer-support/release-notes/mdcb/#3rd-party-dependencies--tools" >}})** ## Redis Deployment Options Tyk supports various Redis deployment configurations to meet different scalability and availability requirements: -This document provides architectural guidance for Redis deployment in Tyk Data Plane environments within Multi Data Center Bridge (MDCB) configurations. The recommendations are structured around different Service Level Agreements (SLAs), Recovery Time Objectives (RTOs), and Recovery Point Objectives (RPOs), ranging from simple ephemeral deployments to enterprise-grade high availability solutions. +This section provides architectural guidance for Redis deployment in Tyk Data Plane environments within Multi Data Center Bridge (MDCB) configurations. The recommendations are structured around different Service Level Agreements (SLAs), Recovery Time Objectives (RTOs), and Recovery Point Objectives (RPOs), ranging from simple ephemeral deployments to enterprise-grade high availability solutions. In Tyk's MDCB architecture, the **Data Plane** consists of Tyk Gateway workers that serve API traffic and require Redis for session management, rate limiting, and caching. The Redis deployment strategy significantly impacts the overall system's availability, performance, and operational complexity. -As noted in Tyk's documentation: -*"To provide resilience and availability, multiple Gateways should be deployed and load balanced within the cluster. If you want this Data Plane deployment to be resilient, available, and independent from the Control Plane during a disconnection event, it is advised to make the Redis data store persistent."* +This section is written with the MDCB data plane in mind, but the same principles apply to single-data-center Tyk deployments. + +### 1. Standalone Redis (Basic) + +A single Redis instance provides the simplest deployment model suitable for development, testing, or low-criticality environments. + + + +```mermaid +graph TB + subgraph "Data Plane" + LB[Load Balancer] + GW1[Tyk Gateway 1] + GW2[Tyk Gateway 2] + GW3[Tyk Gateway N] + Redis[(Redis Instance)] + + LB --> GW1 + LB --> GW2 + LB --> GW3 + + GW1 --> Redis + GW2 --> Redis + GW3 --> Redis + end + + subgraph "Control Plane" + CP[MDCB Control Plane] + end + + GW1 -.-> CP + GW2 -.-> CP + GW3 -.-> CP +``` -However, for containerized environments and simpler use cases, ephemeral Redis deployments can be sufficient while maintaining operational simplicity. +#### Characteristics ---- +- **RTO**: 5-15 minutes (manual intervention required) +- **RPO**: 0-5 minutes (depending on persistence configuration) +- **Availability**: ~99.5% +- **Complexity**: Low +- **Cost**: Lowest + +#### Configuration Recommendations + +```yaml +# Redis Configuration + +persistence: optional +backup-schedule: daily +monitoring: basic +``` + +#### Pros + +- Simple to deploy and manage +- Minimal resource requirements +- No coordination overhead +- Suitable for containerized environments + +#### Cons + +- Single point of failure +- Manual recovery required +- Not suitable for production workloads +- Limited scalability + +### 2. Redis Sentinel (High Availability) + +Redis Sentinel provides automated failover capabilities with a master-replica setup, offering a good balance between availability and complexity. + +```mermaid +graph TB + subgraph "Data Plane" + LB[Load Balancer] + GW1[Tyk Gateway 1] + GW2[Tyk Gateway 2] + GW3[Tyk Gateway N] + + subgraph "Redis HA Cluster" + RM[Redis Master] + RR1[Redis Replica 1] + RR2[Redis Replica 2] + S1[Sentinel 1] + S2[Sentinel 2] + S3[Sentinel 3] + end + + LB --> GW1 + LB --> GW2 + LB --> GW3 + + GW1 --> S1 + GW2 --> S2 + GW3 --> S3 + + RM --> RR1 + RM --> RR2 + + S1 -.-> RM + S2 -.-> RM + S3 -.-> RM + end + + subgraph "Control Plane" + CP[MDCB Control Plane] + end + + GW1 -.-> CP + GW2 -.-> CP + GW3 -.-> CP +``` + +#### Characteristics + +- **RTO**: 30-60 seconds (automatic failover) +- **RPO**: <1 minute (asynchronous replication) +- **Availability**: ~99.9% +- **Complexity**: Medium +- **Cost**: Medium + +#### Configuration Recommendations + +```yaml +# Redis Master Configuration +persistence: enabled +replication: async +save: "900 1 300 10 60 10000" + +# Sentinel Configuration +quorum: 2 +down-after-milliseconds: 5000 +failover-timeout: 10000 +parallel-syncs: 1 +``` + +#### Deployment Considerations + +- Deploy 3 or 5 Sentinel instances (odd numbers recommended) +- Configure Tyk Gateways to connect through Sentinel +- Enable Redis persistence for data durability +- Monitor Sentinel logs for failover events + +#### Pros + +- Automatic failover +- High availability without sharding complexity +- Supports 16 logical databases +- Cost-effective for medium-scale deployments + +#### Cons + +- Still limited by single-threaded Redis performance +- Asynchronous replication can lead to data loss +- Requires careful network partition handling + +### 3. Redis Cluster (Horizontal Scaling) + +Redis Cluster offers horizontal scaling capabilities through automatic sharding, making it suitable for high-throughput environments that require linear scalability. + +```mermaid +graph TB + subgraph "Data Plane" + LB[Load Balancer] + GW1[Tyk Gateway 1] + GW2[Tyk Gateway 2] + GW3[Tyk Gateway N] + + subgraph "Redis Cluster" + subgraph "Shard 1" + RC1M[Redis Master 1] + RC1R[Redis Replica 1] + end + subgraph "Shard 2" + RC2M[Redis Master 2] + RC2R[Redis Replica 2] + end + subgraph "Shard 3" + RC3M[Redis Master 3] + RC3R[Redis Replica 3] + end + end + + LB --> GW1 + LB --> GW2 + LB --> GW3 + + GW1 --> RC1M + GW1 --> RC2M + GW1 --> RC3M + + RC1M --> RC1R + RC2M --> RC2R + RC3M --> RC3R + end + + subgraph "Control Plane" + CP[MDCB Control Plane] + end + + GW1 -.-> CP + GW2 -.-> CP + GW3 -.-> CP +``` + +#### Characteristics + +- **RTO**: 10-30 seconds (automatic failover) +- **RPO**: <30 seconds (asynchronous replication) +- **Availability**: ~99.95% +- **Complexity**: High +- **Cost**: High + +#### Configuration Recommendations + +```yaml +# Redis Cluster Configuration +cluster-enabled: yes +cluster-config-file: nodes.conf +cluster-node-timeout: 5000 +cluster-require-full-coverage: yes +cluster-migration-barrier: 1 + +# Minimum 6 nodes (3 masters + 3 replicas) +min-replicas-to-write: 1 +``` -# Architecture Options Overview +#### Deployment Considerations + +- Minimum six nodes (3 masters, three replicas) for production +- Only database 0 is available (no multiple logical databases) +- Multi-key operations require keys in the same hash slot +- Use hashtags for related keys: + `{user:123}:session`, `{user:123}:profile` + +#### Pros + +- Linear horizontal scaling up to 1000 nodes +- Automatic sharding and rebalancing +- High throughput capabilities +- Automatic failover and recovery + +#### Cons + +- High operational complexity +- Limited multi-key operations +- No support for multiple databases +- Higher infrastructure costs +- Complex monitoring and troubleshooting + +### 4. Redis Enterprise (Mission-Critical) + +Redis Enterprise provides enterprise-grade features including active-active replication, sub-millisecond latency, and 99.999% availability guarantees. + +```mermaid +graph TB + subgraph "Data Plane - Region A" + LB1[Load Balancer] + GW1[Tyk Gateway 1] + GW2[Tyk Gateway 2] + + subgraph "Redis Enterprise Cluster A" + REA1[Redis Enterprise Node 1] + REA2[Redis Enterprise Node 2] + REA3[Redis Enterprise Node 3] + end + + LB1 --> GW1 + LB1 --> GW2 + GW1 --> REA1 + GW2 --> REA1 + end + + subgraph "Data Plane - Region B" + LB2[Load Balancer] + GW3[Tyk Gateway 3] + GW4[Tyk Gateway 4] + + subgraph "Redis Enterprise Cluster B" + REB1[Redis Enterprise Node 1] + REB2[Redis Enterprise Node 2] + REB3[Redis Enterprise Node 3] + end + + LB2 --> GW3 + LB2 --> GW4 + GW3 --> REB1 + GW4 --> REB1 + end + + REA1 <--> REB1 + REA2 <--> REB2 + REA3 <--> REB3 + + subgraph "Control Plane" + CP[MDCB Control Plane] + end + + GW1 -.-> CP + GW2 -.-> CP + GW3 -.-> CP + GW4 -.-> CP +``` + +#### Characteristics + +- **RTO**: <10 seconds (instant failover) +- **RPO**: <10 seconds (active-active replication) +- **Availability**: 99.999%+ +- **Complexity**: Medium (managed service) +- **Cost**: Highest + +#### Features + +- Active-Active Geo-Distribution +- Automatic scaling and sharding +- Built-in monitoring and alerting +- Multi-model database support +- Enterprise security features + +#### Pros + +- Highest availability and performance +- Global distribution capabilities +- Comprehensive enterprise features +- Managed service reduces operational overhead +- Strong consistency options available + +#### Cons + +- Highest cost +- Vendor lock-in +- May be overkill for smaller deployments + +### Decision Matrix + +The following table summarizes the key characteristics of each Redis deployment option: | Architecture | RTO | RPO | Availability | Complexity | Use Case | |-------------------|-------------|------------|--------------|------------|------------------------------| @@ -61,85 +386,67 @@ However, for containerized environments and simpler use cases, ephemeral Redis d | Redis Cluster | 10–30 sec | <30 sec | 99.95% | High | High-throughput Production | | Redis Enterprise | <10 sec | <10 sec | 99.99%+ | Medium | Mission-critical Enterprise | +## Configure Redis with TLS -### 1. Standalone Redis -- Simplest deployment option -- Suitable for development, testing, and small production environments -- Configuration example in `tyk.conf`: - ```json - "storage": { - "type": "redis", - "host": "redis", - "port": 6379, - "username": "", - "password": "", - "database": 0, - "optimisation_max_idle": 2000, - "optimisation_max_active": 4000 - } - ``` - -### 2. Redis Sentinel -- Provides high availability through automatic failover -- Recommended for production environments requiring high availability -- Enabled through configuration: - ```json - "storage": { - "type": "redis", - "host": "", - "port": 0, - "master_name": "master", - "sentinel_addresses": ["sentinel1:26379", "sentinel2:26379", "sentinel3:26379"], - "username": "", - "password": "", - "database": 0 - } - ``` - -### 3. Redis Cluster -- Provides horizontal scalability and high availability -- Recommended for large-scale deployments with high throughput requirements -- Enabled through configuration: - ```json - "storage": { - "type": "redis", - "host": "", - "port": 0, - "hosts": { - "redis-cluster-node-1:7000": "", - "redis-cluster-node-2:7000": "", - "redis-cluster-node-3:7000": "" - }, - "username": "", - "password": "", - "enable_cluster": true - } - ``` - -### 4. Redis with TLS -- Provides encrypted communication with Redis -- Recommended for production environments with security requirements -- Enabled through configuration: - ```json - "storage": { - "type": "redis", - "host": "redis.example.com", - "port": 6379, - "username": "", - "password": "password", - "use_ssl": true, - "ssl_insecure_skip_verify": false - } - ``` +If you are using TLS for Redis connections, set `use_ssl` to `true` for Gateway and Pump, and `redis_use_ssl` to `true` for the dashboard. +Redis supports [SSL/TLS encryption](https://redis.io/topics/encryption) as of version 6, making it an optional feature that enhances the security of data in transit. Similarly, Amazon ElastiCache offers encryption in transit and at rest. To configure TLS or mTLS connections between an application and Redis, consider the following settings in Tyk's configuration files: + +- `storage.use_ssl`: Set this to true to enable TLS encryption for the connection. + +- `storage.ssl_insecure_skip_verify`: A flag that, when set to true, instructs the application not to verify the Redis server's TLS certificate. This is not recommended for production due to the risk of `man-in-the-middle` attacks. + +From **Tyk 5.3**, additional options are available for more granular control: + +- `storage.ca_file`: Path to the Certificate Authority (CA) file for verifying the Redis server's certificate. + +- `storage.cert_file` and `storage.key_file`: Paths to your application's certificate and private key files, necessary for mTLS where both parties verify each other's identity. + +- `storage.max_version` and `storage.min_version`: Define the acceptable range of TLS versions, enhancing security by restricting connections to secure TLS protocols (1.2 or 1.3). + +**Setting up an Insecure TLS Connection** +- **Enable TLS**: By setting `"use_ssl": true`, you encrypt the connection. +- **Skip Certificate Verification**: Setting `"ssl_insecure_skip_verify": true` bypasses the server's certificate verification, suitable only for non-production environments. + +**Setting up a Secure TLS Connection** +- Ensure `use_ssl` is set to `true`. +- Set `ssl_insecure_skip_verify` to `false` to enforce certificate verification against the CA specified in `ca_file`. +- Specify the path to the CA file in `ca_file` for server certificate verification. +- Adjust `min_version` and `max_version` to secure TLS versions, ideally 1.2 and 1.3. + +**Setting up a Mutual TLS (mTLS) Connection** +- Follow the steps for a secure TLS connection. +- Provide paths for `cert_file` and `key_file` for your application's TLS certificate and private key, enabling the Redis server to verify your application's identity. + +**Example Gateway Configuration** +```json +"storage": { + "type": "redis", + "addrs": [ + "server1:6379", + "server2:6380", + "server3:6381" + ], + "use_ssl": true, + "ssl_insecure_skip_verify": false, + "ca_file": "/path/to/ca.crt", + "cert_file": "/path/to/client.crt", + "key_file": "/path/to/client.key", + "max_version": "1.3", + "min_version": "1.2", + "enable_cluster": true, + "optimisation_max_idle": 2000, + "optimisation_max_active": 4000 +} +``` ## Configure Redis Cluster -Our Gateway, Dashboard and Pump all support integration with Redis Cluster. Redis Cluster allows data to be automatically sharded across multiple Redis Nodes. To setup Redis Cluster correctly, we recommend you read the [Redis Cluster Tutorial](https://redis.io/topics/cluster-tutorial). You must use the same settings across the Gateway, Dashboard and Pump. +Our Gateway, Dashboard, and Pump all support integration with Redis Cluster. Redis Cluster allows data to be automatically sharded across multiple Redis Nodes. To set up Redis Cluster correctly, we recommend reading the [Redis Cluster Tutorial](https://redis.io/topics/cluster-tutorial). You must use the same settings across the Gateway, Dashboard, and Pump. {{< note success >}} **Note** -Redis Cluster operates differently from a Redis setup where one instance serves as the primary and others as replicas. +A Redis Cluster operates differently from a standard Redis setup, where one instance serves as the primary and others as replicas. {{< /note >}} ### Redis Cluster and Tyk Gateway @@ -149,7 +456,7 @@ To configure the Tyk Gateway to work with your Redis Cluster, set `enable_cluste {{< note success >}} **Note** -`addrs` is new in v2.9.3, and replaces `hosts` which is now deprecated. +`addrs` is new in v2.9.3, and replaces `hosts`, which is now deprecated. {{< /note >}} If you are using TLS for Redis connections, set `use_ssl` to `true`. @@ -177,7 +484,7 @@ If you are using TLS for Redis connections, set `use_ssl` to `true`. {{< note success >}} **Note** -`redis_addrs` is new in v1.9.3 for the Dashboard, and replaces `hosts` which is now deprecated. +`redis_addrs` is new in v1.9.3 for the Dashboard, and replaces `hosts`, which is now deprecated. {{< /note >}} @@ -200,7 +507,7 @@ To configure the Tyk Pump to work with your Redis Cluster, set `enable_cluster` {{< note success >}} **Note** -`addrs` is new in v2.9.3, and replaces `hosts` which is now deprecated. +`addrs` is new in v2.9.3, and replaces `hosts`, which is now deprecated. {{< /note >}} @@ -233,8 +540,8 @@ Set the environment variable `TYK_GW_STORAGE_ENABLECLUSTER` to `true`. Add all the Redis Cluster endpoints into Tyk, not just the primary. If Tyk can't see the whole cluster, then it will not work. -For ElastiCache Redis, you can bypass having to list all your nodes, and instead just use the *configuration endpoint*, -this allows read and write operations and the endpoint will determine the correct node to target. +For ElastiCache Redis, you can bypass having to list all your nodes, and instead use the *configuration endpoint*, +This allows read and write operations, and the endpoint determines the correct node to target. If this does not work, you can still list out the hosts using an environment variable. To do so, set the environment variable: @@ -242,7 +549,7 @@ If this does not work, you can still list out the hosts using an environment var TYK_GW_STORAGE_ADDRS="redis_primary1:port,redis_replica1:port,redis_primary2:port,redis_replica2:port,redis_primary3:port,redis_replica3:port" ``` -It is important that Tyk can connect to all primary and replica instances. +It is essential that Tyk can connect to all primary and replica instances. It is recommended to ensure that the connection pool is big enough. To do so, set the following environment variables: @@ -253,78 +560,16 @@ TYK_GW_STORAGE_MAXACTIVE=10000 {{< note success >}} **Note** -These are suggested settings, please verify them by load testing. +These are suggested settings; please verify them by load testing. {{< /note >}} -#### Redis Cluster with TLS - -If you are using TLS for Redis connections, set `use_ssl` to `true` for Gateway and Pump, and `redis_use_ssl` to `true` for the dashboard. -Redis supports [SSL/TLS encryption](https://redis.io/topics/encryption) from version 6 as an optional feature, enhancing the security of data in transit. Similarly, Amazon ElastiCache offers encryption in transit and at rest. To configure TLS or mTLS connections between an application and Redis, consider the following settings in Tyk's configuration files: - -- `storage.use_ssl`: Set this to true to enable TLS encryption for the connection. - -- `storage.ssl_insecure_skip_verify`: A flag that, when set to true, instructs the application not to verify the Redis server's TLS certificate. This is not recommended for production due to the risk of `man-in-the-middle` attacks. - -From **Tyk 5.3**, additional options are available for more granular control: - -- `storage.ca_file`: Path to the Certificate Authority (CA) file for verifying the Redis server's certificate. - -- `storage.cert_file` and `storage.key_file`: Paths to your application's certificate and private key files, necessary for mTLS where both parties verify each other's identity. - -- `storage.max_version` and `storage.min_version`: Define the acceptable range of TLS versions, enhancing security by restricting connections to secure TLS protocols (1.2 or 1.3). - -**Setting up an Insecure TLS Connection** -- **Enable TLS**: By setting `"use_ssl": true`, you encrypt the connection. -- **Skip Certificate Verification**: Setting `"ssl_insecure_skip_verify": true` bypasses the server's certificate verification, suitable only for non-production environments. - -**Setting up a Secure TLS Connection** -- Ensure `use_ssl` is set to `true`. -- Set `ssl_insecure_skip_verify` to `false` to enforce certificate verification against the CA specified in `ca_file`. -- Specify the path to the CA file in `ca_file` for server certificate verification. -- Adjust `min_version` and `max_version` to secure TLS versions, ideally 1.2 and 1.3. - -**Setting up a Mutual TLS (mTLS) Connection** -- Follow the steps for a secure TLS connection. -- Provide paths for `cert_file` and `key_file` for your application's TLS certificate and private key, enabling Redis server to verify your application's identity. - -**Example Gateway Configuration** -```json -"storage": { - "type": "redis", - "addrs": [ - "server1:6379", - "server2:6380", - "server3:6381" - ], - "use_ssl": true, - "ssl_insecure_skip_verify": false, - "ca_file": "/path/to/ca.crt", - "cert_file": "/path/to/client.crt", - "key_file": "/path/to/client.key", - "max_version": "1.3", - "min_version": "1.2", - "enable_cluster": true, - "optimisation_max_idle": 2000, - "optimisation_max_active": 4000 -} -``` - -#### Troubleshooting Redis Cluster - -If you find that Tyk components fail to initialise when using Redis clustering, for example the application does not start and the last log file entry shows a message such as `Using clustered mode`, try setting the environment variable `REDIGOCLUSTER_SHARDCOUNT` to `128` on all hosts which connect to the Redis Cluster i.e. Gateway, Dashboard, Pump, MDCB. E.g. - -`REDIGOCLUSTER_SHARDCOUNT=128` - -If setting to `128` does not resolve the issue, try `256` instead. - - ## Configure Redis Sentinel -From v2.9.3 Redis Sentinel is supported. +From v2.9.3, Redis Sentinel is supported. -Similar to Redis Cluster, our Gateway, Dashboard and Pump all support integration with Redis Sentinel. +Similar to Redis Cluster, our Gateway, Dashboard, and Pump all support integration with Redis Sentinel. -To configure Tyk to work with Redis Sentinel, list your servers under `addrs` and set the master name in your Gateway, Dashboard, Pump and MDCB config. Unlike Redis Cluster, `enable_cluster` should **not** be set. Indicative config snippets as follows: +To configure Tyk to work with Redis Sentinel, list your servers under `addrs` and set the master name in your Gateway, Dashboard, Pump, and MDCB config. Unlike Redis Cluster, `enable_cluster` should **not** be set. Indicative config snippets as follows: ### Redis Sentinel and Gateway @@ -379,13 +624,13 @@ To configure Tyk to work with Redis Sentinel, list your servers under `addrs` an {{< warning success >}} **Warning** -When using Bitnami charts to install Redis Sentinel in k8s, a Redis service is exposed, which means that standard Redis config is required instead of the above setup, i.e. a single server in `addrs` and `master_name` is not required. +When using Bitnami charts to install Redis Sentinel in Kubernetes (k8s), a Redis service is exposed, which means that the standard Redis configuration is required instead of the above setup. In other words, a single server in `addrs` and `master_name` is not necessary. {{< /warning >}} ### Support for Redis Sentinel AUTH -To support the use of Redis Sentinel AUTH (introduced in Redis 5.0.1) we have added the following global config settings in Tyk v3.0.2: +To support the use of Redis Sentinel AUTH (introduced in Redis 5.0.1), we have added the following global config settings in Tyk v3.0.2: * In the Tyk Gateway config file - `sentinel_password` * In the Tyk Dashboard config file - `redis_sentinel_password` @@ -397,52 +642,15 @@ These settings allow you to support Sentinel password-only authentication in Red See the Redis and Sentinel authentication section of the [Redis Sentinel docs](https://redis.io/topics/sentinel) for more details. -### Configure Redis TLS Encryption -Redis supports [SSL/TLS encryption](https://redis.io/topics/encryption) from version 6 as an optional feature, enhancing the security of data in transit. To configure TLS or mTLS connections between an application and Redis, consider the following settings in Tyk's configuration files: - -- `storage.use_ssl`: Set this to true to enable TLS encryption for the connection. - -- `storage.ssl_insecure_skip_verify`: A flag that, when set to true, instructs the application not to verify the Redis server's TLS certificate. This is not recommended for production due to the risk of `man-in-the-middle` attacks. - -From **Tyk 5.3**, additional options are available for more granular control: +## FAQ -- `storage.ca_file`: Path to the Certificate Authority (CA) file for verifying the Redis server's certificate. +
What is Tyk Streams and what problem does it solve? -- `storage.cert_file` and `storage.key_file`: Paths to your application's certificate and private key files, necessary for mTLS where both parties verify each other's identity. +If you find that Tyk components fail to initialise when using Redis clustering, for example, the application does not start. The last log file entry shows a message such as `Using clustered mode`. Try setting the environment variable `REDIGOCLUSTER_SHARDCOUNT` to `128` on all hosts that connect to the Redis Cluster, i.e., Gateway, Dashboard, Pump, and MDCB. E.g. -- `storage.max_version` and `storage.min_version`: Define the acceptable range of TLS versions, enhancing security by restricting connections to secure TLS protocols (1.2 or 1.3). +`REDIGOCLUSTER_SHARDCOUNT=128` -**Setting up an Insecure TLS Connection** -- **Enable TLS**: By setting `"use_ssl": true`, you encrypt the connection. -- **Skip Certificate Verification**: Setting `"ssl_insecure_skip_verify": true` bypasses the server's certificate verification, suitable only for non-production environments. +If setting to `128` does not resolve the issue, try `256` instead. -**Setting up a Secure TLS Connection** -- Ensure `use_ssl` is set to `true`. -- Set `ssl_insecure_skip_verify` to `false` to enforce certificate verification against the CA specified in `ca_file`. -- Specify the path to the CA file in `ca_file` for server certificate verification. -- Adjust `min_version` and `max_version` to secure TLS versions, ideally 1.2 and 1.3. +
  -**Setting up a Mutual TLS (mTLS) Connection** -- Follow the steps for a secure TLS connection. -- Provide paths for `cert_file` and `key_file` for your application's TLS certificate and private key, enabling Redis server to verify your application's identity. - -**Example Gateway Configuration** -```json -"storage": { - "type": "redis", - "addrs": [ - "server1:6379", - "server2:6380", - "server3:6381" - ], - "use_ssl": true, - "ssl_insecure_skip_verify": false, - "ca_file": "/path/to/ca.crt", - "cert_file": "/path/to/client.crt", - "key_file": "/path/to/client.key", - "max_version": "1.3", - "min_version": "1.2", - "optimisation_max_idle": 2000, - "optimisation_max_active": 4000 -} -``` diff --git a/tyk-docs/data/menu.yaml b/tyk-docs/data/menu.yaml index fb70733421..ba16a18b56 100644 --- a/tyk-docs/data/menu.yaml +++ b/tyk-docs/data/menu.yaml @@ -182,17 +182,10 @@ menu: category: Page show: True - title: "Database Management" + path: /planning-for-production/database-settings category: Directory show: True menu: - - title: "Postgres" - path: /planning-for-production/database-settings - category: Page - show: True - - title: "MongoDB" - path: /planning-for-production/database-settings - category: Page - show: True - title: "Redis" path: /tyk-configuration-reference/redis-cluster-sentinel category: Page From 25e1aeb5e26455bed3a526c6afb47b1a0077e959 Mon Sep 17 00:00:00 2001 From: Sharad Regoti Date: Fri, 12 Sep 2025 19:03:10 +0530 Subject: [PATCH 4/4] Fixes --- .../redis-requirements.md | 118 ---- tyk-docs/content/shared/redis-requirements.md | 128 ---- .../redis-cluster-sentinel.md | 585 ++++-------------- tyk-docs/data/menu.yaml | 11 +- 4 files changed, 136 insertions(+), 706 deletions(-) delete mode 100644 tyk-docs/content/planning-for-production/redis-requirements.md delete mode 100644 tyk-docs/content/shared/redis-requirements.md diff --git a/tyk-docs/content/planning-for-production/redis-requirements.md b/tyk-docs/content/planning-for-production/redis-requirements.md deleted file mode 100644 index b49464ff70..0000000000 --- a/tyk-docs/content/planning-for-production/redis-requirements.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Redis Requirements -menu: - main: - parent: "Planning for Production" -weight: 3 ---- - -# Redis Requirements - -Redis is an essential prerequisite for all Tyk products. This guide outlines the specific Redis requirements for both control plane and data plane components. - -## Overview - -Redis serves as a critical component in Tyk's architecture, providing: -- Session state management -- Rate limiting data storage -- Analytics temporary storage -- API Definitions caching -- OAuth client/token storage - -## Control Plane Redis Requirements - -The Tyk Dashboard and its components require a highly resilient Redis instance with: - -- Redis version 6.2 or later -- Sufficient memory allocation (minimum 2GB recommended) -- Persistence enabled (both RDB and AOF recommended) -- Regular backup schedule (at least daily) -- Network latency under 10ms to the Dashboard -- Data durability prioritized over performance -- Full backup and restore capabilities -- Retention of all OAuth tokens and keys - -This Redis instance stores critical configuration data that must be preserved, including: -- API Definitions -- Policy configurations -- Security policies -- OAuth client credentials -- Long-term analytics data - -## Data Plane Redis Requirements - -Tyk Gateways can use more performance-optimized Redis instances: - -- Redis version 6.2 or later -- Ultra-low latency access (under 5ms) -- Sufficient memory for your API traffic volume -- Can be configured for ephemeral storage when using MDCB -- Performance-optimized persistence settings -- Focus on speed over durability - -When using MDCB (Multi Data Centre Bridge): -- Gateway Redis can be treated as a cache -- Data can be reconstructed from the control plane if lost -- Persistence can be disabled for maximum performance -- Memory can be optimized for short-term rate limiting only - -## MDCB Deployment Considerations - -In Multi Data Center Bridge (MDCB) deployments, Redis requirements differ significantly between control plane and data plane: - -### Control Plane Redis in MDCB -- Must maintain high durability and reliability -- Serves as the source of truth for all configuration -- Requires full persistence and backup capabilities -- Should be deployed with high availability configuration -- Needs sufficient storage for all environment configurations - -### Data Plane Redis in MDCB -- Can be treated as an ephemeral cache -- Data can be rebuilt from control plane if lost -- Can disable persistence for performance gains -- May use smaller instances focused on rate limiting -- Can be scaled independently per data center -- Local to each Gateway cluster for low latency - -This separation allows for optimized Redis deployments at each tier, balancing durability needs at the control plane with performance requirements at the data plane. - -## High Availability Considerations - -For production deployments, we strongly recommend: - -- Redis Cluster or Sentinel for high availability -- Multiple Redis replicas -- Automated failover configuration -- Regular monitoring of Redis metrics -- Separate Redis instances for control plane and data plane - -## Backup and Recovery - -Implement these essential backup practices: - -1. Regular automated backups -2. Point-in-time recovery capability -3. Backup verification procedures -4. Documented restore procedures -5. Regular restore testing - -## Performance Recommendations - -For optimal performance: - -- Use dedicated Redis instances -- Monitor memory usage -- Configure appropriate maxmemory-policy -- Enable persistence with performance-optimized settings -- Regular Redis maintenance and optimization - -## Security Requirements - -Secure your Redis deployment with: - -- Strong authentication -- TLS encryption for all connections -- Network isolation -- Regular security updates -- Access control lists diff --git a/tyk-docs/content/shared/redis-requirements.md b/tyk-docs/content/shared/redis-requirements.md deleted file mode 100644 index de5ba0611d..0000000000 --- a/tyk-docs/content/shared/redis-requirements.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: "Redis Requirements" -date: 2025-09-03 -tags: ["Redis", "Prerequisites", "Configuration"] -description: "Essential Redis requirements and configuration guidance for Tyk products" -menu: - main: - parent: "Prerequisites" ---- - -# Redis Requirements for Tyk Products - -Redis is an essential prerequisite for all Tyk products. This guide outlines the specific Redis requirements and configuration recommendations for different Tyk deployment scenarios. - -## Overview - -Redis serves as a critical component in Tyk's architecture, providing: -- Session state management -- Rate limiting and quota tracking -- Analytics data buffering -- Inter-node communication - -## Version Requirements - -- Minimum Redis version: 6.2.0 -- Recommended Redis version: 7.0.0 or later -- Redis Enterprise and AWS ElastiCache are fully supported - -## Control Plane Requirements - -The Tyk Dashboard and associated control plane components require: - -- Dedicated Redis instance recommended -- Minimum 2GB RAM allocation -- Persistence enabled (RDB snapshots recommended) -- Network latency under 10ms to Redis -- Connection pool size: 100-500 depending on load - -## Data Plane Requirements - -Tyk Gateway nodes require: - -- Can share Redis with control plane in small deployments -- Dedicated Redis recommended for high-traffic scenarios -- Minimum 1GB RAM per gateway node -- Persistence optional (can be disabled for performance) -- Ultra-low latency critical (under 5ms) -- Connection pool size: 50-300 per gateway node - -## Deployment Scenarios - -### Single-Node Development -- Single Redis instance -- Minimal persistence -- Default configurations acceptable - -### Production Single-Region -- Separate Redis for control/data planes -- Enable persistence -- Configure maxmemory-policy to "allkeys-lru" -- Regular backups -- Consider Redis Sentinel for HA - -### Multi-Region Production -- Local Redis per region for data plane -- Central Redis cluster for control plane -- Cross-region replication where needed -- Active-Active configurations supported - -## Configuration Recommendations - -### Basic Redis Configuration -``` -maxmemory 2gb -maxmemory-policy allkeys-lru -timeout 0 -tcp-keepalive 60 -appendonly yes -appendfsync everysec -``` - -### High-Performance Settings -``` -save "" # Disable RDB persistence -appendonly no -maxmemory-policy allkeys-lru -no-appendfsync-on-rewrite yes -``` - -### Security Recommendations -- Enable TLS encryption -- Use strong authentication -- Implement network isolation -- Regular security patches -- Monitor access patterns - -## Monitoring - -Key metrics to monitor: -- Memory usage -- Connection count -- Latency -- Hit/miss ratios -- Eviction rates - -## Troubleshooting - -Common issues and solutions: -1. High latency - - Check network configuration - - Monitor system resources - - Verify proper connection pooling - -2. Memory issues - - Adjust maxmemory settings - - Review eviction policies - - Monitor key space - -3. Connection problems - - Check security groups/firewall - - Verify credentials - - Review connection limits - -## Additional Resources - -- [Redis Documentation](https://redis.io/documentation) -- [Redis Best Practices](https://redis.io/topics/optimization) -- [Redis Security](https://redis.io/topics/security) diff --git a/tyk-docs/content/tyk-configuration-reference/redis-cluster-sentinel.md b/tyk-docs/content/tyk-configuration-reference/redis-cluster-sentinel.md index ed1e4ea96b..c284b3edc6 100644 --- a/tyk-docs/content/tyk-configuration-reference/redis-cluster-sentinel.md +++ b/tyk-docs/content/tyk-configuration-reference/redis-cluster-sentinel.md @@ -1,454 +1,27 @@ --- -title: "Redis Deployment and Configuration with Tyk" -description: "This page guides on configuring Tyk to work with Redis Cluster and Sentinel, including TLS encryption and troubleshooting tips." +title: "Configure Redis Cluster and Sentinel" +description: "This page provides guidance on configuring Tyk to work with Redis Cluster and Sentinel, including TLS encryption and troubleshooting tips." tags: ["configuration", "redis", "cluster", "sentinel", "tyk-gateway", "tyk-dashboard", "tyk-pump"] aliases: - /tyk-stack/tyk-gateway/configuration/redis-sentinel - /tyk-stack/tyk-gateway/configuration/redis-cluster --- -## Introduction - -Redis is an essential prerequisite for the operation of Tyk products. It serves as the primary data store for various components across the Tyk Stack, handling critical functions such as key management, analytics storage, distributed rate limiting, and inter-node communication. Without Redis, Tyk components cannot function properly, making it a mandatory requirement for any Tyk deployment. - -## Tyk Components Using Redis - -| Component | Redis Usage | -|--------------------------|-----------------------------------------------| -| **Tyk Gateway** | Session Management, Rate Limiting, Cache, Analytics, Cluster Synchronization | -| **Tyk Dashboard** | Session Management, API Configuration, Developer Portal, Cluster Notifications | -| **Tyk Pump** | Analytics Processing, Uptime Data | -| **Tyk Identity Broker** | Profile Storage, Token Caching | -| **MDCB** | Configuration Synchronization, Analytics Aggregation | - -## Supported Redis Versions - -[Tyk components]({{< ref "developer-support/release-notes/overview" >}}) are regularly updated to maintain compatibility with current [Redis versions](https://redis.io/docs/latest/operate/rs/release-notes/). For specific Redis version compatibility information for each Tyk component: - -Refer to the release notes of your specific Tyk component and version, which include documentation links and the compatibility matrix. - -- **[Tyk Gateway]({{< ref "developer-support/release-notes/gateway#3rd-party-dependencies--tools" >}})** -- **[Tyk Dashboard]({{< ref "developer-support/release-notes/dashboard#3rd-party-dependencies--tools" >}})** -- **[Tyk Pump]({{< ref "developer-support/release-notes/pump#3rd-party-dependencies--tools" >}})** -- **[Tyk Identity Broker]({{< ref "developer-support/release-notes/tib/#3rd-party-dependencies--tools" >}})** -- **[MDCB]({{< ref "developer-support/release-notes/mdcb/#3rd-party-dependencies--tools" >}})** - -## Redis Deployment Options - -Tyk supports various Redis deployment configurations to meet different scalability and availability requirements: - -This section provides architectural guidance for Redis deployment in Tyk Data Plane environments within Multi Data Center Bridge (MDCB) configurations. The recommendations are structured around different Service Level Agreements (SLAs), Recovery Time Objectives (RTOs), and Recovery Point Objectives (RPOs), ranging from simple ephemeral deployments to enterprise-grade high availability solutions. - -In Tyk's MDCB architecture, the **Data Plane** consists of Tyk Gateway workers that serve API traffic and require Redis for session management, rate limiting, and caching. The Redis deployment strategy significantly impacts the overall system's availability, performance, and operational complexity. - -This section is written with the MDCB data plane in mind, but the same principles apply to single-data-center Tyk deployments. - -### 1. Standalone Redis (Basic) - -A single Redis instance provides the simplest deployment model suitable for development, testing, or low-criticality environments. - - - -```mermaid -graph TB - subgraph "Data Plane" - LB[Load Balancer] - GW1[Tyk Gateway 1] - GW2[Tyk Gateway 2] - GW3[Tyk Gateway N] - Redis[(Redis Instance)] - - LB --> GW1 - LB --> GW2 - LB --> GW3 - - GW1 --> Redis - GW2 --> Redis - GW3 --> Redis - end - - subgraph "Control Plane" - CP[MDCB Control Plane] - end - - GW1 -.-> CP - GW2 -.-> CP - GW3 -.-> CP -``` - -#### Characteristics - -- **RTO**: 5-15 minutes (manual intervention required) -- **RPO**: 0-5 minutes (depending on persistence configuration) -- **Availability**: ~99.5% -- **Complexity**: Low -- **Cost**: Lowest - -#### Configuration Recommendations - -```yaml -# Redis Configuration - -persistence: optional -backup-schedule: daily -monitoring: basic -``` - -#### Pros - -- Simple to deploy and manage -- Minimal resource requirements -- No coordination overhead -- Suitable for containerized environments - -#### Cons - -- Single point of failure -- Manual recovery required -- Not suitable for production workloads -- Limited scalability - -### 2. Redis Sentinel (High Availability) - -Redis Sentinel provides automated failover capabilities with a master-replica setup, offering a good balance between availability and complexity. - -```mermaid -graph TB - subgraph "Data Plane" - LB[Load Balancer] - GW1[Tyk Gateway 1] - GW2[Tyk Gateway 2] - GW3[Tyk Gateway N] - - subgraph "Redis HA Cluster" - RM[Redis Master] - RR1[Redis Replica 1] - RR2[Redis Replica 2] - S1[Sentinel 1] - S2[Sentinel 2] - S3[Sentinel 3] - end - - LB --> GW1 - LB --> GW2 - LB --> GW3 - - GW1 --> S1 - GW2 --> S2 - GW3 --> S3 - - RM --> RR1 - RM --> RR2 - - S1 -.-> RM - S2 -.-> RM - S3 -.-> RM - end - - subgraph "Control Plane" - CP[MDCB Control Plane] - end - - GW1 -.-> CP - GW2 -.-> CP - GW3 -.-> CP -``` - -#### Characteristics - -- **RTO**: 30-60 seconds (automatic failover) -- **RPO**: <1 minute (asynchronous replication) -- **Availability**: ~99.9% -- **Complexity**: Medium -- **Cost**: Medium - -#### Configuration Recommendations - -```yaml -# Redis Master Configuration -persistence: enabled -replication: async -save: "900 1 300 10 60 10000" - -# Sentinel Configuration -quorum: 2 -down-after-milliseconds: 5000 -failover-timeout: 10000 -parallel-syncs: 1 -``` - -#### Deployment Considerations - -- Deploy 3 or 5 Sentinel instances (odd numbers recommended) -- Configure Tyk Gateways to connect through Sentinel -- Enable Redis persistence for data durability -- Monitor Sentinel logs for failover events - -#### Pros - -- Automatic failover -- High availability without sharding complexity -- Supports 16 logical databases -- Cost-effective for medium-scale deployments - -#### Cons - -- Still limited by single-threaded Redis performance -- Asynchronous replication can lead to data loss -- Requires careful network partition handling - -### 3. Redis Cluster (Horizontal Scaling) - -Redis Cluster offers horizontal scaling capabilities through automatic sharding, making it suitable for high-throughput environments that require linear scalability. - -```mermaid -graph TB - subgraph "Data Plane" - LB[Load Balancer] - GW1[Tyk Gateway 1] - GW2[Tyk Gateway 2] - GW3[Tyk Gateway N] - - subgraph "Redis Cluster" - subgraph "Shard 1" - RC1M[Redis Master 1] - RC1R[Redis Replica 1] - end - subgraph "Shard 2" - RC2M[Redis Master 2] - RC2R[Redis Replica 2] - end - subgraph "Shard 3" - RC3M[Redis Master 3] - RC3R[Redis Replica 3] - end - end - - LB --> GW1 - LB --> GW2 - LB --> GW3 - - GW1 --> RC1M - GW1 --> RC2M - GW1 --> RC3M - - RC1M --> RC1R - RC2M --> RC2R - RC3M --> RC3R - end - - subgraph "Control Plane" - CP[MDCB Control Plane] - end - - GW1 -.-> CP - GW2 -.-> CP - GW3 -.-> CP -``` - -#### Characteristics - -- **RTO**: 10-30 seconds (automatic failover) -- **RPO**: <30 seconds (asynchronous replication) -- **Availability**: ~99.95% -- **Complexity**: High -- **Cost**: High - -#### Configuration Recommendations - -```yaml -# Redis Cluster Configuration -cluster-enabled: yes -cluster-config-file: nodes.conf -cluster-node-timeout: 5000 -cluster-require-full-coverage: yes -cluster-migration-barrier: 1 - -# Minimum 6 nodes (3 masters + 3 replicas) -min-replicas-to-write: 1 -``` - -#### Deployment Considerations - -- Minimum six nodes (3 masters, three replicas) for production -- Only database 0 is available (no multiple logical databases) -- Multi-key operations require keys in the same hash slot -- Use hashtags for related keys: - `{user:123}:session`, `{user:123}:profile` - -#### Pros - -- Linear horizontal scaling up to 1000 nodes -- Automatic sharding and rebalancing -- High throughput capabilities -- Automatic failover and recovery - -#### Cons - -- High operational complexity -- Limited multi-key operations -- No support for multiple databases -- Higher infrastructure costs -- Complex monitoring and troubleshooting - -### 4. Redis Enterprise (Mission-Critical) - -Redis Enterprise provides enterprise-grade features including active-active replication, sub-millisecond latency, and 99.999% availability guarantees. - -```mermaid -graph TB - subgraph "Data Plane - Region A" - LB1[Load Balancer] - GW1[Tyk Gateway 1] - GW2[Tyk Gateway 2] - - subgraph "Redis Enterprise Cluster A" - REA1[Redis Enterprise Node 1] - REA2[Redis Enterprise Node 2] - REA3[Redis Enterprise Node 3] - end - - LB1 --> GW1 - LB1 --> GW2 - GW1 --> REA1 - GW2 --> REA1 - end - - subgraph "Data Plane - Region B" - LB2[Load Balancer] - GW3[Tyk Gateway 3] - GW4[Tyk Gateway 4] - - subgraph "Redis Enterprise Cluster B" - REB1[Redis Enterprise Node 1] - REB2[Redis Enterprise Node 2] - REB3[Redis Enterprise Node 3] - end - - LB2 --> GW3 - LB2 --> GW4 - GW3 --> REB1 - GW4 --> REB1 - end - - REA1 <--> REB1 - REA2 <--> REB2 - REA3 <--> REB3 - - subgraph "Control Plane" - CP[MDCB Control Plane] - end - - GW1 -.-> CP - GW2 -.-> CP - GW3 -.-> CP - GW4 -.-> CP -``` - -#### Characteristics - -- **RTO**: <10 seconds (instant failover) -- **RPO**: <10 seconds (active-active replication) -- **Availability**: 99.999%+ -- **Complexity**: Medium (managed service) -- **Cost**: Highest - -#### Features - -- Active-Active Geo-Distribution -- Automatic scaling and sharding -- Built-in monitoring and alerting -- Multi-model database support -- Enterprise security features - -#### Pros - -- Highest availability and performance -- Global distribution capabilities -- Comprehensive enterprise features -- Managed service reduces operational overhead -- Strong consistency options available - -#### Cons - -- Highest cost -- Vendor lock-in -- May be overkill for smaller deployments - -### Decision Matrix - -The following table summarizes the key characteristics of each Redis deployment option: - -| Architecture | RTO | RPO | Availability | Complexity | Use Case | -|-------------------|-------------|------------|--------------|------------|------------------------------| -| Single Redis | 5–15 min | 0–5 min | 99.5% | Low | Development/Testing | -| Redis with Sentinel | 30–60 sec | <1 min | 99.9% | Medium | Production (Standard) | -| Redis Cluster | 10–30 sec | <30 sec | 99.95% | High | High-throughput Production | -| Redis Enterprise | <10 sec | <10 sec | 99.99%+ | Medium | Mission-critical Enterprise | - -## Configure Redis with TLS - -If you are using TLS for Redis connections, set `use_ssl` to `true` for Gateway and Pump, and `redis_use_ssl` to `true` for the dashboard. -Redis supports [SSL/TLS encryption](https://redis.io/topics/encryption) as of version 6, making it an optional feature that enhances the security of data in transit. Similarly, Amazon ElastiCache offers encryption in transit and at rest. To configure TLS or mTLS connections between an application and Redis, consider the following settings in Tyk's configuration files: - -- `storage.use_ssl`: Set this to true to enable TLS encryption for the connection. - -- `storage.ssl_insecure_skip_verify`: A flag that, when set to true, instructs the application not to verify the Redis server's TLS certificate. This is not recommended for production due to the risk of `man-in-the-middle` attacks. - -From **Tyk 5.3**, additional options are available for more granular control: - -- `storage.ca_file`: Path to the Certificate Authority (CA) file for verifying the Redis server's certificate. - -- `storage.cert_file` and `storage.key_file`: Paths to your application's certificate and private key files, necessary for mTLS where both parties verify each other's identity. - -- `storage.max_version` and `storage.min_version`: Define the acceptable range of TLS versions, enhancing security by restricting connections to secure TLS protocols (1.2 or 1.3). - -**Setting up an Insecure TLS Connection** -- **Enable TLS**: By setting `"use_ssl": true`, you encrypt the connection. -- **Skip Certificate Verification**: Setting `"ssl_insecure_skip_verify": true` bypasses the server's certificate verification, suitable only for non-production environments. - -**Setting up a Secure TLS Connection** -- Ensure `use_ssl` is set to `true`. -- Set `ssl_insecure_skip_verify` to `false` to enforce certificate verification against the CA specified in `ca_file`. -- Specify the path to the CA file in `ca_file` for server certificate verification. -- Adjust `min_version` and `max_version` to secure TLS versions, ideally 1.2 and 1.3. - -**Setting up a Mutual TLS (mTLS) Connection** -- Follow the steps for a secure TLS connection. -- Provide paths for `cert_file` and `key_file` for your application's TLS certificate and private key, enabling the Redis server to verify your application's identity. - -**Example Gateway Configuration** -```json -"storage": { - "type": "redis", - "addrs": [ - "server1:6379", - "server2:6380", - "server3:6381" - ], - "use_ssl": true, - "ssl_insecure_skip_verify": false, - "ca_file": "/path/to/ca.crt", - "cert_file": "/path/to/client.crt", - "key_file": "/path/to/client.key", - "max_version": "1.3", - "min_version": "1.2", - "enable_cluster": true, - "optimisation_max_idle": 2000, - "optimisation_max_active": 4000 -} -``` - ## Configure Redis Cluster -Our Gateway, Dashboard, and Pump all support integration with Redis Cluster. Redis Cluster allows data to be automatically sharded across multiple Redis Nodes. To set up Redis Cluster correctly, we recommend reading the [Redis Cluster Tutorial](https://redis.io/topics/cluster-tutorial). You must use the same settings across the Gateway, Dashboard, and Pump. +Our Gateway, Dashboard and Pump all support integration with Redis Cluster. Redis Cluster allows data to be automatically sharded across multiple Redis Nodes. To setup Redis Cluster correctly, we recommend you read the [Redis Cluster Tutorial](https://redis.io/topics/cluster-tutorial). You must use the same settings across the Gateway, Dashboard and Pump. {{< note success >}} **Note** -A Redis Cluster operates differently from a standard Redis setup, where one instance serves as the primary and others as replicas. +Redis Cluster operates differently from a Redis setup where one instance serves as the primary and others as replicas. {{< /note >}} +### Supported Versions +- Tyk 5.3 supports Redis 6.2.x, 7.0.x, and 7.2.x +- Tyk 5.2.x and earlier supports Redis 6.0.x and Redis 6.2.x only. + + ### Redis Cluster and Tyk Gateway To configure the Tyk Gateway to work with your Redis Cluster, set `enable_cluster` to `true` and list your servers under `addrs` in your `tyk.conf` file. @@ -456,7 +29,7 @@ To configure the Tyk Gateway to work with your Redis Cluster, set `enable_cluste {{< note success >}} **Note** -`addrs` is new in v2.9.3, and replaces `hosts`, which is now deprecated. +`addrs` is new in v2.9.3, and replaces `hosts` which is now deprecated. {{< /note >}} If you are using TLS for Redis connections, set `use_ssl` to `true`. @@ -484,7 +57,7 @@ If you are using TLS for Redis connections, set `use_ssl` to `true`. {{< note success >}} **Note** -`redis_addrs` is new in v1.9.3 for the Dashboard, and replaces `hosts`, which is now deprecated. +`redis_addrs` is new in v1.9.3 for the Dashboard, and replaces `hosts` which is now deprecated. {{< /note >}} @@ -507,7 +80,7 @@ To configure the Tyk Pump to work with your Redis Cluster, set `enable_cluster` {{< note success >}} **Note** -`addrs` is new in v2.9.3, and replaces `hosts`, which is now deprecated. +`addrs` is new in v2.9.3, and replaces `hosts` which is now deprecated. {{< /note >}} @@ -540,8 +113,8 @@ Set the environment variable `TYK_GW_STORAGE_ENABLECLUSTER` to `true`. Add all the Redis Cluster endpoints into Tyk, not just the primary. If Tyk can't see the whole cluster, then it will not work. -For ElastiCache Redis, you can bypass having to list all your nodes, and instead use the *configuration endpoint*, -This allows read and write operations, and the endpoint determines the correct node to target. +For ElastiCache Redis, you can bypass having to list all your nodes, and instead just use the *configuration endpoint*, +this allows read and write operations and the endpoint will determine the correct node to target. If this does not work, you can still list out the hosts using an environment variable. To do so, set the environment variable: @@ -549,7 +122,7 @@ If this does not work, you can still list out the hosts using an environment var TYK_GW_STORAGE_ADDRS="redis_primary1:port,redis_replica1:port,redis_primary2:port,redis_replica2:port,redis_primary3:port,redis_replica3:port" ``` -It is essential that Tyk can connect to all primary and replica instances. +It is important that Tyk can connect to all primary and replica instances. It is recommended to ensure that the connection pool is big enough. To do so, set the following environment variables: @@ -560,16 +133,83 @@ TYK_GW_STORAGE_MAXACTIVE=10000 {{< note success >}} **Note** -These are suggested settings; please verify them by load testing. +These are suggested settings, please verify them by load testing. {{< /note >}} +#### Redis Cluster with TLS + +If you are using TLS for Redis connections, set `use_ssl` to `true` for Gateway and Pump, and `redis_use_ssl` to `true` for the dashboard. +Redis supports [SSL/TLS encryption](https://redis.io/topics/encryption) from version 6 as an optional feature, enhancing the security of data in transit. Similarly, Amazon ElastiCache offers encryption in transit and at rest. To configure TLS or mTLS connections between an application and Redis, consider the following settings in Tyk's configuration files: + +- `storage.use_ssl`: Set this to true to enable TLS encryption for the connection. + +- `storage.ssl_insecure_skip_verify`: A flag that, when set to true, instructs the application not to verify the Redis server's TLS certificate. This is not recommended for production due to the risk of `man-in-the-middle` attacks. + +From **Tyk 5.3**, additional options are available for more granular control: + +- `storage.ca_file`: Path to the Certificate Authority (CA) file for verifying the Redis server's certificate. + +- `storage.cert_file` and `storage.key_file`: Paths to your application's certificate and private key files, necessary for mTLS where both parties verify each other's identity. + +- `storage.max_version` and `storage.min_version`: Define the acceptable range of TLS versions, enhancing security by restricting connections to secure TLS protocols (1.2 or 1.3). + +**Setting up an Insecure TLS Connection** +- **Enable TLS**: By setting `"use_ssl": true`, you encrypt the connection. +- **Skip Certificate Verification**: Setting `"ssl_insecure_skip_verify": true` bypasses the server's certificate verification, suitable only for non-production environments. + +**Setting up a Secure TLS Connection** +- Ensure `use_ssl` is set to `true`. +- Set `ssl_insecure_skip_verify` to `false` to enforce certificate verification against the CA specified in `ca_file`. +- Specify the path to the CA file in `ca_file` for server certificate verification. +- Adjust `min_version` and `max_version` to secure TLS versions, ideally 1.2 and 1.3. + +**Setting up a Mutual TLS (mTLS) Connection** +- Follow the steps for a secure TLS connection. +- Provide paths for `cert_file` and `key_file` for your application's TLS certificate and private key, enabling Redis server to verify your application's identity. + +**Example Gateway Configuration** +```json +"storage": { + "type": "redis", + "addrs": [ + "server1:6379", + "server2:6380", + "server3:6381" + ], + "use_ssl": true, + "ssl_insecure_skip_verify": false, + "ca_file": "/path/to/ca.crt", + "cert_file": "/path/to/client.crt", + "key_file": "/path/to/client.key", + "max_version": "1.3", + "min_version": "1.2", + "enable_cluster": true, + "optimisation_max_idle": 2000, + "optimisation_max_active": 4000 +} +``` + +#### Troubleshooting Redis Cluster + +If you find that Tyk components fail to initialise when using Redis clustering, for example the application does not start and the last log file entry shows a message such as `Using clustered mode`, try setting the environment variable `REDIGOCLUSTER_SHARDCOUNT` to `128` on all hosts which connect to the Redis Cluster i.e. Gateway, Dashboard, Pump, MDCB. E.g. + +`REDIGOCLUSTER_SHARDCOUNT=128` + +If setting to `128` does not resolve the issue, try `256` instead. + + ## Configure Redis Sentinel -From v2.9.3, Redis Sentinel is supported. +From v2.9.3 Redis Sentinel is supported. + +Similar to Redis Cluster, our Gateway, Dashboard and Pump all support integration with Redis Sentinel. + +To configure Tyk to work with Redis Sentinel, list your servers under `addrs` and set the master name in your Gateway, Dashboard, Pump and MDCB config. Unlike Redis Cluster, `enable_cluster` should **not** be set. Indicative config snippets as follows: -Similar to Redis Cluster, our Gateway, Dashboard, and Pump all support integration with Redis Sentinel. +### Supported Versions +- Tyk 5.3 supports Redis 6.2.x, 7.0.x, and 7.2.x +- Tyk 5.2.x and earlier supports Redis 6.0.x and Redis 6.2.x only. -To configure Tyk to work with Redis Sentinel, list your servers under `addrs` and set the master name in your Gateway, Dashboard, Pump, and MDCB config. Unlike Redis Cluster, `enable_cluster` should **not** be set. Indicative config snippets as follows: ### Redis Sentinel and Gateway @@ -624,13 +264,13 @@ To configure Tyk to work with Redis Sentinel, list your servers under `addrs` an {{< warning success >}} **Warning** -When using Bitnami charts to install Redis Sentinel in Kubernetes (k8s), a Redis service is exposed, which means that the standard Redis configuration is required instead of the above setup. In other words, a single server in `addrs` and `master_name` is not necessary. +When using Bitnami charts to install Redis Sentinel in k8s, a Redis service is exposed, which means that standard Redis config is required instead of the above setup, i.e. a single server in `addrs` and `master_name` is not required. {{< /warning >}} ### Support for Redis Sentinel AUTH -To support the use of Redis Sentinel AUTH (introduced in Redis 5.0.1), we have added the following global config settings in Tyk v3.0.2: +To support the use of Redis Sentinel AUTH (introduced in Redis 5.0.1) we have added the following global config settings in Tyk v3.0.2: * In the Tyk Gateway config file - `sentinel_password` * In the Tyk Dashboard config file - `redis_sentinel_password` @@ -642,15 +282,52 @@ These settings allow you to support Sentinel password-only authentication in Red See the Redis and Sentinel authentication section of the [Redis Sentinel docs](https://redis.io/topics/sentinel) for more details. -## FAQ +### Configure Redis TLS Encryption +Redis supports [SSL/TLS encryption](https://redis.io/topics/encryption) from version 6 as an optional feature, enhancing the security of data in transit. To configure TLS or mTLS connections between an application and Redis, consider the following settings in Tyk's configuration files: -
What is Tyk Streams and what problem does it solve? +- `storage.use_ssl`: Set this to true to enable TLS encryption for the connection. -If you find that Tyk components fail to initialise when using Redis clustering, for example, the application does not start. The last log file entry shows a message such as `Using clustered mode`. Try setting the environment variable `REDIGOCLUSTER_SHARDCOUNT` to `128` on all hosts that connect to the Redis Cluster, i.e., Gateway, Dashboard, Pump, and MDCB. E.g. +- `storage.ssl_insecure_skip_verify`: A flag that, when set to true, instructs the application not to verify the Redis server's TLS certificate. This is not recommended for production due to the risk of `man-in-the-middle` attacks. -`REDIGOCLUSTER_SHARDCOUNT=128` +From **Tyk 5.3**, additional options are available for more granular control: -If setting to `128` does not resolve the issue, try `256` instead. +- `storage.ca_file`: Path to the Certificate Authority (CA) file for verifying the Redis server's certificate. -
  +- `storage.cert_file` and `storage.key_file`: Paths to your application's certificate and private key files, necessary for mTLS where both parties verify each other's identity. +- `storage.max_version` and `storage.min_version`: Define the acceptable range of TLS versions, enhancing security by restricting connections to secure TLS protocols (1.2 or 1.3). + +**Setting up an Insecure TLS Connection** +- **Enable TLS**: By setting `"use_ssl": true`, you encrypt the connection. +- **Skip Certificate Verification**: Setting `"ssl_insecure_skip_verify": true` bypasses the server's certificate verification, suitable only for non-production environments. + +**Setting up a Secure TLS Connection** +- Ensure `use_ssl` is set to `true`. +- Set `ssl_insecure_skip_verify` to `false` to enforce certificate verification against the CA specified in `ca_file`. +- Specify the path to the CA file in `ca_file` for server certificate verification. +- Adjust `min_version` and `max_version` to secure TLS versions, ideally 1.2 and 1.3. + +**Setting up a Mutual TLS (mTLS) Connection** +- Follow the steps for a secure TLS connection. +- Provide paths for `cert_file` and `key_file` for your application's TLS certificate and private key, enabling Redis server to verify your application's identity. + +**Example Gateway Configuration** +```json +"storage": { + "type": "redis", + "addrs": [ + "server1:6379", + "server2:6380", + "server3:6381" + ], + "use_ssl": true, + "ssl_insecure_skip_verify": false, + "ca_file": "/path/to/ca.crt", + "cert_file": "/path/to/client.crt", + "key_file": "/path/to/client.key", + "max_version": "1.3", + "min_version": "1.2", + "optimisation_max_idle": 2000, + "optimisation_max_active": 4000 +} +``` \ No newline at end of file diff --git a/tyk-docs/data/menu.yaml b/tyk-docs/data/menu.yaml index ba16a18b56..e1c848cfb4 100644 --- a/tyk-docs/data/menu.yaml +++ b/tyk-docs/data/menu.yaml @@ -183,13 +183,8 @@ menu: show: True - title: "Database Management" path: /planning-for-production/database-settings - category: Directory + category: Page show: True - menu: - - title: "Redis" - path: /tyk-configuration-reference/redis-cluster-sentinel - category: Page - show: True - title: "Circuit Breakers" path: /planning-for-production/ensure-high-availability/circuit-breakers category: Page @@ -222,6 +217,10 @@ menu: path: /planning-for-production/monitoring/tyk-components category: Page show: True + - title: "Redis" + path: /tyk-configuration-reference/redis-cluster-sentinel + category: Page + show: True - title: "Graceful Shutdown" path: /planning-for-production/ensure-high-availability/graceful-shutdown category: Page