Gateway Services

Gateway Services represent the upstream services in your system. Services are the business logic components of your system that are responsible for processing and responding to requests. Gateway Services, in conjunction with Routes, let you expose your upstream services to clients with Kong Gateway.

The configuration of a Gateway Service defines the connectivity details between the Kong Gateway and the upstream service, along with other metadata. Generally, you should map one Gateway Service to each upstream service.

Here’s how it works:

1. A client sends a request.
2. A Route matches the request based on defined rules and sends it to a specific Gateway Service.
3. The Gateway Service receives the request and forwards it to your actual application (the upstream service).
   • For simple deployments, the upstream URL can be provided directly in the Gateway Service.
   • For sophisticated traffic management needs, a Gateway Service can point at an Upstream entity.
4. The upstream service processes the request and sends a response back through Kong Gateway.

Plugins can also be attached to a Service, and will run against every request that triggers a request to the Service that they’re attached to.

 
flowchart LR
  A(API client)
  B("`Route 
  (/mock)`")
  C("`Gateway Service
  (example-service)`")
  D(Service 
  application)
  
  A <--requests
  responses--> B
  subgraph id1 ["`
  **KONG GATEWAY**`"]
    B <--requests
    responses--> C
  end
  C <--requests
  responses--> D

  style id1 rx:10,ry:10
  
  

Figure 1: Diagram showing the request and response flow through Kong Gateway.

Timeouts are configured at the Service level and influence retry behavior when failures occur.

Connect timeout

The connect_timeout parameter defines the time allowed to establish a TCP connection to the upstream server. If the connection can’t be opened, it fails at the socket-setup layer. Kong Gateway returns a 502 Bad Gateway response and retries the request up to the number of retries that are configured with the retries parameter.

Read timeout

The read_timeout parameter defines the time that the Kong Gateway waits for the upstream to send a full response after establishing a connection. If the upstream stalls, Kong Gateway triggers the timeout once the idle time exceeds the configured value and returns a 504 Gateway Time-out response.

The retry behavior depends on the method used:

• Idempotent methods (GET, HEAD, PUT, DELETE, OPTIONS, and TRACE): Kong Gateway retries the request up to the number of retries configured with the retries parameter.
• Non-idempotent methods (POST, PATCH, LOCK, UNLOCK, PROPPATCH, MKCOL, MOVE, and COPY): Kong Gateway will not retry unless proxy_next_upstream non_idempotent is set in the NGINX configuration by default.

Write timeout

The write_timeout parameter defines the idle time between successive write operations when sending a request body to the upstream. It measures gaps in data transmission, not the total upload duration. The timer resets after each successful write. The timeout triggers if the upstream accepts the connection but delays receiving the body at the TCP level. Kong Gateway returns a 504 Gateway Time-out response.

The retry behavior depends on the method used:

• Idempotent methods (GET, HEAD, PUT, DELETE, OPTIONS, and TRACE): Kong Gateway retries the request up to the number of retries configured with the retries parameter.
• Non-idempotent methods (POST, PATCH, LOCK, UNLOCK, PROPPATCH, MKCOL, MOVE, and COPY): Kong Gateway will not retry unless proxy_next_upstream non_idempotent is set in the NGINX configuration by default.