Merge pull request #1883 from yousong/feature/yousong-docs-lbcluster

docs: 添加lbcluster, lbagent的API描述
2026-09-24 16:03:43 +08:00 · 2019-07-24 16:53:05 +08:00
parent 2c9e2bb850 ffbc73f086
commit 2ee947e6ec
9 changed files with 413 additions and 3 deletions
@@ -214,6 +214,18 @@ paths:
  /loadbalancerbackends/{loadbalancerbackendId}:
    $ref: "./loadbalancer/loadbalancerbackend.yaml"

+  /loadbalancerclusters:
+    $ref: "./loadbalancer/loadbalancerclusters.yaml"
+  /loadbalancerclusters/{loadbalancerClusterId}:
+    $ref: "./loadbalancer/loadbalancercluster.yaml"
+
+  /loadbalanceragents:
+    $ref: "./loadbalancer/loadbalanceragents.yaml"
+  /loadbalanceragents/{loadbalancerAgentId}:
+    $ref: "./loadbalancer/loadbalanceragent.yaml"
+  /loadbalanceragents/{loadbalancerAgentId}/params-patch:
+    $ref: "./loadbalancer/loadbalanceragent-params-patch.yaml"
+
  /identity_providers:
    $ref: "./identity/identity_providers.yaml"
  /identity_providers/{idp_id}:
@@ -6,7 +6,7 @@ get:
    200:
      description: 实例信息
      schema:
-        $ref: "../schemas/loadbalancer.yaml#/LoadbalancerCachedAclListResponse"
+        $ref: "../schemas/loadbalancer.yaml#/LoadbalancerResponse"
  tags:
    - loadbalancers
 delete:
@@ -0,0 +1,15 @@
+post:
+  summary: 更改loadbalancer转发实例的守护进程的参数
+  parameters:
+    - $ref: "../parameters/loadbalancer.yaml#/loadbalancerAgentId"
+    - name: params
+      in: body
+      schema:
+        $ref: "../schemas/loadbalancer.yaml#/LoadbalancerAgentParams"
+  responses:
+    200:
+      description: 变更后的转发实例信息
+      schema:
+        $ref: "../schemas/loadbalancer.yaml#/LoadbalancerAgentResponse"
+  tags:
+    - loadbalanceragents
@@ -0,0 +1,46 @@
+get:
+  summary: 获取指定loadbalancer转发实例信息
+  parameters:
+    - $ref: "../parameters/loadbalancer.yaml#/loadbalancerAgentId"
+  responses:
+    200:
+      description: 转发实例信息
+      schema:
+        $ref: "../schemas/loadbalancer.yaml#/LoadbalancerAgentResponse"
+  tags:
+    - loadbalanceragents
+put:
+  summary: 更新loadbalancer转发实例自身参数
+  parameters:
+    - $ref: "../parameters/loadbalancer.yaml#/loadbalancerAgentId"
+    - name: loadbalanceragent
+      in: body
+      schema:
+        type: object
+        properties:
+          hb_timeout:
+            description: 转发实例心跳超时时间
+            in: body
+            type: integer
+            minimum: 1
+            example: 3600
+  responses:
+    200:
+      description: 转发实例信息
+      schema:
+        $ref: "../schemas/loadbalancer.yaml#/LoadbalancerAgentResponse"
+  tags:
+    - loadbalanceragents
+delete:
+  summary: 删除指定loadbalancer转发实例
+  description: |
+    删除操作仅涉及数据库记录，实际节点的下线计划需要管理员计划实施
+  parameters:
+    - $ref: "../parameters/loadbalancer.yaml#/loadbalancerId"
+  responses:
+    200:
+      description: 被删除转发实例的信息
+      schema:
+        $ref: "../schemas/loadbalancer.yaml#/LoadbalancerAgentResponse"
+  tags:
+    - loadbalanceragents
@@ -0,0 +1,25 @@
+get:
+  summary: 按指定条件列出loadbalancer转发实例
+  parameters:
+    - $ref: "../parameters/loadbalancer.yaml#/cluster"
+  responses:
+    200:
+      description: 实例列表信息
+      schema:
+        $ref: "../schemas/loadbalancer.yaml#/LoadbalancerAgentListResponse"
+  tags:
+    - loadbalanceragents
+post:
+  summary: 创建loadbalancer转发实例
+  parameters:
+    - name: loadbalanceragent
+      in: body
+      schema:
+        $ref: "../schemas/loadbalancer.yaml#/LoadbalancerAgentCreateRequest"
+  responses:
+    200:
+      description: 新创建的实例信息
+      schema:
+        $ref: "../schemas/loadbalancer.yaml#/LoadbalancerAgentResponse"
+  tags:
+    - loadbalanceragents
@@ -0,0 +1,26 @@
+get:
+  summary: 获取指定loadbalancer集群信息
+  parameters:
+    - $ref: "../parameters/loadbalancer.yaml#/loadbalancerClusterId"
+  responses:
+    200:
+      description: 集群信息
+      schema:
+        $ref: "../schemas/loadbalancer.yaml#/LoadbalancerClusterResponse"
+  tags:
+    - loadbalancerclusters
+delete:
+  summary: 删除指定loadbalancer集群
+  description: |
+    该操作会同时删除指定集群下的LoadbalancerAgent对象。
+
+    该操作仅删除数据库记录，并不对实际的转发节点进行配置变更，转发节点的下线需要由管理员另外执行。
+  parameters:
+    - $ref: "../parameters/loadbalancer.yaml#/loadbalancerClusterId"
+  responses:
+    200:
+      description: 被删除实例的信息
+      schema:
+        $ref: "../schemas/loadbalancer.yaml#/LoadbalancerClusterResponse"
+  tags:
+    - loadbalancerclusters
@@ -0,0 +1,23 @@
+get:
+  summary: 按指定条件列出loadbalancer集群
+  responses:
+    200:
+      description: Loadbalancer集群组列表
+      schema:
+        $ref: "../schemas/loadbalancer.yaml#/LoadbalancerClusterListResponse"
+  tags:
+    - loadbalancerclusters
+post:
+  summary: 创建loadbalancer集群
+  parameters:
+    - name: loadbalancercluster
+      in: body
+      schema:
+        $ref: "../schemas/loadbalancer.yaml#/LoadbalancerClusterCreateRequest"
+  responses:
+    200:
+      description: 新创建的后端服务器组信息
+      schema:
+        $ref: "../schemas/loadbalancer.yaml#/LoadbalancerClusterResponse"
+  tags:
+    - loadbalancerclusters
@@ -31,6 +31,18 @@ loadbalancercachedcertificateId:
  in: path
  required: true 
  description: 证书缓存id
+loadbalancerClusterId:
+  name: loadbalancerClusterId
+  type: string
+  in: path
+  required: true
+  description: Loadbalancer集群id
+loadbalancerAgentId:
+  name: loadbalancerAgentId
+  type: string
+  in: path
+  required: true
+  description: Loadbalancer转发实例id


 address:
@@ -76,4 +88,10 @@ certificate_id:
  name: certificate_id
  in: query
  type: string
-  description: 指定loadbalaner本地证id  
+  description: 指定loadbalaner本地证书id
+
+cluster:
+  name: cluster
+  in: query
+  type: string
+  description: 指定loadbalancer集群id
@@ -310,4 +310,249 @@ LoadbalancerCachedCertificateListResponse:
    cached_loadbalancercertificates:
      type: array
      items:
-        $ref: "#/LoadbalancerCachedCertificateResponse"        
+        $ref: "#/LoadbalancerCachedCertificateResponse"
+
+LoadbalancerCluster:
+  type: object
+  description: Loadbalancer集群实例
+  properties:
+    id:
+      type: string
+      description: 实例uuid
+      readOnly: true
+    zone_id:
+      type: string
+      description: 集群所在的zone uuid
+      readOnly: true
+
+LoadbalancerClusterCreateRequest:
+  type: object
+  properties:
+    loadbalancercluster:
+      type: object
+      required:
+        - zone
+      properties:
+        zone:
+          type: string
+          description: 指定集群所属的zone uuid
+LoadbalancerClusterListResponse:
+  type: object
+  properties:
+    loadbalancerclusters:
+      type: array
+      items:
+        $ref: '#/LoadbalancerCluster'
+LoadbalancerClusterResponse:
+  type: object
+  properties:
+    loadbalancercluster:
+      type: object
+      $ref: '#/LoadbalancerCluster'
+
+
+LoadbalancerAgent:
+  type: object
+  description: Loadbalancer转发实例
+  properties:
+    id:
+      type: string
+      description: 实例uuid
+      readOnly: true
+    cluster_id:
+      type: string
+      description: 转发实例所属的集群id
+      readOnly: true
+    ha_state:
+      type: string
+      description: 转发实例的主备状态
+      readOnly: true
+      enum:
+        - MASTER
+        - BACKUP
+        - UNKNOWN
+    ha_last_seen:
+      type: string
+      format: date-time
+      description: 转发实例上次心跳UTC时间
+      readOnly: true
+      example: "2019-07-24T06:38:07.000000Z"
+    ha_timeout:
+      type: integer
+      description: |
+        转发实例心跳超时时间
+
+        若上次心跳时间距离当前时间超过此值，则认为实例已离线，进入非活跃状态
+      unit: seconds
+    ip:
+      type: string
+      description: 转发实例自上报的IP地址
+      readOnly: true
+    params:
+      $ref: '#/LoadbalancerAgentParams'
+    loadbalancer_acls:
+      type: string
+      format: date-time
+      description: 转发实例当前同步到的最新LB访问控制对象时戳
+    loadbalancer_backend_groups:
+      type: string
+      format: date-time
+      description: 转发实例当前同步到的最新LB后端服务器组对象时戳
+    loadbalancer_backends:
+      type: string
+      format: date-time
+      description: 转发实例当前同步到的最新LB后端对象时戳
+    loadbalancer_certificates:
+      type: string
+      format: date-time
+      description: 转发实例当前同步到的最新LB证书对象时戳
+    loadbalancer_listener_rules:
+      type: string
+      format: date-time
+      description: 转发实例当前同步到的最新LB访问策略对象时戳
+    loadbalancer_listeners:
+      type: string
+      format: date-time
+      description: 转发实例当前同步到的最新LB监听对象时戳
+    loadbalancers:
+      type: string
+      format: date-time
+      description: 转发实例当前同步到的最新LB对象时戳
+
+LoadbalancerAgentParams:
+  type: object
+  properties:
+    vrrp:
+      $ref: '#/LoadbalancerAgentParamsVrrp'
+    haproxy:
+      $ref: '#/LoadbalancerAgentParamsHaproxy'
+    telegraf:
+      $ref: '#/LoadbalancerAgentParamsTelegraf'
+    keepalived_conf_tmpl:
+      type: string
+      description: |
+        以base64编码的KeepAlived配置模板
+
+        创建时可选，服务端会设定默认值
+      example: Z2xvYmFsX2RlZnMgewoJcm91dGVyX2lkIHt7IC5hZ2VudC5pZCB9fQoJI3ZycnBfc3RyaWN0Cgl2cnJwX3NraXBfY2hlY2tfYWR2X2FkZHIKCWVuYWJsZV9zY3JpcHRfc2VjdXJpdHkKfQoKdnJycF9pbnN0YW5jZSBZdW5pb25MQiB7CglpbnRlcmZhY2Uge3sgLnZycnAuaW50ZXJmYWNlIH19Cgl2aXJ0dWFsX3JvdXRlcl9pZCB7eyAudnJycC52aXJ0dWFsX3JvdXRlcl9pZCB9fQoJYXV0aGVudGljYXRpb24gewoJCWF1dGhfdHlwZSBQQVNTCgkJYXV0aF9wYXNzIHt7IC52cnJwLnBhc3MgfX0KCX0KCXt7IGlmIC52cnJwLm5vdGlmeV9zY3JpcHQgLX19IG5vdGlmeSB7eyAudnJycC5ub3RpZnlfc2NyaXB0IH19IHJvb3Qge3stIGVuZCB9fQoJe3sgaWYgLnZycnAudW5pY2FzdF9wZWVyIC19fSB1bmljYXN0X3BlZXIgeyB7ey0gcHJpbnRsbiB9fQoJCXt7LSByYW5nZSAudnJycC51bmljYXN0X3BlZXIgfX0JCXt7IHByaW50bG4gLiB9fSB7ey0gZW5kIH19Cgl9Cgl7ey0gZW5kIH19Cglwcmlvcml0eSB7eyAudnJycC5wcmlvcml0eSB9fQoJYWR2ZXJ0X2ludCB7eyAudnJycC5hZHZlcnRfaW50IH19CglnYXJwX21hc3Rlcl9yZWZyZXNoIHt7IC52cnJwLmdhcnBfbWFzdGVyX3JlZnJlc2ggfX0KCXt7IGlmIC52cnJwLnByZWVtcHQgLX19IHByZWVtcHQge3stIGVsc2UgLX19IG5vcHJlZW1wdCB7ey0gZW5kIH19Cgl2aXJ0dWFsX2lwYWRkcmVzcyB7CgkJe3stIHByaW50ZiAiXG4iIH19CgkJe3stIHJhbmdlIC52cnJwLmFkZHJlc3NlcyB9fQkJe3sgcHJpbnRsbiAuIH19IHt7LSBlbmQgfX0KCQl7ey0gcHJpbnRmICJcdCIgLX19Cgl9Cn0K
+    haproxy_conf_tmpl:
+      type: string
+      description: |
+        以base64编码的HAProxy配置模板
+
+        创建时可选，服务端会设定默认值
+      example: Cmdsb2JhbAoJbWF4Y29ubiA0MDk2MAoJdHVuZS5zc2wuZGVmYXVsdC1kaC1wYXJhbSAyMDQ4Cgl7ey0gcHJpbnRsbiB9fQoJe3stIGlmIC5oYXByb3h5Lmdsb2JhbF9zdGF0c19zb2NrZXQgfX0Je3sgcHJpbnRsbiAuaGFwcm94eS5nbG9iYWxfc3RhdHNfc29ja2V0IH19IHt7LSBlbmQgfX0KCXt7LSBpZiAuaGFwcm94eS5nbG9iYWxfbmJ0aHJlYWQgfX0JbmJ0aHJlYWQge3sgcHJpbnRsbiAuaGFwcm94eS5nbG9iYWxfbmJ0aHJlYWQgfX0ge3stIGVuZCB9fQoJe3stIGlmIC5oYXByb3h5Lmdsb2JhbF9sb2cgfX0Je3sgcHJpbnRsbiAuaGFwcm94eS5nbG9iYWxfbG9nIH19IHt7LSBlbmQgfX0KCmRlZmF1bHRzCgl0aW1lb3V0IGNvbm5lY3QgMTBzCgl0aW1lb3V0IGNsaWVudCA2MHMKCXRpbWVvdXQgc2VydmVyIDYwcwoJdGltZW91dCB0dW5uZWwgMWgKCXt7LSBwcmludGxuIH19Cgl7ey0gaWYgLmhhcHJveHkuZ2xvYmFsX2xvZyB9fQl7eyBwcmludGxuICJsb2cgZ2xvYmFsIiB9fSB7ey0gZW5kIH19Cgl7ey0gaWYgbm90IC5oYXByb3h5LmxvZ19ub3JtYWwgfX0Je3sgcHJpbnRsbiAib3B0aW9uIGRvbnRsb2ctbm9ybWFsIiB9fSB7ey0gZW5kIH19CgpsaXN0ZW4gc3RhdHMKCW1vZGUgaHR0cAoJYmluZCA6Nzc4CglzdGF0cyBlbmFibGUKCXN0YXRzIGhpZGUtdmVyc2lvbgoJc3RhdHMgcmVhbG0gIkhhcHJveHkgU3RhdGlzdGljcyIKCXN0YXRzIGF1dGggWXVuaW9uOkxCU3RhdHMKCXN0YXRzIHVyaSAvCg==
+    telegraf_conf_tmpl:
+      type: string
+      description: |
+        以base64编码的Telegraf配置模板
+
+        创建时可选，服务端会设定默认值
+      example: Cltbb3V0cHV0cy5pbmZsdXhkYl1dCgl1cmxzID0gWyJ7eyAudGVsZWdyYWYuaW5mbHV4X2RiX291dHB1dF91cmwgfX0iXQoJZGF0YWJhc2UgPSAie3sgLnRlbGVncmFmLmluZmx1eF9kYl9vdXRwdXRfbmFtZSB9fSIKCWluc2VjdXJlX3NraXBfdmVyaWZ5ID0gdHJ1ZQoKW1tpbnB1dHMuaGFwcm94eV1dCglpbnRlcnZhbCA9ICJ7eyAudGVsZWdyYWYuaGFwcm94eV9pbnB1dF9pbnRlcnZhbCB9fXMiCglzZXJ2ZXJzID0gWyJ7eyAudGVsZWdyYWYuaGFwcm94eV9pbnB1dF9zdGF0c19zb2NrZXQgfX0iXQoJa2VlcF9maWVsZF9uYW1lcyA9IHRydWUK
+
+LoadbalancerAgentParamsVrrp:
+  type: object
+  description: VRRP参数
+  properties:
+    advert_int:
+      type: integer
+      description: VRRP通告间隔，单位秒
+      mininum: 1
+      example: 1
+    interface:
+      type: string
+      description: VRRP通告发送的网口名
+      example: eth0
+    garp_master_refresh:
+      type: integer
+      description: TODO
+    pass:
+      type: string
+      description: VRRP通告共享密码
+      example: OneCloudLB
+    preempt:
+      type: boolean
+      description: 是否进行抢占式选举
+      example: false
+    priority:
+      type: integer
+      description: VRRP实例优先级
+      mininum: 1
+      maximum: 255
+      example: 110
+    virtual_router_id:
+      type: integer
+      description: VRRP集群ID
+      mininum: 1
+      maximum: 255
+      example: 100
+LoadbalancerAgentParamsHaproxy:
+  type: object
+  description: HAProxy参数
+  properties:
+    global_log:
+      type: string
+      description: HAProxy配置文件global段中关于日志的配置
+      example: "log /dev/log local0 info"
+    global_nbthread:
+      type: integer
+      description: HAProxy配置文件global段中关于线程数的配置
+      example: 1
+      mininum: 1
+      maximum: 64
+    log_http:
+      type: boolean
+      description: 是否记录HTTP访问日志
+    log_tcp:
+      type: boolean
+      description: 是否记录TCP访问日志
+    log_normal:
+      type: boolean
+      description: 是否记录结果正常的访问
+LoadbalancerAgentParamsTelegraf:
+  type: object
+  description: Telegraf参数
+  properties:
+    haproxy_input_interval:
+      type: integer
+      description: HAProxy统计数据的采样间隔
+      unit: seconds
+      minimum: 1
+    influx_db_output_name:
+      type: string
+      description: 存储监控数据的InfluxDB数据库的名称
+      example: "telegraf"
+    influx_db_output_unsafe_ssl:
+      type: boolean
+      description: 访问InfluxDB时是否忽略证书校验
+    influx_db_output_url:
+      type: string
+      description: InfluxDB的API地址
+      example: https://10.168.222.136:8086/
+
+LoadbalancerAgentCreateRequest:
+  type: object
+  properties:
+    loadbalanceragent:
+      type: object
+      required:
+        - cluster
+      properties:
+        cluster:
+          type: string
+          description: 指定转发实例所属的集群
+        params:
+          $ref: '#/LoadbalancerAgentParams'
+LoadbalancerAgentListResponse:
+  type: object
+  properties:
+    loadbalanceragents:
+      type: array
+      items:
+        $ref: '#/LoadbalancerAgent'
+LoadbalancerAgentResponse:
+  type: object
+  properties:
+    loadbalanceragent:
+      type: object
+      $ref: '#/LoadbalancerAgent'