[TT-15401] added external services configuration info

[andrei-tyk]

User description

Contributor checklist

• Reviewed PR Code suggestions and updated accordingly
• Tyklings: Labled the PR with the relevant releases
• Tyklings: Added Jira DX PR ticket to the subject

---

New Contributors

• Start the PR branch from our latest master
• I have read the repository contribution guidelines
• I have read the repository technical guidelines

---

---

PR Type

Documentation, Enhancement

---

Description

• Add external services config docs

• Document global and per-service proxy

• Describe mTLS settings and env vars

• Provide examples and best practices

---

Diagram Walkthrough

flowchart LR
  A["Gateway config reference"] -- "adds section" --> B["external_services overview"]
  B -- "details" --> C["Global proxy settings"]
  B -- "details" --> D["Service-specific overrides"]
  D -- "covers" --> D1["oauth"]
  D -- "covers" --> D2["storage"]
  D -- "covers" --> D3["webhooks"]
  D -- "covers" --> D4["health"]
  D -- "covers" --> D5["discovery"]
  B -- "security" --> E["mTLS parameters"]
  B -- "ops" --> F["Env vars, migration, troubleshooting"]
  B -- "guidance" --> G["Examples & best practices"]

Loading

File Walkthrough

Relevant files

Documentation

gateway-config.md Add external_services config reference in shared gateway config tyk-docs/content/shared/gateway-config.md Add external_services configuration section. Document global proxy and env precedence. Add OAuth mTLS parameters and TLS versions. Note per-service blocks: storage, webhooks, health, discovery. +141/-0  external-services-configuration.md New guide: External Services Configuration (proxy and mTLS) tyk-docs/content/tyk-configuration-reference/external-services-configuration.md New comprehensive page for External Services. Includes structure, examples, security, performance. Details env vars, migration, troubleshooting. Documents per-service proxy and mTLS options. +460/-0

---

[github-actions]

⚠️ Deploy preview for PR #6900 did not become live after 3 attempts.
Please check Netlify or try manually: Preview URL

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 Security concerns Sensitive information handling: Examples include embedding proxy credentials in URLs. While you later recommend env vars, consider adding explicit cautions to avoid plain-text secrets in config files and logs, and note that proxy URLs with credentials may appear in process lists or error logs. Also, advise file permission best practices around certs/keys consistently across both files.

⚡ Recommended focus areas for review Accuracy The precedence order lists environment variables below config, while earlier text says env vars take precedence when enabled. Clarify and keep the precedence consistent across docs. API Consumer -> Gateway network read timeout. Not setting this config, or setting this to 0, defaults to 120 seconds ### http_server_options.write_timeout ENV: <b>TYK_GW_HTTPSERVEROPTIONS_WRITETIMEOUT</b><br /> Type: `int`<br /> API Consumer -> Gateway network write timeout. Not setting this config, or setting this to 0, defaults to 120 seconds Support Claims The doc claims hot-reload, connection pooling, and per-service timeouts; verify these are actually implemented and exposed to users, or mark as informational/roadmap to avoid misleading users. ### Key Features - **Zero Downtime Configuration**: Hot-reload support for configuration changes - **Backward Compatibility**: Existing configurations continue to work unchanged - **Enterprise Security**: Production-ready mTLS and proxy authentication - **Performance Optimized**: Service-specific connection pooling and timeouts - **Comprehensive Logging**: Detailed debug information for troubleshooting Scope Clarity Storage section suggests Redis/database proxy/mTLS via external services; confirm applicability to Tyk’s actual storage backends and avoid implying DB support if not present. ### external_services.storage Storage service-specific configuration for external storage operations including Redis connections and database interactions. ### external_services.storage.proxy Service-specific proxy configuration for storage requests. Supports the same proxy configuration options as other services. ### external_services.storage.mtls Mutual TLS configuration for storage service communications. Supports the same mTLS configuration options as other services.

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Fix precedence order inconsistency The order implies env vars are lower priority than file config, which contradicts earlier "environment variables take precedence" statements. Align the precedence to avoid misconfigurations and outages. Place environment variables ahead when use_environment is enabled. tyk-docs/content/tyk-configuration-reference/external-services-configuration.md [123-131] ### Configuration Hierarchy and Precedence Settings are applied in the following priority order (highest to lowest): -1. **Service-specific configuration** - Overrides all other settings -2. **Global external_services configuration** - Applies to all services -3. **Environment variables** - Used when `use_environment: true` +1. **Service-specific configuration** - Highest priority for that service +2. **Environment variables (when `use_environment: true`)** - Override file-based settings for the relevant scope (global or service-specific) +3. **Global `external_services` configuration** - Applies to all services 4. **Default settings** - Built-in fallback values Suggestion importance[1-10]: 8 __ Why: This addresses a real inconsistency between earlier statements (env vars take precedence) and the precedence list, reducing the chance of misconfiguration. The proposed order is precise and context-aware of use_environment, making it a high-impact correctness fix for the docs.	Medium
	Clarify mTLS requirement semantics Clarify whether cert_file and key_file are required simultaneously with insecure_skip_verify: true. Without this, users may misconfigure mTLS and break connectivity. Add an explicit note about the precedence and requirement matrix. tyk-docs/content/shared/gateway-config.md [1049-1055] ### external_services.oauth.mtls.enabled ENV: <b>TYK_GW_EXTERNAL_SERVICES_OAUTH_MTLS_ENABLED</b><br /> Type: `bool`<br /> -Enable or disable mTLS for OAuth service requests. When enabled, `cert_file` and `key_file` are required. +Enable or disable mTLS for OAuth service requests. When `enabled: true`, `cert_file` and `key_file` are required to present a client certificate. Note: `insecure_skip_verify` only affects server certificate verification and does not remove the requirement for `cert_file`/`key_file` when mTLS is enabled. Suggestion importance[1-10]: 6 __ Why: The clarification correctly aligns with the existing text and adds useful nuance about insecure_skip_verify not affecting client cert requirements when mTLS is enabled. It's accurate and reduces misconfiguration risk, though it's a documentation clarity improvement rather than a critical fix.	Low
General	Clarify pooling values’ status These numeric limits appear normative; if not enforced by the product, readers may assume they are configurable or defaults. Add a note clarifying whether these are defaults, examples, or recommendations and how to change them if applicable to prevent mis-tuning based on incorrect assumptions. tyk-docs/content/tyk-configuration-reference/external-services-configuration.md [312-322] ### Performance Optimization ### Connection Pooling The feature implements optimized connection pooling for each service type: | Service Type | Max Connections | Per Host | Idle Timeout | Reasoning | |--------------|-----------------|----------|--------------|-----------| | OAuth | 50 | 10 | 30s | Frequent auth requests, connection reuse | | Health | 20 | 5 | 15s | Quick, frequent health checks | | Storage | 50 | 15 | 90s | Longer-lived connections, bulk operations | | Discovery | 30 | 5 | 20s | Service registry lookups | | Webhooks | 50 | 10 | 30s | Reliable delivery, connection reuse | +Note: The above values are recommendations (not hard-coded defaults) unless explicitly configured in your deployment. If your build exposes tuning options, adjust them per service to match workload characteristics. + Suggestion importance[1-10]: 5 __ Why: The note helps prevent readers from assuming the values are defaults if they are only recommendations, improving clarity. Impact is moderate since it depends on product behavior, but it meaningfully reduces potential tuning mistakes.	Low

[github-actions]

Code Review: External Services Configuration Documentation

The PR adds comprehensive documentation for the External Services Configuration feature in Tyk Gateway. This is a well-structured and detailed guide that explains how to configure external service interactions with Tyk Gateway.

Strengths

1. Comprehensive Coverage: The documentation thoroughly covers all aspects of the feature, including:

   • Overview and key features
   • Supported external services
   • Configuration structure and parameters
   • Configuration hierarchy and precedence
   • Multiple configuration examples for different scenarios
   • Security best practices
   • Performance optimization
   • Migration from legacy configuration
   • Troubleshooting

2. Well-Structured Format: The documentation follows a logical flow, starting with an overview and gradually diving into more specific details and advanced use cases.

3. Clear Examples: Multiple JSON configuration examples are provided for different scenarios, making it easy for users to understand how to implement the feature.

4. Tables for Parameter Reference: The use of tables for parameter references makes the documentation easy to scan and reference.

5. Migration Guidance: Clear instructions are provided for migrating from legacy configurations, including a before/after example.

6. Troubleshooting Section: The inclusion of common issues and their solutions will be valuable for users.

Minor Suggestions

While the documentation is of high quality, here are a few minor suggestions for consideration:

1. Diagrams: Consider adding a visual diagram showing how the external services configuration fits into the overall Tyk architecture, which could help users better understand the feature's context.

2. Cross-References: Ensure all internal links to other documentation sections (using the {{< ref >}} shortcode) are correctly pointing to existing pages.

3. Version Information: Consider adding information about which Tyk Gateway version introduced this feature.

Conclusion

This PR adds valuable and well-written documentation for the External Services Configuration feature. The documentation is comprehensive, clear, and follows best practices for technical documentation. It will be a useful resource for Tyk users who need to configure external service interactions.

The PR is ready to be merged.

---

Tip: Mention me again using /probe <request>.
Powered by Probe AI

[netlify]

✅ PS. Add to the end of url /docs/nightly

Name	Link
🔨 Latest commit	fc05e86
🔍 Latest deploy log	https://app.netlify.com/projects/tyk-docs/deploys/68b94d7c664fc5000869d98e
😎 Deploy Preview	https://deploy-preview-6900--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[netlify]

✅ PS. Add to the end of url /docs/nightly

Name	Link
🔨 Latest commit	8ab6057
🔍 Latest deploy log	https://app.netlify.com/projects/tyk-docs/deploys/68d51c6b718adb00082f8653
😎 Deploy Preview	https://deploy-preview-6900--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[andyo-tyk]

Some observations

[sharadregoti]

TODO:

1. Add links to the configuration document for each field mentioned in the table.
2. The CI is failing because reference configurations are not available.