This PR enhances the graceful shutdown sequence of the Tyk Gateway by introducing a configurable waiting period. This allows orchestration platforms like Kubernetes to detect that the gateway is shutting down via its readiness probe, remove it from the load balancer's pool, and stop routing new traffic to it before the gateway process terminates. This helps prevent dropped requests during rolling updates and enables zero-downtime deployments.

The key change is the introduction of a new configuration parameter, graceful_shutdown_delay_seconds. When a shutdown signal is received, the gateway immediately marks itself as shutting down, causing the readiness endpoint to return a 503 Service Unavailable status. It then waits for the configured delay before proceeding with the existing shutdown logic, providing a window for traffic managers to react.

Files Changed Analysis

The changes are concise and targeted across 5 files:

• config/config.go: Adds the GracefulShutdownDelaySeconds field to the main configuration struct.
• cli/linter/schema.json: Updates the configuration schema to include the new graceful_shutdown_delay_seconds property for validation.
• gateway/server.go: Introduces a shuttingDown atomic boolean to the Gateway struct. The shutdown signal handler is updated to set this flag and then wait for the configured delay before proceeding.
• gateway/health_check.go: Modifies the readinessHandler to check the shuttingDown flag and return an HTTP 503 Service Unavailable if it is set.
• gateway/health_check_test.go: Adds a unit test to verify that the readiness probe correctly returns a 503 status when the gateway is in the shutdown state.

Architecture & Impact Assessment

• What this PR accomplishes: It improves the gateway's operational behavior in orchestrated environments, making rolling updates more reliable by preventing traffic from being sent to terminating instances.

• Key technical changes introduced:

  1. Configurable Shutdown Delay: A new graceful_shutdown_delay_seconds parameter allows operators to define a waiting period.
  2. Immediate State Flagging: Upon receiving a termination signal, an atomic boolean shuttingDown is immediately set to true.
  3. Proactive Readiness Failure: The readiness probe begins failing with a 503 error as soon as the shuttingDown state is active.
  4. Delayed Shutdown: The actual server shutdown process is postponed by the configured delay, creating a window for traffic redirection.

• Affected system components:

  • Gateway Configuration
  • Gateway Server Lifecycle & Signal Handling
  • Health & Readiness Check Endpoints

• Shutdown Sequence Visualization:

sequenceDiagram
participant Orchestrator as "Orchestrator (e.g., K8s)"
participant LoadBalancer as "Load Balancer"
participant Gateway

Note over Gateway: Normal Operation
Orchestrator->>Gateway: GET /hello (Readiness Probe)
Gateway-->>Orchestrator: 200 OK

Note over Gateway: Shutdown Initiated
Orchestrator->>Gateway: Sends SIGTERM
Gateway->>Gateway: Sets shuttingDown = true

Note over Gateway: Readiness probe now fails
Orchestrator->>Gateway: GET /hello (Readiness Probe)
Gateway-->>Orchestrator: 503 Service Unavailable
Orchestrator->>LoadBalancer: Deregister Gateway instance
Note right of LoadBalancer: Stops sending new traffic

Gateway->>Gateway: Waits for `graceful_shutdown_delay_seconds`
Gateway->>Gateway: Proceeds with existing graceful shutdown

## Scope Discovery & Context Expansion
The impact of this change is primarily operational, enhancing the gateway's behavior as a component within modern cloud-native environments. The change is self-contained and does not affect other Tyk services.

- **Orchestration (Kubernetes/Nomad)**: A failing readiness probe is the standard mechanism to signal that a pod should be removed from a service's load balancing pool. This change makes the gateway a better citizen in such systems.
- **Load Balancers (AWS ALB, NGINX)**: External load balancers that use the readiness endpoint for health checks will correctly identify the node as unhealthy and remove it from the active backend pool before connections are forcefully terminated.


<details>
  <summary>Metadata</summary>

  - Review Effort: 2 / 5
  - Primary Label: enhancement


</details>
<!-- visor:section-end id="overview" -->

<!-- visor:thread-end key="TykTechnologies/tyk#8241@bcfdfa9" -->

---

*Powered by [Visor](https://probelabs.com/visor) from [Probelabs](https://probelabs.com)*

*Last updated: 2026-06-09T18:08:32.137Z | Triggered by: pr_updated | Commit: bcfdfa9*

💡 **TIP:** You can chat with Visor using `/visor ask <your question>`
<!-- /visor-comment-id:visor-thread-overview-TykTechnologies/tyk#8241 -->

Security Issues (1)

const maxShutdownDelay = 300 // 5 minutes
// In Start() function, after config is loaded:

if gwConfig.GracefulShutdownDelaySeconds > maxShutdownDelay {

mainLog.Warningf("Configured graceful shutdown delay of %d seconds is too high. Capping at %d seconds.", gwConfig.GracefulShutdownDelaySeconds, maxShutdownDelay)

gwConfig.GracefulShutdownDelaySeconds = maxShutdownDelay

}
// ... existing shutdown logic ...

if gwConfig.GracefulShutdownDelaySeconds > 0 {

mainLog.Infof("Delaying graceful shutdown for %d seconds", gwConfig.GracefulShutdownDelaySeconds)
select {
case <-time.After(time.Duration(gwConfig.GracefulShutdownDelaySeconds) * time.Second):
}

}

Security Issues (1)

const maxShutdownDelay = 300 // 5 minutes
// In Start() function, after config is loaded:

if gwConfig.GracefulShutdownDelaySeconds > maxShutdownDelay {

mainLog.Warningf("Configured graceful shutdown delay of %d seconds is too high. Capping at %d seconds.", gwConfig.GracefulShutdownDelaySeconds, maxShutdownDelay)

gwConfig.GracefulShutdownDelaySeconds = maxShutdownDelay

}
// ... existing shutdown logic ...

if gwConfig.GracefulShutdownDelaySeconds > 0 {

mainLog.Infof("Delaying graceful shutdown for %d seconds", gwConfig.GracefulShutdownDelaySeconds)
select {
case <-time.After(time.Duration(gwConfig.GracefulShutdownDelaySeconds) * time.Second):
}

}

✅ Performance Check Passed

No performance issues found – changes LGTM.

Quality Issues (1)

Powered by Visor from Probelabs

Last updated: 2026-06-09T18:08:11.935Z | Triggered by: pr_updated | Commit: bcfdfa9

💡 TIP: You can chat with Visor using /visor ask <your question>

🎯 Recommended Merge Targets

Based on JIRA ticket TT-16068: Enhance Graceful Shutdown Sequence to introduce a waiting period for Gateway Deregistration

Fix Version: Tyk 5.14.0

⚠️ Warning: Expected release branches not found in repository

Required:

• master - No matching release branches found. Fix will be included in future releases.

📋 Workflow

1. Merge this PR to master first

🚨 Jira Linter Failed

Commit: bcfdfa9
Failed at: 2026-06-09 18:07:02 UTC

The Jira linter failed to validate your PR. Please check the error details below:

failed to get Jira issue: failed to fetch Jira issue TT-16068: Issue does not exist or you do not have permission to see it.: request failed. Please analyze the request body for more details. Status code: 404

Next Steps

• Ensure your branch name contains a valid Jira ticket ID (e.g., ABC-123)
• Verify your PR title matches the branch's Jira ticket ID
• Check that the Jira ticket exists and is accessible

This comment will be automatically deleted once the linter passes.

Quality Gate failed

Failed conditions
42.9% Coverage on New Code (required ≥ 80%)
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE