Was this helpful?


Apigee Edge enhances the availability of your API by providing built-in support for load balancing and failover across multiple backend server instances.

TargetServer configurations decouple concrete endpoint URLs from TargetEndpoint configurations. Each TargetServer is referenced by name in a TargetEndpoint HTTPConnection. Instead of defining concrete URL in the configuration, you can configure one or more named TargetServers. 

A TargetServer definition consists of a name, a host and a port, with an additional element to indicate whether the TargetServer is enabled or disabled.

Sample TargetServer Configuration:

<TargetServer  name="target1">
  <Host>1.mybackendservice.com</Host>
  <Port>80</Port>
  <IsEnabled>true</IsEnabled>
</TargetServer >

TargetServer Configuration Elements

Name Description Default Required?
name The name of the TargetServer configuration. The name must be unique within the environment. N/A Yes
Host The host URL of the backend service. N/A Yes
Port The port on which the backend service is listening N/A Yes
IsEnabled A boolean that indicates whether the TargetServer configuration is enabled or disabled. This enables you to take TargetServers out of rotation without modifying the API proxy configuration. A common usage would be to write an app or script that enables or disables TargetServers automatically based on expected capacity requirements, maintenance schedules, etc. true Yes

To create a TargetServer in an environment:

$ curl -H "Content-Type:text/xml" -X POST -d \
'<TargetServer name="target1">
   <Host>1.mybackendservice.com</Host>
   <Port>80</Port>
   <IsEnabled>true</IsEnabled>
 </TargetServer>' \
-u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/targetservers

Sample Response:

{
  "host" : "1.mybackendservice.com",
  "isEnabled" : true,
  "name" : "target1",
  "port" : 80
}

After you create the first TargetServer, then create a second TargetServer. By defining two TargetServers, you provide two URLs that a TargetEndpoint can use for loadbalancing:

$ curl -H "Content-type:text/xml" -X POST -d \
'<TargetServer  name="target2">
  <Host>2.mybackendservice.com</Host>
  <Port>80</Port>
  <IsEnabled>true</IsEnabled>
</TargetServer >' \
-u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/targetservers

Sample Response:

{
  "host" : "2.mybackendservice.com",
  "isEnabled" : true,
  "name" : "target2",
  "port" : 80
}

Retrieve a list of TargetServers in an environment:

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/targetservers

Sample response:

[ "target2", "target1" ]

There are now two TargetServers available for use by API proxies deployed in the test environment. To load balance traffic across these TargetServers, you configure the HTTP connection in an API proxy's target endpoint to use the TargetServers.

There is no limit on the number of TargetServers that you can set up in an environment or reference from a TargetEndpoint's HTTPConnection.

Configuring a TargetEndpoint to load balance across named TargetServers

Now that you have two TargetServers available, you can modify the TargetEndpoint HTTP connection setting to reference those two TargetServers by name.

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <LoadBalancer>
      <Server name="target1" />
      <Server name="target2" />
    </LoadBalancer>
    <Path>/test</Path>
  </HTTPTargetConnection>
</TargetEndpoint>

The configuration above is the most basic load balancing configuration possible. The load balancer supports three load balancing algorithms, Round Robin, Weighted, and Least Connection. Round Robin is the default algorithm. Since no algorithm is specified in the configuration above, outbound requests from the API proxy to the backend servers will alternate, one for one, between target1 and target 2. 

Retries are triggered by I/O exceptions and HTTP time outs. Retries are not triggered by HTTP error codes (4xx, 5xx).

Setting load balancer options

You can tune availability by using options for load balancing and failover at the load balancer and TargetServer level.

Available options for LoadBalancers are:

Algorithm

Sets the algorithm used by LoadBalancer. The available algorithms are RoundRobin, Weighted, and MaximumFailures, each of which is documented below.

Round robin

The default algorithm,

RoundRobin

forwards a request to each TargetServer in the order in which the servers are listed in the target endpoint HTTP connection.

For example:

<TargetEndpoint name="default">
  <HTTPTargetConnection>
      <LoadBalancer>
        <Algorithm>RoundRobin</Algorithm>
        <Server name="target1" />
        <Server name="target2" />
      </LoadBalancer>
      <Path>/test</Path>
  </HTTPTargetConnection>
</TargetEndpoint>

Weighted

The weighted load balancing algorithm enables you to configure proportional traffic loads for your TargetServers. The weighted LoadBalancer distributes request to your TargetServers in direct proportion to each TargetServer 's weight. Therefore, the weighted algorithm requires you to set a weight attribute for each TargetServer . For example:

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <LoadBalancer>
      <Algorithm>Weighted</Algorithm>
      <Server name="target1">
        <Weight>1</Weight>
      </Server>
      <Server name="target2">
        <Weight>2</Weight>
      </Server>
    </LoadBalancer>
    <Path>/test</Path>
  </HTTPTargetConnection>
</TargetEndpoint>

In this example, 2 requests will be routed to target2 for every 1 request routed to target1.

Least Connection

LoadBalancers configured to use the least connection algorithm route outbound requests to the TargetServer with fewest open HTTP connections.

<TargetEndpoint name="default">
  <HTTPTargetConnection>
      <LoadBalancer>
        <Algorithm>LeastConnection</Algorithm>
        <Server name="target1" />
        <Server name="target2" />
      </LoadBalancer>
  </HTTPTargetConnection>
  <Path>/test</Path>
</TargetEndpoint>

Maximum failures

The maximum number of failed requests from the API proxy to the TargetServer that results in the request being redirected to another TargetServer . As configured below, target1 will be removed from rotation after 5 failed requests.

<TargetEndpoint name="default">
  <HTTPTargetConnection>
      <LoadBalancer>
        <Algorithm>RoundRobin</Algorithm>
        <Server name="target1" />
           <MaxFailures>5</MaxFailures>
        <Server name="target2" />
      </LoadBalancer>
      <Path>/test</Path>
  </HTTPTargetConnection>
</TargetEndpoint>
If you configure MaxFailures without also configuring a HealthMonitor, then eventually all of your TargetServers will be removed from rotation. If you configure MaxFailures, always configure an associated HealthMonitor.

Retry

Retry the request once to a different server after an I/O error (not an HTTP status code 500).

<RetryEnabled>true</RetryEnabled>

IsFallback

One (and only one) TargetServer can be set as the 'fallback' server. The fallback TargetServer is not included in load balancing routines until all other TargetServers are identified as unavailable by the load balancer. When the load balancer determines that all TargetServers are unavailable, all traffic is routed to the fallback server. For example:

<TargetEndpoint name="default">
  <HTTPTargetConnection>
      <LoadBalancer>
        <Algorithm>RoundRobin</Algorithm>
        <Server name="target1" />
        <Server name="target2" />
        <Server name="target3" />
          <IsFallback>true</IsFallback>
      </LoadBalancer>
      <Path>/test</Path>
  </HTTPTargetConnection>
</TargetEndpoint>

The configuration above results in round robin load balancing between targets 1 and 2 until both targets 1 and 2 are unavailable. When targets 1 and 2 are unavailable, all traffic is routed to target 3.

Path

Path defines a URI fragment that will be appended to all requests issued by the TargetServer to the backend server.

Health monitoring

Health monitoring enables you to enhance load balancing configurations by actively polling the backend service URLs defined in the TargetServer configurations. The HealthMonitor acts as a simple client that invokes a backend service over TCP or HTTP. A TCP client simply ensures that a socket can opened. You configure the HTTP client to submit a valid HTTP request to the backend service. You can define HTTP GET, PUT, POST, or DELETE operations. Typically, you define a simple GET request that simply shows that the backend service is available. 

You create a HealthMonitor by setting one up in a TargetEndpoint's HTTPConnection configuration. A simple HealthMonitor defines an IntervalInSec combined with either a TCPMonitor or an HTTPMonitor.

TCPMonitor

The configuration below defines a HealthMonitor that polls each TargetServer by opening a connection on port 80 every 5 seconds.

  • If the connection fails or takes more than 10 seconds to connect, then the failure count increments by 1 for that TargetServer.
  • If the connection succeeds, then the failure count for the TargetServer is reset to 0.

You can add a HealthMonitor as a child element of the TargetEndpoint's HTTPTargetConnetion element, as shown below:

<TargetEndpoint name="default">
  <HTTPTargetConnection><HealthMonitor>
    <IsEnabled>true</IsEnabled>
    <IntervalInSec>5</IntervalInSec>
    <TCPMonitor>
      <ConnectTimeoutInSec>10</ConnectTimeoutInSec>
      <Port>80</Port>
    </TCPMonitor>
  </HealthMonitor>
. . .

HealthMonitor with TCPMonitor Configuration Elements

Name Description Default Required?
IsEnabled A boolean that enables or disables the HealthMonitor. false No
IntervalInSec The time interval, in seconds, between each polling TCP request. 0 Yes
ConnectTimeoutInSec Time in which connection to the TCP port must be established to be considered a success. Failure to connect in the specified interval counts as a failure, incrementing the load balancer's failure count for the TargetServer. 0 Yes
Port The port on which the TCP connection will be established. 0 Yes

HTTPMonitor

A sample HealthMonitor that uses an HTTPMonitor will submit a GET request to the backend service once every five seconds. The sample below adds an HTTP Basic Authorization header to the request message. The Response configuration defines settings that will be compared against actual response from the backend service. In the example below, the expected response is an HTTP response code 200 and a custom HTTP header ImOK whose value is YoureOK. If the response does not match, then the request will treated as a failure by the load balancer configuration.

Note that all of the Request and Response settings in an HTTP monitor will be specific to the backend service that must be invoked.

<HealthMonitor>
  <IsEnabled>true</IsEnabled>
  <IntervalInSec>5</IntervalInSec>
  <HTTPMonitor> 
    <Request>
      <ConnectTimeoutInSec>10</ConnectTimeoutInSec>
      <SocketReadTimeoutInSec>30</SocketReadTimeoutInSec>
      <Port>80</Port>
      <Verb>GET</Verb>
      <Path>/healthcheck</Path>
      <Headers>
        <Header name="Authorization">Basic 12e98yfw87etf</Header>
      </Headers>
    </Request>
    <SuccessResponse> 
      <ResponseCode>200</ResponseCode>
      <Headers>
        <Header name=”ImOK”>YoureOK</Header>
      </Headers>
    </SuccessResponse>
  </HTTPMonitor> 
</HealthMonitor>

HealthMonitor with HTTPMonitor Configuration Elements

Name Description Default Required?
IsEnabled A boolean that enables or disables the HealthMonitor. false No
IntervalInSec The time interval, in seconds, between each polling HTTP request. 0 Yes
Request Configuration options for the outbound HTTP request message sent by the HealthMonitor to the TargetServers in the rotation. N/A Yes
ConnectTimeoutInSec Time, in seconds, in which the TCP connection handshake to the HTTP service must complete to be considered a success. Failure to connect in the specified interval counts as a failure, incrementing the LoadBalancer's failure count for the TargetServer. 0 No
SocketReadTimeoutInSec Time, in seconds, in which data must be read from the HTTP service to be considered a success. Failure to read in the specified interval counts as a failure, incrementing the LoadBalancer's failure count for the TargetServer. 0 No
Port The port on which the HTTP connection to the backend service will be established. N/A No
Verb The HTTP verb used for each polling HTTP request to the backend service . N/A No
Path The path appended to the URL defined in the TargetServer. Use the path element to configure a 'polling endpoint' on your HTTP service. N/A No
Headers A list of one or more HTTP headers and their values that will be populated on each polling HTTP request. N/A No
Payload The HTTP body generated for each polling HTTP request. Note that this element is not required for GET requests. N/A No
Response Matching options for the inbound HTTP response message generated by the polled backend service. Responses that do not match increment the failure count by 1. N/A Yes
ResponseCode The HTTP response code expected to be received from the polled TargetServer. A code different than the code specified results in a failure, and the count being incremented for the polled backend service. You can define multiple ResponseCode elements. N/A No
Headers A list of one or more HTTP headers and values expected to be received from the polled backend service. Any HTTP headers or values on the response that are different from those specified result in a failure, and the count for the polled TargetServer is incremented by 1. You can define multiple Header elements. N/A No

Configuring outbound client SSL for mutual authentication

TargetServers expose the same SSL configuration settings as TargetEndpoints.

<TargetServer  name="TargetServer 1"> 
    <IsEnabled>true</IsEnabled> 
    <Host>www.example.com/Host> 
    <Port>443</Port> 
    <SSLInfo> 
        <Ciphers/> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <Enabled>true</Enabled> 
        <IgnoreValidationErrors>false</IgnoreValidationErrors> 
        <KeyAlias>keystore-alias</KeyAlias> 
        <KeyStore>keystore-name</KeyStore> 
        <Protocols/> 
        <TrustStore>truststore-name</TrustStore> 
    </SSLInfo> 
</TargetServer > 

For complete instructions on configuring outbound client SSL, see Client-SSL to backend servers.

Get help

For help, see Apigee Customer Support.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)