docs: Add documentation for configuring service discovery with uptime tests

[buger]

User description

Summary

• Adds new documentation page explaining how to configure uptime tests to dynamically discover endpoints using service discovery
• Addresses the documentation gap identified in DX-2022
• Incorporates findings from TT-14943 regarding the correct JSON structure for query endpoints

What's Included

The new documentation page (uptime-tests-service-discovery.mdx) covers:

• Introduction: Use cases and how the feature works
• Prerequisites: Required setup before configuring
• Query Endpoint JSON Structure: Examples for simple, nested, and target list formats
• API Definition Configuration: Complete reference table with all options
• Service Discovery Examples:
  • Consul (with health endpoint)
  • etcd (simple and nested JSON)
  • Eureka (with JSON response)
• Dashboard Configuration: Step-by-step UI instructions
• Combining Static and Dynamic Tests: How to mix manual and discovered endpoints
• Integration with Load Balancing: Using check_host_against_uptime_tests
• Troubleshooting Guide: Common issues and solutions

Navigation Changes

Added the new page to docs.json under:

• API Management → Deploy Tyk → Tyk Self Managed → Configuration

The page appears after "Uptime Tests" for logical navigation flow.

Test Plan

• Verify the new page renders correctly in the documentation site
• Check all internal links work correctly
• Confirm JSON examples are syntactically valid
• Review navigation placement in the sidebar

Related Issues

• Resolves: DX-2022 (Documentation on Configuring Service Discovery for Uptime Tests)
• Related: TT-14943 (Identify correct JSON returned by the Query Endpoint)

🤖 Generated with Claude Code

---

PR Type

Documentation

---

Description

• Add new uptime tests discovery guide

• Insert page into docs navigation

• Provide JSON structures and configs

• Include dashboard steps and troubleshooting

---

Diagram Walkthrough

flowchart LR
  Nav["Update docs.json navigation"] -- "add page link" --> Page["New guide: uptime-tests-service-discovery.mdx"]
  Page -- "covers" --> JSON["JSON structures & examples"]
  Page -- "includes" --> Config["API definition options"]
  Page -- "guides" --> UI["Dashboard setup steps"]
  Page -- "adds" --> Help["Troubleshooting & tips"]

Loading

File Walkthrough

Relevant files

Documentation

docs.json Add service discovery doc to navigation                                    docs.json Add new page path under Configuration. Place after uptime-tests in sidebar. +1/-0      uptime-tests-service-discovery.mdx New guide: uptime tests with service discovery                      planning-for-production/ensure-high-availability/uptime-tests-service-discovery.mdx New comprehensive guide for uptime tests discovery. Provide JSON path patterns and examples. Detail API/Dashboard configurations and load balancing. Add troubleshooting and related links. +458/-0

---

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

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

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Possible Inaccuracy The config table marks data_path as required; however, some discovery responses may rely on parent_data_path with use_nested_query and/or use_target_list where paths may differ. Verify required/optional flags align with actual Gateway behavior and whether data_path is always mandatory. ### Configuration Options | Option | Type | Required | Description | | :--- | :--- | :--- | :--- | | `use_discovery_service` | boolean | Yes | Set to `true` to enable service discovery for uptime tests | | `query_endpoint` | string | Yes | The URL of your service discovery endpoint (Consul, etcd, Eureka, etc.) | | `data_path` | string | Yes | The JSON path to the hostname/address field in the response | | `parent_data_path` | string | No | Used with `use_nested_query` to specify the path to a JSON-encoded string containing the actual data | | `port_data_path` | string | No | The JSON path to the port field if separate from hostname | | `use_nested_query` | boolean | No | Set to `true` if the endpoint data is within a JSON-encoded string | | `use_target_list` | boolean | No | Set to `true` if the response contains multiple endpoints | | `cache_timeout` | integer | No | How long (in seconds) to cache the discovered endpoints. Default: 60 | | `target_path` | string | No | A path to append to discovered endpoints (e.g., `/health` for health check endpoints) | JSON Path Semantics Examples use dotted paths like Service.Address, services.address, and port.$. Confirm these match the exact JSONPath syntax supported by Tyk for uptime test discovery (e.g., arrays handling, nested fields). Mismatch could confuse users. ## Service Discovery Examples ### Consul Example Consul's health endpoint returns healthy service instances. Configure Tyk to query Consul and extract service addresses: **Query Endpoint:** http://consul:8500/v1/health/service/my-api?passing=true **Sample Response:** ```json [ { "Node": { "ID": "node-1", "Node": "consul-node-1", "Address": "10.0.0.1" }, "Service": { "ID": "my-api-1", "Service": "my-api", "Address": "10.0.0.1", "Port": 8080 } }, { "Node": { "ID": "node-2", "Node": "consul-node-2", "Address": "10.0.0.2" }, "Service": { "ID": "my-api-2", "Service": "my-api", "Address": "10.0.0.2", "Port": 8080 } } ] Configuration: { "uptime_tests": { "service_discovery": { "use_discovery_service": true, "query_endpoint": "http://consul:8500/v1/health/service/my-api?passing=true", "data_path": "Service.Address", "port_data_path": "Service.Port", "use_target_list": true, "cache_timeout": 30, "target_path": "/health" } } } </details> <details><summary><a href='https://github.com/TykTechnologies/tyk-docs/pull/1154/files#diff-b7b4169fa5b2e02aa17d40553a73c5d9520086753c501eeb926c63b162bb6d9eR133-R150'><strong>Nav Placement</strong></a> New page is inserted after "uptime-tests". Confirm sidebar ordering and grouping match docs conventions and that the slug matches the file path to avoid broken links. </summary> ```json "deployment-and-operations/tyk-self-managed/tyk-demos-and-pocs/overview", "tyk-self-managed/install", { "group": "Configuration", "pages": [ "planning-for-production", "planning-for-production/database-settings", "planning-for-production/ensure-high-availability/circuit-breakers", "planning-for-production/ensure-high-availability/enforced-timeouts", "planning-for-production/ensure-high-availability/health-check", "planning-for-production/ensure-high-availability/load-balancing", "planning-for-production/ensure-high-availability/service-discovery", "planning-for-production/ensure-high-availability/uptime-tests", "planning-for-production/ensure-high-availability/uptime-tests-service-discovery", "configure/external-service", "tyk-configuration-reference/kv-store", "planning-for-production/monitoring/tyk-components", "tyk-configuration-reference/redis-cluster-sentinel",

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Use supported admonitions Replace the custom tag with the site's supported admonition syntax to avoid rendering errors. If MDX doesn't register a Note component, use fenced admonitions or a standard blockquote. planning-for-production/ensure-high-availability/uptime-tests-service-discovery.mdx [298-300] -<Note> -Eureka returns XML by default. To receive JSON, either configure your Eureka endpoint or use Tyk to add an `Accept: application/json` header via an API definition that proxies to Eureka. -</Note> +> Note: +> Eureka returns XML by default. To receive JSON, either configure your Eureka endpoint or use Tyk to add an `Accept: application/json` header via an API definition that proxies to Eureka. Suggestion importance[1-10]: 6 __ Why: Replacing a custom Note tag with a standard admonition or blockquote can prevent rendering errors if Note isn’t registered. It’s a safe, readability-focused improvement but not critical.	Low
	Ensure table renders reliably If the docs site uses CommonMark without a table plugin, this pipe table might not render. Convert to a simple list to ensure compatibility and prevent broken formatting in static site builds. planning-for-production/ensure-high-availability/uptime-tests-service-discovery.mdx [141-154] ### Configuration Options -| Option | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| `use_discovery_service` | boolean | Yes | Set to `true` to enable service discovery for uptime tests | -| `query_endpoint` | string | Yes | The URL of your service discovery endpoint (Consul, etcd, Eureka, etc.) | -| `data_path` | string | Yes | The JSON path to the hostname/address field in the response | -| `parent_data_path` | string | No | Used with `use_nested_query` to specify the path to a JSON-encoded string containing the actual data | -| `port_data_path` | string | No | The JSON path to the port field if separate from hostname | -| `use_nested_query` | boolean | No | Set to `true` if the endpoint data is within a JSON-encoded string | -| `use_target_list` | boolean | No | Set to `true` if the response contains multiple endpoints | -| `cache_timeout` | integer | No | How long (in seconds) to cache the discovered endpoints. Default: 60 | -| `target_path` | string | No | A path to append to discovered endpoints (e.g., `/health` for health check endpoints) | +- `use_discovery_service` (boolean, required): Set to `true` to enable service discovery for uptime tests. +- `query_endpoint` (string, required): The URL of your service discovery endpoint (Consul, etcd, Eureka, etc.). +- `data_path` (string, required): The JSON path to the hostname/address field in the response. +- `parent_data_path` (string, optional): Used with `use_nested_query` to specify the path to a JSON-encoded string containing the actual data. +- `port_data_path` (string, optional): The JSON path to the port field if separate from hostname. +- `use_nested_query` (boolean, optional): Set to `true` if the endpoint data is within a JSON-encoded string. +- `use_target_list` (boolean, optional): Set to `true` if the response contains multiple endpoints. +- `cache_timeout` (integer, optional): How long (in seconds) to cache the discovered endpoints. Default: 60. +- `target_path` (string, optional): A path to append to discovered endpoints (e.g., `/health` for health check endpoints). Suggestion importance[1-10]: 5 __ Why: Converting pipe table to a list can improve compatibility if the site lacks table support. Impact is moderate and context-dependent; the current table may already render fine.	Low
Possible issue	Prevent broken sidebar link Ensure the new sidebar entry uptime-tests-service-discovery matches the actual file path and slug. If the sidebar expects file paths without extension, verify routing builds correctly; otherwise include .mdx to prevent broken links. docs.json [146-148] "planning-for-production/ensure-high-availability/uptime-tests", -"planning-for-production/ensure-high-availability/uptime-tests-service-discovery", +"planning-for-production/ensure-high-availability/uptime-tests-service-discovery.mdx", "configure/external-service", Suggestion importance[1-10]: 4 __ Why: The suggestion is reasonable but speculative; many doc sites resolve slugs without extensions. It could prevent a broken link if the build requires .mdx, but correctness depends on site config.	Low