#!wiki caution
'''Note'''

If you want to discuss changes to this spec or found an error, please contact uma.goring AT rackspace.com or youcef.laribi AT citrix.com

OpenStack LoadBalancers API 1.1

概述

预期读者

本指南面向希望使用 OpenStack Load Balancers API 创建应用程序的软件开发人员。它假定读者对负载均衡概念有一般了解，并且熟悉

RESTful Web 服务
HTTP/1.1 约定
JSON 和/或 XML 序列化格式

文档变更历史

本版本的开发者指南取代并废止所有先前版本。下表描述了最新的更改

修订日期变更摘要

修订日期

2012 年 2 月 9 日

2012 年 1 月 24 日

2011 年 5 月 27 日

2011 年 4 月 19 日

2011 年 2 月 23 日

概念

要有效地使用 OpenStack Load Balancers API，您应该了解几个关键概念

负载均衡器

负载均衡器是一个逻辑设备。它用于根据其配置中定义的标准，在多个后端系统或服务（称为节点）之间分配工作负载。

虚拟 IP

虚拟 IP 是配置在负载均衡器上的互联网协议 (IP) 地址，供连接到负载均衡服务的客户端使用。传入的连接和请求根据负载均衡器的配置分发到后端节点。

节点

节点是在指定 IP 和端口上提供服务的后端设备。

健康监控

健康监控是每个负载均衡器的一个功能。它用于确定负载均衡器的后端节点是否可用以处理请求。负载均衡服务支持两种健康监控模式：被动和主动。

被动健康监控

默认情况下，所有负载均衡配置都使用被动健康监控，这是默认监控，不需要用户进行任何配置。如果被动健康监控确定节点已关闭、无法访问或发生故障，则将节点置于 OFFLINE 状态并停止向其发送流量。

主动健康监控

主动健康监控是一种由用户显式配置的技术。它使用以定期间隔执行的合成事务来确定节点的状态。激活主动监控时，它将接管节点的监控，并禁用被动监控。相反，当用户删除主动监控时，将被动监控重新启用到负载均衡器的节点。这保证了始终监控节点健康状况。

在配置主动健康监控时，用户可以选择使用以下三种类型的探测器之一

CONNECT
HTTP
HTTPS

这些探测器以配置的间隔执行；如果发生故障，节点状态更改为 OFFLINE，节点将不会接收流量。如果后续测试运行检测到节点已恢复，则节点状态更改为 ONLINE，并且能够服务请求。

会话持久性

会话持久性是负载均衡服务的一个功能。它尝试强制同一会话中的后续连接或请求重定向到与之前相同的节点，只要该节点在线即可。

通用 API 信息

本章中的部分介绍了适用于所有 OpenStack API 的操作和指南，并且不特定于负载均衡 API。

身份验证

此 API 使用 OpenStack 定义的标准进行身份验证。目前这仍在进行中。一旦完成，本节将描述用户如何从 OpenStack 身份验证服务进行身份验证并获取令牌，以及如何在负载均衡 API 中呈现此令牌。

请参阅 OpenStack 身份验证的当前状态：https://wiki.openstack.org/openstack-authn 以及 OpenStack 项目 KeyStone 以获取详细信息。

服务访问/端点

您的服务提供商将发布您可以用来连接到其运营的 LB 服务的端点。

请求/响应类型

Cloud Load Balancers API 支持 JSON 和 XML 数据序列化格式。请求格式使用 Content-Type 标头指定，并且对于具有请求主体的操作是必需的。可以使用 Accept 标头或在请求 URI 中添加 .xml 或 .json 扩展来指定响应格式。请注意，响应可以使用与请求不同的格式进行序列化。如果未指定响应格式，则默认使用 JSON。如果使用 Accept 标头和查询扩展指定了冲突的格式，则查询扩展优先。

表 3.1. JSON 和 XML 响应格式

格式	Accept 标头	查询扩展
JSON	application/json	.json
XML	application/xml	.xml

内容压缩

请求和响应主体数据可以使用 gzip 压缩进行编码，以加速 API 调用和响应的交互性能。这由客户端请求中的 Accept-Encoding 标头控制，并由服务器响应中的 Content-Encoding 标头指示。

除非显式设置标头，否则编码默认禁用。

表 3.2. 编码标头

头部	类型	姓名
HTTP/1.1	请求	Accept-Encoding
HTTP/1.1	响应	Content-Encoding

持久连接

默认情况下，API 支持通过 HTTP/1.1 keep-alives 进行持久连接。除非将 connection 标头设置为 close，否则所有连接都将保持活动状态。

#!wiki caution
'''Note'''

The server may close the connection at any time and clients should not rely on this behavior.

分页集合

为了减少服务负载，列表操作一次最多返回 100 个项目。要浏览集合，可以将 limit 和 marker 参数（例如，?limit=50&marker=1）设置为 URI 中。如果给定的 marker 超出了列表的末尾，则返回一个空列表。请注意，列表操作绝不会返回 404（itemNotFound）错误。

限制

帐户可以预配置一组阈值（或限制）来管理容量并防止滥用系统。系统识别两种类型的限制：速率限制和绝对限制。

速率限制

我们使用人类可读的通配符 URI 和机器可处理的正则表达式来指定速率限制。正则表达式边界匹配器 '^' 在根 URI 路径之后生效。例如，正则表达式/v1.1/1234/loadbalancers 将匹配以下 URI 的粗体部分：https://loadbalancers.api.openstack.org/v1.1/1234/loadbalancers。

表 3.3. 默认速率限制

动词	URI	RegEx
GET	/v1.1/*	^/1.1/.*
POST	/v1.1/*	^/1.1/.*
POST	/v1.1/*	^/1.1/.*
PUT	/v1.1/*	^/1.1/.*
DELETE	/v1.1/*	^/1.1/.*

速率限制按相对于动词的顺序应用，从最不具体到最具体。例如，虽然 POST 到 /v1.1/* 的阈值为每分钟 25 次，但不能 POST 到 /v1.1/* 超过每秒 2 次，因为任何 POST 的速率限制为每秒 2 次。如果您超过帐户建立的阈值，将返回 413（Rate Control）HTTP 响应，其中包含 Retry-After 标头，以通知客户端何时可以尝试重试。

绝对限制

绝对限制指定为名称/值对。然后，绝对限制的名称唯一标识部署中的限制。例如，maxNodesPerLoadbalancer 标识与给定负载均衡器关联的节点总数。

下表显示了一些这些限制和示例值

姓名	值
maxLoadBalancers	20
maxNodesPerLoadBalancer	5
maxVIPsPerLoadBalancer	1
maxDaysKeptForDeletedLoadBalancers	15
maxLoadBalancerNameLength	15

以编程方式确定限制

应用程序可以使用以下 /limits URI 以编程方式确定当前帐户限制

动词	URI
GET	/limits

正常响应代码: 200

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

此操作不需要请求主体。

示例 3.1. 列出限制响应：XML

#!highlight xml numbers=disable
<limits xmlns="https://docs.openstack.org/common/api/v1.1">
   <rates>
      <rate uri="/v1.1/*" regex="^/1.1/.*">
          <limit  verb="GET"  value="600000"
                  remaining="426852"  unit="HOUR"
                  next-available="2011-02-22T19:32:43.835Z"/>
      </rate>
   </rates>

   <absolute>
       <limit name="maxNodesPerLoadBalancer" value="5"/>
       <limit name="maxVIPsPerLoadBalancer" value="1"/>
   </absolute>
</limits>

示例 3.2. 列出限制响应：JSON

#!highlight javascript numbers=disable
 {
    "limits" :
          {
            "rate" : {
                       "values": [
                                  {
                                    "uri" : "/v1.1/*",
                                    "regex" : "^/1./.*",
                                    "limit" : [
                                               {
                                                 "verb" : "GET",
                                                 "value" : 600000,
                                                 "remaining" : 426852,
                                                 "unit" : "HOUR",
                                                 "next-available" : "2011-02-22T19:32:43.835Z"
                                               }
                                              ]
                                  }

                                ]
                     },
            "absolute" : {
                           "values" : {
                                        "maxNodesPerLoadBalancer" : "5",
                                        "maxVIPsPerLoadBalancer" : "1"
                                      }
                         }
          }
}

错误

返回错误的 API 调用返回以下故障对象之一。所有故障对象都从基本故障 serviceFault 扩展而来，以便于支持它的语言进行异常处理。

serviceFault

serviceFault 以及所有其他故障都包含 message 和 detail 元素，这些元素包含描述故障性质的字符串以及表示 HTTP 响应代码的 code 属性，以便于使用。故障的 code 属性是为了方便调用者，以便他们可以从 HTTP 响应标头或直接从故障对象中检索响应代码（如果他们选择这样做）。调用者不应期望直接返回 serviceFault，而应期望仅返回一个子故障。

badRequest

此故障指示请求对象中的数据无效；例如，在预期整数的参数中使用字符串。该故障将包装验证错误。

示例 3.3. 故障响应，badRequest

#!highlight xml numbers=disable
<badRequest xmlns="https://docs.openstack.org/atlas/api/v1.1" code="400">
   <message>Validation fault</message>
   <details>The object is not valid</details>
   <validationErrors>
      <message>Node IP address is invalid. Please specify a valid IP address.</message>
   </validationErrors>
</badRequest>

immutableEntity

当用户尝试修改当前状态不允许修改的项目时，将返回此故障。例如，状态为 BUILD、PENDING_UPDATE 或 DELETED 的负载均衡器可能无法修改。

示例 3.4. 故障响应，immutableEntity

#!highlight xml numbers=disable
<immutableEntity code="422" xmlns="https://docs.openstack.org/atlas/api/v1.1">
  <message>The object at the specified URI is immutable and cannot be modified.
  </message>
</immutableEntity>

itemNotFound

示例 3.5. 故障响应，itemNotFound

#!highlight xml numbers=disable
<itemNotFound code="404" xmlns="https://docs.openstack.org/atlas/api/v1.1">
  <message>Object not Found</message>
</itemNotFound>

loadBalancerFault

如果在负载均衡器操作期间发生意外错误，将返回 loadBalancerFault 故障。

示例 3.6. 故障响应，loadBalancerFault

#!highlight xml numbers=disable
<loadBalancerFault code="500" xmlns="https://docs.openstack.org/atlas/api/v1.1">
  <message>Load Balancer has experienced an internal error</message>
</loadBalancerFault>

outOfVirtualIps

此故障指示没有虚拟 IP 剩余可分配给新的负载均衡器。实际上，此故障不应发生，因为虚拟 IP 将按需订购容量。

示例 3.7. 故障响应，outOfVirtualIps

#!highlight xml numbers=disable
<outOfVirtualIps code="500" xmlns="https://docs.openstack.org/atlas/api/v1.1">
   <message>
       Out of virtual IPs. Please contact support so they can allocate more virtual IPs.
   </message>
</outOfVirtualIps>

overLimit

当用户超过当前分配的限制时，将返回此故障。

示例 3.8. 故障响应，overLimit

#!highlight xml numbers=disable
<overLimit code="413" xmlns="https://docs.openstack.org/atlas/api/v1.1">
  <message>
    Load balancer cannot be created. You have reached your maximum number of load balancers.
  </message>
</overLimit>

serviceUnavailable

当服务不可用时，例如服务正在维护中，将返回此故障。请注意，这并不一定意味着当前配置的负载均衡器无法处理流量；它只是意味着 API 当前无法服务请求。

示例 3.9. 故障响应，serviceUnavailable

#!highlight xml numbers=disable
<serviceUnavailable code="500" xmlns="https://docs.openstack.org/atlas/api/v1.1">
   <message>The Load balancing service is currently not available</message>
</serviceUnavailable>

unauthorized

当用户未被授权执行尝试的操作时，将返回此故障。

示例 3.10. 故障响应，unauthorized

#!highlight xml numbers=disable
<unauthorized code="401" xmlns="https://docs.openstack.org/atlas/api/v1.1">
    <message>You are not authorized to execute this operation.</message>
</unauthorized>

unprocessableEntity

由于语义错误，实体无法处理时，将返回此故障。

示例 3.11. 故障响应，unprocessableEntity

#!highlight xml numbers=disable
<unprocessableEntity code="422" xmlns="https://docs.openstack.org/atlas/api/v1.1">
   <message>The Object at the specified URI is unprocessable.</message>
</unprocessableEntity>

API 操作

本章解释了特定的 API 操作。有关适用于所有 API 操作的想法，请参阅“通用 API 信息”章节。

负载均衡器

列出负载均衡器

动词	URI	描述
GET	/loadbalancers	列出为帐户配置的所有负载均衡器。

正常响应代码: 200

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

此操作提供与您的帐户配置和关联的所有负载均衡器的列表。

要查看已删除的负载均衡器，请将 "?status=DELETED" 添加到 GET URI 的末尾。已删除的负载均衡器是不可变的且无法恢复的。

此操作返回每个负载均衡器的以下属性

id
name
algorithm
protocol
port
status
created
updated

此操作不需要请求主体。

示例 4.1. 列出负载均衡器响应：XML

#!highlight xml numbers=disable
<?xml version="1.0" ?>
<loadBalancers xmlns="https://docs.openstack.org/atlas/api/v1.1">
  <loadBalancer id="71" name="lb-site1" status="ACTIVE"
                protocol="HTTP" port="80" algorithm="LEAST_CONNECTIONS" created="2010-12-13T15:38:27-06:00" updated="2010-12-13T15:38:38-06:00" >
  </loadBalancer>

  <loadBalancer id="166" name="lb-site2" status="ACTIVE"
                protocol="HTTP" port="80" algorithm="ROUND_ROBIN"  created="2010-12-13T15:38:27-06:00" updated="2010-12-13T15:38:38-06:00" >
  </loadBalancer>
</loadBalancers>

示例 4.2. 列出负载均衡器响应：JSON

#!highlight javascript numbers=disable
{
  "loadBalancers":[
         {
           "name":"lb-site1",
           "id":"71",
           "protocol":"HTTP",
           "port":"80",
           "algorithm":"LEAST_CONNECTIONS",
           "status":"ACTIVE",
           "created":"2010-11-30T03:23:42Z",
           "updated":"2010-11-30T03:23:44Z"
         },
         {
           "name":"lb-site2",
           "id":"166",
           "protocol":"TCP",
           "port":"9123",
           "algorithm":"ROUND_ROBIN",
           "status":"ACTIVE",
           "created":"2010-11-30T03:23:42Z",
           "updated":"2010-11-30T03:23:44Z"
         }
      ]
}

列出负载均衡器详情

动词	URI	描述
GET	/loadbalancers/loadBalancerId	列出指定负载均衡器的详细信息。

正常响应代码: 200

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

此操作为与您的帐户配置和关联的特定负载均衡器提供详细输出。此操作无法返回已被删除的负载均衡器的详细信息。

此操作不需要请求主体。

示例 4.3. 列出负载均衡器详细信息响应：XML

#!highlight xml numbers=disable
<loadBalancer xmlns="https://docs.openstack.org/atlas/api/v1.1"
   id="2000"
   name="sample-loadbalancer"
   protocol="HTTP"
   port="80"
   algorithm="ROUND_ROBIN"
   status="ACTIVE"
   created="2010-11-30T03:23:42Z"
   updated="2010-11-30T03:23:44Z">

   <virtualIps>
     <virtualIp id="1000" address="2001:cdba:0000:0000:0000:0000:3257:9652" type="PUBLIC" ipVersion="IPV6" />
   </virtualIps>

   <nodes>
     <node id="1041" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" />
     <node id="1411" address="10.1.1.2" port="80" condition="ENABLED" status="ONLINE" />
   </nodes>

   <sessionPersistence persistenceType="HTTP_COOKIE"/>

   <connectionThrottle maxRequestRate="50" rateInterval="60" />

</loadBalancer>

示例 4.4. 列出负载均衡器详细信息响应：JSON

#!highlight javascript numbers=disable
{
      "id": "2000",
      "name":"sample-loadbalancer",
      "protocol":"HTTP",
      "port": "80",
      "algorithm":"ROUND_ROBIN",
      "status":"ACTIVE",
      "created":"2010-11-30T03:23:42Z",
      "updated":"2010-11-30T03:23:44Z",
      "virtualIps":[
                    {
                       "id": "1000",
                       "address":"2001:cdba:0000:0000:0000:0000:3257:9652",
                       "type":"PUBLIC",
                       "ipVersion":"IPV6"
                    }
                   ],

       "nodes":     [
                      {
                         "id": "1041",
                         "address":"10.1.1.1",
                         "port": "80",
                         "condition":"ENABLED",
                         "status":"ONLINE"
                       },
                       {
                         "id": "1411",
                         "address":"10.1.1.2",
                         "port": "80",
                         "condition":"ENABLED",
                         "status":"ONLINE"
                       }
                     ],
       "sessionPersistence":{
                              "persistenceType":"HTTP_COOKIE"
                            },
       "connectionThrottle":{
                              "maxRequestRate": "50",
                              "rateInterval": "60"
                            }
}

创建负载均衡器

动词	URI	描述
POST	/loadbalancers	根据请求定义的配置创建一个新的负载均衡器。

正常响应代码: 202

错误响应代码：loadbalancerFault (500), serviceUnavailable (503), unauthorized (401),badRequest (400), overLimit (413)

此操作根据请求对象中定义的配置配置一个新的负载均衡器。在验证请求并开始配置过程后，将返回一个响应对象。该对象将包含一个唯一的标识符和请求的状态。

如果返回的状态设置为“BUILD”，则使用负载均衡器的标识符，调用者可以通过对 loadbalancers/loadbalancerid 执行 GET 操作来检查创建操作的进度。当返回的负载均衡器状态更改为“ACTIVE”时，负载均衡器已成功配置并投入运行。

此操作的调用者必须指定负载均衡器的以下至少属性

name
至少一个节点

如果由于数据不足或无效而无法满足请求，将返回 HTTP 400（错误请求）错误响应，其中响应主体包含有关故障性质的信息。验证过程中的故障无法恢复，需要调用者更正故障原因并再次发布请求。

#!wiki caution
Note

By default the system will create a loadbalancer with protocol set to HTTP, port set to 80 (or 443 if protocol is HTTPS), and assign a public IPV6 address to the loadbalancer. The default algorithm used is set to ROUND_ROBIN.

#!wiki caution
Note

A load balancer's name has a max length that can be queried when querying limits.

用户可以通过简单地在请求中提供额外的元素或属性，在创建时配置负载均衡器支持的所有已记录功能。本文档概述了负载均衡服务支持的所有功能。

#!wiki caution
Note

Users may request either an IPv4 or IPV6 address by specifying the version in the create request. For example to request a public IPV6 virtual IP address for the load balancer, use the following virtualIP element in the request:

<virtualIp type="PUBLIC" ipVersion="IPV6"/>

If the version attribute is not specified, then an IPv6 IP address is allocated by default.

示例 4.5. 创建负载均衡器（必需属性）请求：XML

#!highlight xml numbers=disable
<loadBalancer xmlns="https://docs.openstack.org/atlas/api/v1.1"
              name="a-new-loadbalancer">
      <nodes>
      <node address="10.1.1.1" port="80" />
      <node address="10.1.1.2" port="81" />
    </nodes>
</loadBalancer>

示例 4.6. 创建负载均衡器（必需属性）请求：JSON

#!highlight javascript numbers=disable
{
    "name": "a-new-loadbalancer",
    "nodes":      [
                    {
                      "address": "10.1.1.1",
                      "port": "80"
                    },
                    {
                      "address": "10.1.1.2",
                      "port": "81"
                    }
                   ]
}

如果您至少有一个负载均衡器，您可以通过发出 POST 请求并提供虚拟 IP ID 而不是类型来创建后续共享单个虚拟 IP 的负载均衡器。此外，如果您希望使用一个 IP 地址来负载平衡不安全和安全的协议，此功能非常理想。例如，此方法可以使您使用相同的负载均衡器配置来支持 HTTP 和 HTTPS 负载均衡器。

#!wiki caution
Note

Load balancers sharing a virtual IP must utilize a unique port.

示例 4.7. 创建负载均衡器（必需属性与共享 IP）请求：XML

#!hightlight xml
<loadBalancer xmlns="https://docs.openstack.org/atlas/api/v1.1"
              name="a-new-loadbalancer" port="83" protocol="HTTP">
      <virtualIps>
         <virtualIp id="39"/>
      </virtualIps>

      <nodes>
         <node address="10.1.1.1" port="80" condition="ENABLED" />
      </nodes>
</loadBalancer>

示例 4.8. 创建负载均衡器（必需属性与共享 IP）请求：JSON

#!highlight javascript numbers=disable
{
   "name":"a-new-loadbalancer",
   "port":"83",
   "protocol":"HTTP",
   "virtualIps": [
                   {
                      "id":"39"
                   }
                 ],
   "nodes":      [
                   {
                      "address":"10.1.1.1",
                      "port":"80",
                      "condition":"ENABLED"
                   }
                 ]
}

示例 4.9. 创建负载均衡器（必需属性与共享 IP）响应：XML

#!highlight xml numbers=disable
<loadBalancer xmlns="https://docs.openstack.org/atlas/api/v1.1"
              id="144" name="a-new-loadbalancer" algorithm="ROUND_ROBIN"
              protocol="HTTP"
              port="83"
              status="BUILD"
              created="2011-02-08T21:19:55Z"
              updated="2011-02-08T21:19:55Z" >

    <virtualIps>
       <virtualIp id="39" address="3ffe:1900:4545:3:200:f8ff:fe21:67cf" ipVersion="IPV6" type="PUBLIC" />
    </virtualIps>

    <nodes>
       <node id="653" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" />
    </nodes>
</loadBalancer>

示例 4.10. 创建负载均衡器（必需属性与共享 IP）响应：JSON

#!highlight javascript numbers=disable
{
    "name": "a-new-loadbalancer",
    "id": "144",
    "protocol": "HTTP",
    "port": "83",
    "algorithm": "ROUND_ROBIN",
    "status": "BUILD",
    "created": "2011-04-13T14:18:07Z",
    "updated":"2011-04-13T14:18:07Z",
    "virtualIps": [
                    {
                      "address": "3ffe:1900:4545:3:200:f8ff:fe21:67cf",
                      "id": "39",
                      "type": "PUBLIC",
                      "ipVersion": "IPV6"
                    }
                  ],
    "nodes":      [
                    {
                      "address": "10.1.1.1",
                      "id": "653",
                      "port": "80",
                      "status": "ONLINE",
                      "condition": "ENABLED"
                    }
                  ]
}

更新负载均衡器属性

动词	URI	描述
PUT	/loadbalancers/loadBalancerId	更新负载均衡器的属性。

正常响应代码: 202

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

此操作更新指定负载均衡器的属性。在成功验证请求后，服务将返回 202（已接受）响应代码。调用者应检查负载均衡器状态是否为 ACTIVE，以确认更新已生效。如果负载均衡器状态为“PENDING_UPDATE”，则调用者可以使用其 ID（使用 GET 操作）轮询负载均衡器，以等待更改应用并负载均衡器返回到 ACTIVE 状态。

此操作允许调用者更改以下一个或多个属性

name
algorithm

此操作不返回响应主体。

#!wiki caution
Note

The load balancer's ID, status, port and protocol are immutable attributes and cannot be modified by the caller. Supplying an unsupported attribute will result in a 400 (badRequest) fault.

示例 4.11. 更新负载均衡器属性请求：XML

#!highlight xml numbers=disable
<loadBalancer xmlns="https://docs.openstack.org/atlas/api/v1.1"
              name="newname-loadbalancer" algorithm="LEAST_CONNECTIONS" />

示例 4.12. 更新负载均衡器属性请求：JSON

#!highlight javascript numbers=disable
{
   "name": "newname-loadbalancer",
   "algorithm": "LEAST_CONNECTIONS"
}

表 4.1. 负载均衡器状态

姓名

ACTIVE

BUILD

待更新

待删除

DELETED

SUSPENDED

错误

请注意，状态为 SUSPENDED 的负载均衡器未投入运行，对其的流量将被拒绝，并且不会转发到后端节点。

删除负载均衡器

动词	URI	描述
DELETE	/loadbalancers/loadBalancerId	从帐户中删除负载均衡器。

正常响应代码: 202

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

删除负载均衡器功能会删除指定的负载均衡器及其关联的配置，并从帐户中删除。所有配置数据将被立即清除，并且无法恢复。

此操作不需要请求主体。

此操作不返回响应主体。

删除的负载均衡器在删除后几天内仍会显示在列出帐户的负载均衡器时。其状态更改为 DELETED。DELETED 负载均衡器的更新日期反映其删除的时间/日期。

节点

负载均衡器定义的节点负责服务通过负载均衡器的虚拟 IP 接收到的请求。默认情况下，负载均衡器采用基本健康检查，以确保节点在其定义的端口上正在侦听。在添加时以及根据负载均衡器健康检查配置定义的定期间隔，会检查节点。如果后端节点未在其端口上侦听，或者不满足负载均衡器的定义活动健康检查的条件，则负载均衡器将不会转发连接或请求到它，并且其状态将显示为 OFFLINE。只有状态为 ONLINE 的节点才能接收并能够服务来自负载均衡器的流量。

节点的状态可以通过被动或主动健康监控来确定。

调用者可以使用节点元素的 weight 属性为节点分配相关的权重。

节点的权重决定了与其他负载均衡器节点相比，它服务请求或连接的比例。例如，如果节点 A 的权重为 2，而节点 B 的权重为 1，则负载均衡器会将两倍于节点 B 的请求转发到节点 A。如果未指定 weight 属性，则节点的权重隐式设置为“1”。

列出节点

动词	URI	描述
GET	/loadbalancers/loadBalancerId/nodes	列出为负载均衡器配置的节点。

列出负载均衡器的所有节点。

正常响应代码: 200

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

此操作不需要请求主体。

示例 4.13. 列出节点响应：XML

#!highlight xml numbers=disable
<nodes>
   <node id="410" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" />
   <node id="236" address="10.1.1.2" port="80" condition="ENABLED" status="ONLINE" />
   <node id="2815" address="10.1.1.3" port="83" condition="DISABLED" status="OFFLINE" />
</nodes>

示例 4.14. 列出节点响应：JSON

#!highlight javascript numbers=disable
{
  "nodes" : [
              {
                "id":"410",
                "address":"10.1.1.1",
                "port":"80",
                "condition":"ENABLED",
                "status":"ONLINE"
              },
              {
                "id":"236",
                "address":"10.1.1.2",
                "port":"80",
                "condition":"ENABLED",
                "status":"ONLINE"
              },
              {
                "id":"2815",
                "address":"10.1.1.3",
                "port":"83",
                "condition":"DISABLED",
                "status":"OFFLINE"
              },
            ]
}

检索节点

动词	URI	描述
GET	/loadbalancers/loadBalancerId/nodes/nodeId	检索负载均衡器 loadbalancerId 的节点 nodeid 的配置。

此操作检索节点的配置。

正常响应代码: 200

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

此操作不需要请求主体。

示例 4.15. 检索节点配置响应：XML

#!highlight xml numbers=disable
<node id="236" address="10.1.1.2" port="80" condition="ENABLED" status="ONLINE" />

示例 4.16. 检索节点响应：JSON

#!highlight javascript numbers=disable
{
  "id":"236",
  "address":"10.1.1.2",
  "port":"80",
  "condition":"ENABLED",
  "status":"ONLINE"
}

添加节点

动词	URI	描述
POST	/loadbalancers/loadBalancerId/nodes	将新节点添加到负载均衡器。

正常响应代码: 202

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

添加节点时，会为其分配一个唯一的标识符，可用于变异操作，例如更改节点的条件或权重，或从负载均衡器中删除节点。

每个负载均衡器都双向连接到公共互联网和内部网络；因此，节点可以是内部专用地址或公共互联网上的地址。

#!wiki caution
Note:

When a node is added to a load balancer, it is enabled by default.

示例 4.17. 添加节点请求：XML

#!highlight xml numbers=disable
<nodes xmlns="https://docs.openstack.org/atlas/api/v1.1">
  <node address="10.1.1.1" port="80" />
  <node address="10.2.2.1" port="80" weight="2" />
  <node address="10.2.2.2" port="88" condition="DISABLED" weight="2" />
</nodes>

示例 4.18. 添加节点请求：JSON

#!highlight javascript numbers=disable
{
  "nodes": [
             {
               "address": "10.1.1.1",
               "port": "80"
             },
             {
               "address": "10.2.2.1",
               "port": "80",
               "weight": "2"
             },
             {
               "address": "10.2.2.2",
               "port": "88",
               "condition": "DISABLED",
               "weight": "2"
             }
           ]
}

示例 4.19. 添加节点响应：XML

#!highlight xml numbers=disable
<nodes xmlns="https://docs.openstack.org/atlas/api/v1.1">
 <node id="7298" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" />
 <node id="293" address="10.2.2.1" port="80" weight="2" condition="ENABLED" status="OFFLINE" />
 <node id="183" address="10.2.2.2" port="88" weight="2" condition="DISABLED" status="OFFLINE" />
</nodes>

示例 4.20. 添加节点响应：JSON

#!highlight javascript numbers=disable
{
  "nodes": [
             {
               "id": "7298",
               "address": "10.1.1.1",
               "port": "80",
               "condition": "ENABLED",
               "status": "ONLINE"
             },
             {
               "id": "293",
               "address": "10.2.2.1",
               "port": "80",
               "weight": "2",
               "condition": "ENABLED",
               "status": "OFFLINE"
             },
             {
               "id": "183",
               "address": "10.2.2.4",
               "port": "88",
               "weight": "2",
               "condition": "DISABLED",
               "status": "OFFLINE"
             }
           ]
}

修改节点

动词	URI	描述
PUT	/loadbalancers/loadBalancerId/nodes/nodeId	修改负载均衡器上的节点配置。

正常响应代码: 202

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

此操作不返回响应主体。

#!wiki caution
Note

The node's IP and port are immutable attributes and cannot be modified with a PUT
request. Supplying an unsupported attribute will result in a 400 (badRequest) fault. A load balancer supports a maximum number of nodes. The maximum number of nodes per loadbalancer is returned when querying the limits of the LB service.

负载均衡器中的每个节点都处于启用或禁用状态，这决定了它在负载均衡器中的作用。当节点具有 condition="ENABLED" 时，允许该节点接受新的连接。其状态最终将变为 ONLINE，以反映此配置。当节点具有 condition="DISABLED" 时，无论会话持久性配置如何，都不允许该节点接受任何新的连接。与该节点的现有连接将被强制终止。配置成功应用后，节点的状态将更改为 OFFLINE。

示例 4.21. 禁用节点请求：XML

#!highlight xml numbers=disable
<node condition="DISABLED" />

示例 4.22. 禁用节点请求：JSON

#!highlight javascript numbers=disable
{
  "condition": "DISABLED"
}

即使节点配置为 condition="ENABLED"，如果节点或其负载均衡器存在配置或操作错误，其状态仍可能保持为 OFFLINE。

删除节点

动词	URI	描述
DELETE	/loadbalancers/loadBalancerId/nodes/nodeId	从负载均衡器中删除节点。

正常响应代码: 200, 202

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

此操作不需要请求主体。

此操作不返回响应主体。

#!wiki caution
Note

A load balancer must have at least one node. Attempting to remove the last node of a loadbalancer will result in a badRequest (400) error.

虚拟 IP

虚拟 IP (VIP) 使客户端可以访问负载均衡器。负载均衡服务支持可在公共互联网上路由的公共 VIP，或仅可在负载均衡器所在的区域内路由的专用地址。

表 4.3. 虚拟 IP 类型

姓名

PUBLIC

INTERNAL

列出虚拟 IP

动词	URI	描述
GET	/loadbalancers/loadBalancerId/virtualips	列出与负载均衡器关联的所有虚拟 IP。

正常响应代码：200

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

此操作列出负载均衡器的所有虚拟 IP 地址。

此请求不需要请求体。

#!wiki caution
Note

The maximum number of VIPs that can be configured when creating a load balancer can be discovered by querying the limits of the LB service.

示例 4.23. 列出虚拟 IP 响应：XML

#!highlight xml numbers=disable
<virtualIps xmlns="https://docs.openstack.org/atlas/api/v1.1">
  <virtualIp id="1021" address="206.10.10.210" type="PUBLIC" ipVersion="IPV4"/>
</virtualIps>

示例 4.24. 列出虚拟 IP 响应：JSON

#!highlight javascript numbers=disable
{
  "virtualIps": [
                 {
                   "id": "1021",
                   "address": "206.10.10.210",
                   "type": "PUBLIC",
                   "ipVersion": "IPV4"
                 }
                ]
}

使用情况报告

列出使用情况

姓名	URI	描述
GET	/loadbalancers/loadBalancerId/usage	列出当前和历史使用情况。

正常响应代码：200

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

此操作不需要请求主体。

负载均衡器使用情况报告提供一组使用情况计数器。此列表将至少包含 transferBytesIn 和 transferBytesOut 使用情况计数器，它们分别表示从客户端请求接收到的负载均衡器的字节流量，以及作为对客户端的响应从节点发送的流量。

示例 4.25. 报告负载均衡器使用情况响应：XML

#!highlight xml numbers=disable
<loadBalancerUsageRecords xmlns="https://docs.openstack.org/atlas/api/v1.1">
   <loadBalancerUsageRecord  id="394"  transferBytesIn="2819204"
                             transferBytesOut="84923069" />
   <loadBalancerUsageRecord  id="473" transferBytesIn="0" transferBytesOut="0" />
</loadBalancerUsageRecords>

示例 4.26. 报告负载均衡器使用情况响应：JSON

#!highlight javascript numbers=disable
{
  "loadBalancerUsageRecords": [
                                {
                                  "id": "394",
                                  "transferBytesIn": "2819204",
                                  "transferBytesOut": "84923069"
                                },
                                {
                                  "id": "473",
                                  "transferBytesIn": "0",
                                  "transferBytesOut": "0"
                                }
                              ]
}

监视器

动词	URI	描述
GET	/loadbalancers/loadBalancerId/healthmonitor	检索健康监视器配置（如果存在）。
PUT	/loadbalancers/loadBalancerId/healthmonitor	更新健康监视器设置。
DELETE	/loadbalancers/loadBalancerId/healthmonitor	移除健康监控。

正常响应代码: 200, 202

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

除了默认的被动监控之外，负载均衡服务还包括主动健康监控操作，该操作会定期检查您的后端节点，以确保它们正确响应。

主动健康监控提供 3 种类型的健康监控。调用方可以在负载均衡器上配置一个健康监控。

健康监控具有一个 type 属性，用于指示它是 3 种类型中的哪一种。此规范中提供的 3 种类型如下所述。

表 4.4. 健康监控类型

姓名

CONNECT

HTTP

HTTPS

监视器 CONNECT

监视器连接到每个节点在其定义的端口上，以确保节点正在正确侦听。

CONNECT 监视器是最基本的健康检查类型，不执行后处理或协议特定的健康检查。它包括几个可配置的属性

delay：定期调用监视器之间的最小时间（秒）。
timeout：监视器建立到节点的连接之前超时所用的最大秒数。该值必须小于延迟值。
attemptsBeforeDeactivation：在从轮换中删除节点之前允许的监视器失败次数。必须是 1 到 10 之间的数字。

示例 4.27. 监视器 CONNECT 请求：XML

#!highlight xml numbers=disable
<healthMonitor xmlns="https://docs.openstack.org/atlas/api/v1.1"
               type="CONNECT" delay="20" timeout="10"
               attemptsBeforeDeactivation="3" />

示例 4.28. 监视器 CONNECT 请求：JSON

#!highlight javascript numbers=disable
{
  "type": "CONNECT",
  "delay": "20",
  "timeout": "10",
  "attemptsBeforeDeactivation": "3"
}

示例 4.29. 监视器连接响应：XML

#!highlight xml numbers=disable
<healthMonitor xmlns="https://docs.openstack.org/atlas/api/v1.1"
               type="CONNECT" delay="10" timeout="10"
               attemptsBeforeDeactivation="3" />

示例 4.30. 监视器连接响应：JSON

#!highlight javascript numbers=disable
{
  "type": "CONNECT",
  "delay": "20",
  "timeout": "10",
  "attemptsBeforeDeactivation": "3"
}

监视器 HTTP 和 HTTPS

HTTP 和 HTTPS 监视器比 CONNECT 监视器更智能。它能够处理 HTTP 或 HTTPS 响应以确定节点的状况。它支持与 CONNECT 监视器相同的基本属性，并包括用于评估监视器探测的 HTTP 响应的 path 属性。

path：监视器在 HTTP 请求中使用的 HTTP 路径。这必须以 /（正斜杠）开头。监视器期望从节点收到 HTTP 状态代码为 200 的响应。

示例 4.31. 监视器 HTTP 响应：XML

#!highlight xml numbers=disable
<healthMonitor xmlns="https://docs.openstack.org/atlas/api/v1.1"
               type="HTTP" delay="10" timeout="3" attemptsBeforeDeactivation="2"
               path="/"
/>

示例 4.32. 监视器 HTTPS 响应：XML

#!highlight xml numbers=disable
<healthMonitor xmlns="https://docs.openstack.org/atlas/api/v1.1"
               type="HTTPS" delay="10" timeout="3"
               attemptsBeforeDeactivation="3"
               path="/healthcheck"
/>

示例 4.33. 监视器 HTTPS 响应：JSON

#!highlight javascript numbers=disable
{
   "type": "HTTPS",
   "delay": "10",
   "timeout": "3",
   "attemptsBeforeDeactivation": "3",
   "path": "/healthcheck"
}

如果负载均衡器没有健康监控配置，则 LB 服务在检索（GET 请求）健康监控配置时将返回一个空响应。

会议

管理会话持久性

动词	URI	描述
GET	/loadbalancers/loadBalancerId/sessionpersistence	列出会话持久性配置。
PUT	/loadbalancers/loadBalancerId/sessionpersistence	启用会话持久性。
DELETE	/loadbalancers/loadBalancerId/sessionpersistence	禁用会话持久性。

正常响应代码: 200, 202

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

会话持久性是负载均衡服务的一项功能，它强制客户端的多个请求被定向到同一节点。这在许多不固有地在后端服务器之间共享应用程序状态的 Web 应用程序中很常见。

表 4.5. 会话持久性模式

姓名

HTTP_COOKIE

示例 4.34. 列出会话持久性配置响应：XML

#!highlight xml numbers=disable
<sessionPersistence xmlns="https://docs.openstack.org/atlas/api/v1.1"
                    persistenceType="HTTP_COOKIE" />

示例 4.35. 列出会话持久性配置响应：JSON

#!highlight javascript numbers=disable
{
   "persistenceType":"HTTP_COOKIE"
}

示例 4.36. 设置会话持久性类型请求：XML

#!highlight xml numbers=disable
<sessionPersistence xmlns="https://docs.openstack.org/atlas/api/v1.1"
                    persistenceType="HTTP_COOKIE" />

示例 4.37. 设置会话持久性类型请求：JSON

#!highlight javascript numbers=disable
{
    "persistenceType":"HTTP_COOKIE"
}

连接

限制连接

动词	URI	描述
GET	/loadbalancers/loadBalancerId/connectionthrottle	列出连接限制配置。
PUT	/loadbalancers/loadBalancerId/connectionthrottle	更新限制配置。
DELETE	/loadbalancers/loadBalancerId/connectionthrottle	删除连接限制配置。

正常响应代码: 200, 202

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

连接限制功能对每个客户端 IP 地址的连接数量施加限制，以帮助缓解对您应用程序的恶意或滥用流量。可以根据您网站的流量模式配置以下属性。

maxRequestRate：在定义的 rateInterval 中允许来自单个 IP 地址的最大 HTTP 请求（或 TCP 连接）数量。将值设置为 0 允许无限的连接或请求速率。
rateInterval：评估 maxRequestRate 的频率（秒）。例如，maxRequestRate 为 30，rateInterval 为 60，将允许来自单个 IP 地址每分钟最多 30 个 HTTP 请求或 TCP 连接。此属性的值必须在 1 到 3600 之间。

#!wiki caution
Note

When the rate is exceeded, the load balancer returns a serviceUnavailable (503) error to new requests for HTTP/HTTPS loadbalancers. For TCP loadbalancers, new connections are refused.

示例 4.42. 列出连接限制配置响应：XML

#!highlight xml numbers=disable
<connectionThrottle xmlns="https://docs.openstack.org/atlas/api/v1.1"
                    maxRequestRate="50" rateInterval="60" />

示例 4.43. 列出连接限制配置响应：JSON

#!highlight javascript numbers=disable
{
    "maxRequestRate": "50",
    "rateInterval": "60"
}

示例 4.44. 更新连接限制配置请求：XML

#!highlight xml numbers=disable
<connectionThrottle xmlns="https://docs.openstack.org/atlas/api/v1.1"
                    maxRequestRate="40" />

示例 4.45. 更新连接限制配置请求：JSON

#!highlight javascript numbers=disable
{
   "maxRequestRate": "40"
}

协议

列出负载均衡协议

动词	URI	描述
GET	/protocols	列出所有受支持的负载均衡协议。

正常响应代码: 200

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

此操作不需要请求主体。

所有负载均衡器必须配置为其负载均衡的服务协议。协议选择应基于后端节点的协议。当前规范支持 HTTP、HTTPS 和 TCP 服务。

在配置 HTTP 或 HTTPS 负载均衡器时，除非另有说明，否则将选择给定协议的默认端口。

示例 4.46. 列出负载均衡协议响应：XML

#!highlight xml numbers=disable
<protocols xmlns="https://docs.openstack.org/atlas/api/v1.1">
     <protocol name="HTTP" port="80" />
     <protocol name="HTTPS" port="443" />
     <protocol name="TCP" port="*" />
</protocols>

示例 4.47. 列出负载均衡协议响应：JSON

#!highlight javascript numbers=disable
{
 "protocols": [
               {
                 "name": "HTTP",
                 "port": "80"
               },
               {
                 "name": "HTTPS",
                 "port": "443"
               },
               {
                 "name": "TCP",
                 "port": "*"
               }
              ]
}

算法

所有负载均衡器都使用一种算法来定义如何在后端节点之间定向流量。新创建的负载均衡器的默认算法是 ROUND_ROBIN，可以在创建时或在负载均衡器最初配置后更改。

算法名称在负载均衡 API 的主要版本中必须保持不变，尽管可以在此 API 的给定主要版本中创建具有唯一算法名称的新算法。

表 4.6. 负载均衡算法

姓名

LEAST_CONNECTIONS

ROUND_ROBIN

列出负载均衡算法

动词	URI	描述
GET	/algorithms	列出所有支持的负载均衡算法。

正常响应代码: 200

错误响应代码：loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

此操作不需要请求主体。

示例 4.48. 列出负载均衡算法响应：XML

#!highlight xml numbers=disable
<algorithms xmlns="https://docs.openstack.org/atlas/api/v1.1">
   <algorithm name="ROUND_ROBIN" />
   <algorithm name="LEAST_CONNECTIONS" />
</algorithms>

示例 4.49. 列出负载均衡算法响应：JSON

#!highlight javascript numbers=disable
{
   "algorithms": [
                  {
                    "name": "ROUND_ROBIN"
                  },
                  {
                    "name": "LEAST_CONNECTIONS"
                  }
                 ]
}

API 扩展

此 API 规范的实现可以根据需要使用扩展来增强此核心 API（例如，支持新的 LB 算法或协议）。

但是，所有编写到此核心规范的客户端应用程序都必须由扩展的实现支持。因此，使用此 API 的应用程序不应接收到未在此规范中指定的数据负载或值，也不应需要在请求中指定未在此规范中描述的额外信息。

有关如何在 OpenStack 服务中开发和使用扩展 API 的详细描述，请参阅 OpenStack 网站上的 OpenStack Compute API 1.1 文档。

Atlas-LB

OpenStack LoadBalancers API 1.1

目录

概述

预期读者

文档变更历史

修订日期 变更摘要

概念

负载均衡器

虚拟 IP

节点

健康监控

被动健康监控

主动健康监控

会话持久性

通用 API 信息

身份验证

服务访问/端点

请求/响应类型

内容压缩

持久连接

分页集合

限制

速率限制

绝对限制

以编程方式确定限制

错误

serviceFault

badRequest

immutableEntity

itemNotFound

loadBalancerFault

outOfVirtualIps

overLimit

serviceUnavailable

unauthorized

unprocessableEntity

API 操作

负载均衡器

列出负载均衡器

列出负载均衡器详情

创建负载均衡器

更新负载均衡器属性

删除负载均衡器

节点

列出节点

检索节点

添加节点

修改节点

删除节点

虚拟 IP

列出虚拟 IP

使用情况报告

列出使用情况

监视器

监视器 CONNECT

监视器 HTTP 和 HTTPS

会议

管理会话持久性

连接

限制连接

协议

列出负载均衡协议

算法

列出负载均衡算法

API 扩展

修订日期变更摘要