Targets

A Target identifies an instance of an upstream service using an IP address or hostname with a port. Each Upstream can have many Targets. Targets are used by Upstreams for load balancing. For example, if you have an example_upstream Upstream, you can point it to two different Targets: httpbin.konghq.com and httpbun.com. This is so that if one of the servers (like httpbin.konghq.com) is unavailable, it automatically detects the problem and routes all traffic to the working server (httpbun.com).

The following diagram illustrates how Targets are used by Upstreams for load balancing:

 
flowchart LR

  A("Request")
  B("`Route 
  (/mock)`")
  C("`Service
  (example_service)`")
  D("Target:
  httpbin.konghq.com")
  E("Target:
  httpbun.com")
  F(Upstream service:
  httpbin.konghq.com)
  G(Upstream service:
  httpbun.com)

  A --> B
  subgraph id1 ["`**KONG GATEWAY**`"]
    B --> C --> D & E
  subgraph id3 ["`**Upstream** (load balancer)`"]
  
    D & E
  end

  end

  subgraph id2 ["`**Target upstream services**`"]
    D --> F
    E --> G

  end

  style id2 stroke:none!important
  

A Target can also have a hostname instead of an IP address. In that case, the name is resolved and all entries found are individually added to the load balancer.

For example, let’s say you add api.host.com:123 with weight=100:

• If the hostname api.host.com resolves to an A record with 2 IP addresses, both IP addresses are added as a target, each with weight=100 and port 123.
• If the hostname resolves to an SRV record, then the port and weight fields from the DNS record are used, and override the port and weight set in the Target.

The balancer honors the DNS record’s ttl setting. Upon expiry, it queries the nameserver and updates the balancer. When a DNS record has ttl=0, the hostname is added as a single target, with the specified weight. The nameserver is queried for every request, adding latency to the request.

You can set failover: true to indicate that a Target should be used as a failover (backup) Target in case the other, regular targets (failover: false) associated with an Upstream are unhealthy. The failover Target is only used when all regular Targets are unhealthy. You can set one or multiple failover Targets for an Upstream.

Failover Targets are supported by the latency, least-connections, and round-robin load balancing algorithms.

Note: If you set failover Targets for Upstreams with the consistent-hashing or sticky session load balancing algorithms, they won’t be used for regular load balancing or as a failover.

The following is an example failover Target configuration:

_format_version: "3.0"
upstreams:
  - name: example_upstream
    targets:
    - target: 192.168.1.3:8080
      weight: 50
      failover: true

curl -i -X POST http://localhost:8001/upstreams/{upstreamName|Id}/targets/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "target": "192.168.1.3:8080",
      "weight": 50,
      "failover": true
    }
    '

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/upstreams/{upstreamId}/targets/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "target": "192.168.1.3:8080",
      "weight": 50,
      "failover": true
    }
    '

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

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

resource "konnect_gateway_target" "my_target" {
  target = "192.168.1.3:8080"
  weight = 50
  failover = true

  upstream_id = konnect_gateway_upstream.my_upstream.id
  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

For a complete tutorial, see Route requests to backup Targets during failures.