Gateway Services

Uses: Kong Gateway Admin API deck KIC Konnect API Terraform

What is a Gateway Service?

Gateway Services represent the upstream services in your system. These applications are the business logic components of your system responsible for responding to requests.

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.

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.

Gateway Services, in conjunction with Routes, let you expose your upstream services to clients with Kong Gateway.

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

Schema

* Additional properties are NOT allowed.

ca_certificatesarray[string]

Array of CA Certificate object UUIDs that are used to build the trust store while verifying upstream server’s TLS certificate. If set to null when Nginx default is respected. If default CA list in Nginx are not specified and TLS verification is enabled, then handshake with upstream server will always fail (because no CA are trusted).

client_certificateobject

Certificate to be used as client certificate while TLS handshaking to the upstream server.

Hide Child Parameters

idstring

connect_timeoutinteger

The timeout in milliseconds for establishing a connection to the upstream server.

Default:60000

created_atinteger

Unix epoch when the resource was created.

enabledboolean

Whether the Service is active. If set to false, the proxy behavior will be as if any routes attached to it do not exist (404). Default: true.

Default:true

hoststringrequired

The host of the upstream server. Note that the host value is case sensitive.

idstring

namestring

The Service name.

pathstring

The path to be used in requests to the upstream server.

portinteger

The upstream server port.

Default:80

protocolstring

The protocol used to communicate with the upstream.

Allowed values:grpcgrpcshttphttpstcptlstls_passthroughudpwswss

Default:http

read_timeoutinteger

The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server.

Default:60000

retriesinteger

The number of retries to execute upon failure to proxy.

Default:5

tagsarray[string]

An optional set of strings associated with the Service for grouping and filtering.

tls_sansobject

Hide Child Parameters

dnsnamesarray[string]

urisarray[string]

tls_verifyboolean

Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected.

tls_verify_depthinteger

Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to null, then the Nginx default is respected.

updated_atinteger

Unix epoch when the resource was last updated.

urlstring

Helper field to set protocol, host, port and path using a URL. This field is write-only and is not returned in responses.

write_timeoutinteger

The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server.

Default:60000

Set up a Gateway Service

The following creates a new Gateway Service called example-service with basic configuration:

_format_version: "3.0"
services:
  - name: example-service
    url: http://httpbin.konghq.com

Copied to clipboard!

To create a Gateway Service, call the Admin API’s /services endpoint.

curl -i -X POST http://localhost:8001/services/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "example-service",
      "url": "http://httpbin.konghq.com"
    }
    '

      
        
      
    
Copied to clipboard!

To create a Gateway Service, call the Konnect control plane config API’s /services endpoint.

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/services/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "example-service",
      "url": "http://httpbin.konghq.com"
    }
    '

      
        
      
    
Copied to clipboard!

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.

See the Konnect API reference to learn about region-specific URLs and personal access tokens.

Kong Ingress Controller doesn’t manage Services directly. Any Kubernetes resources referenced by an Ingress or Gateway API *Route resource will automatically be created.

Create a Route to get started.

Prerequisite: Configure your Personal Access Token

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

      
        
      
    
Copied to clipboard!

resource "konnect_gateway_service" "my_service" {
  url = "http://httpbin.konghq.com"

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

Copied to clipboard!

The following creates a new Service called example-service with basic configuration:

In Kong Manager or Gateway Manager, go to Gateway Services.
Click New Gateway Service.
Enter a unique name for the Service. In this example, it’s example-service.
Define the endpoint for this Service by specifying the full URL or by its separate elements. In this example, the full upstream URL is http://httpbin.konghq.com.
Click Save.

Gateway Services

What is a Gateway Service?

Schema

Set up a Gateway Service

Did this doc help?

Help us make these docs great!

Still need help