.. -*- rst -*- List Pools ========== .. rest_method:: GET /v2/lbaas/pools Lists all pools for the project. Use the ``fields`` query parameter to control which fields are returned in the response body. Additionally, you can filter results by using query string parameters. For information, see :ref:`filtering`. Administrative users can specify a project ID that is different than their own to list pools for other projects. The list might be empty. .. rest_status_code:: success ../http-status.yaml - 200 .. rest_status_code:: error ../http-status.yaml - 400 - 401 - 500 Request ------- .. rest_parameters:: ../parameters.yaml - fields: fields - project_id: project_id_query Curl Example ------------ .. literalinclude:: examples/pools-list-curl :language: bash Response Parameters ------------------- .. rest_parameters:: ../parameters.yaml - admin_state_up: admin_state_up - ca_tls_container_ref: ca_tls_container_ref - created_at: created_at - crl_container_ref: crl_container_ref - description: description - healthmonitor_id: healthmonitor-id - id: pool-id - lb_algorithm: lb-algorithm - listeners: listener-ids - loadbalancers: loadbalancer-ids - members: member-ids - name: name - operating_status: operating_status - project_id: project_id - protocol: protocol-pools - provisioning_status: provisioning_status - session_persistence: session_persistence - tags: tags - tls_ciphers: tls_ciphers - tls_container_ref: tls_container_ref - tls_enabled: tls_enabled - updated_at: updated_at Response Example ---------------- .. literalinclude:: examples/pools-list-response.json :language: javascript Create Pool =========== .. rest_method:: POST /v2/lbaas/pools Creates a pool for a load balancer. The pool defines how requests should be balanced across the backend member servers. This operation provisions a pool by using the configuration that you define in the request object. After the API validates the request and starts the provisioning process, the API returns a response object, which contains a unique ID. In the response, the pool :ref:`provisioning status` is ``ACTIVE``, ``PENDING_CREATE``, or ``ERROR``. If the status is ``PENDING_CREATE``, issue GET ``/v2/lbaas/pools/{pool_id}`` to view the progress of the provisioning operation. When the pool status changes to ``ACTIVE``, the pool is successfully provisioned and is ready for further configuration. At a minimum, you must specify these pool attributes: - ``protocol`` The protocol for which this pool and its members listen. A valid value is ``HTTP``, ``HTTPS``, ``PROXY``, ``TCP``, or ``UDP``. - ``lb_algorithm`` The load-balancer algorithm, such as ``ROUND_ROBIN``, ``LEAST_CONNECTIONS``, ``SOURCE_IP`` and ``SOURCE_IP_PORT``, that distributes traffic to the pool members. The load-balancer provider must support this algorithm. - ``listener_id`` The ID of the listener in which this pool becomes the default pool. Each listener has only one default pool. ---OR--- - ``loadbalancer_id`` The ID of the load balancer under which this pool will be created. Each load balancer can have zero or more pools associated with it. These pools can be used for L7policies. .. note:: Either ``listener_id`` or ``loadbalancer_id`` must be specified. Some attributes receive default values if you omit them from the request: - ``admin_state_up`` Default is ``true``. - ``name`` Default is an empty string. - ``description`` Default is an empty string. If the API cannot fulfill the request due to insufficient data or data that is not valid, the service returns the HTTP ``Bad Request (400)`` response code with information about the failure in the response body. Validation errors require that you correct the error and submit the request again. Specifying a project_id is deprecated. The pool will inherit the project_id of the parent load balancer. You can configure all documented features of the pool at creation time by specifying the additional elements or attributes in the request. To create a pool, the parent load balancer must have an ``ACTIVE`` provisioning status. ``SOURCE_IP_PORT`` algorithm is available from version 2.13. .. rest_status_code:: success ../http-status.yaml - 201 .. rest_status_code:: error ../http-status.yaml - 400 - 401 - 403 - 404 - 409 - 500 - 503 Request ------- .. rest_parameters:: ../parameters.yaml - admin_state_up: admin_state_up-default-optional - ca_tls_container_ref: ca_tls_container_ref-optional - crl_container_ref: crl_container_ref-optional - description: description-optional - lb_algorithm: lb-algorithm - listener_id: listener-id-pool-optional - loadbalancer_id: loadbalancer-id-pool-optional - name: name-optional - project_id: project_id-optional-deprecated - protocol: protocol-pools - session_persistence: session_persistence-optional - tags: tags-optional - tls_enabled: tls_enabled-optional - tls_ciphers: tls_ciphers-optional - tls_container_ref: tls_container_ref-optional .. _session_persistence: Pool Session Persistence ------------------------ Pool session persistence tells the load balancer to attempt to send future requests from a client to the same backend member as the initial request. When the pool has no session persistence, the session persistence object is ``null``. Octavia currently support three session persistence methods: +-----------------+----------------------------------------------------------+ | Method | Description | +=================+==========================================================+ | ``APP_COOKIE`` | Use the specified ``cookie_name`` send future requests | | | to the same member. | +-----------------+----------------------------------------------------------+ | ``HTTP_COOKIE`` | The load balancer will generate a cookie that is | | | inserted into the response. This cookie will be used to | | | send future requests to the same member. | +-----------------+----------------------------------------------------------+ | ``SOURCE_IP`` | The source IP address on the request will be hashed to | | | send future requests to the same member. | +-----------------+----------------------------------------------------------+ Pool Session Persistence Object ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. rest_parameters:: ../parameters.yaml - type: session_persistence_type - cookie_name: session_persistence_cookie - persistence_timeout: session_persistence_timeout - persistence_granularity: session_persistence_granularity Pool Session Persistence Object Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. literalinclude:: examples/pool-session-persistence-obj.json :language: javascript Request Example ---------------- .. literalinclude:: examples/pool-create-request.json :language: javascript Curl Example ------------ .. literalinclude:: examples/pool-create-curl :language: bash Response Parameters ------------------- .. rest_parameters:: ../parameters.yaml - admin_state_up: admin_state_up - ca_tls_container_ref: ca_tls_container_ref - created_at: created_at - crl_container_ref: crl_container_ref - description: description - healthmonitor_id: healthmonitor-id - id: pool-id - lb_algorithm: lb-algorithm - listeners: listener-ids - loadbalancers: loadbalancer-ids - members: member-ids - name: name - operating_status: operating_status - project_id: project_id - protocol: protocol-pools - provisioning_status: provisioning_status - session_persistence: session_persistence - tags: tags - tls_enabled: tls_enabled - tls_ciphers: tls_ciphers - tls_container_ref: tls_container_ref - updated_at: updated_at Response Example ---------------- .. literalinclude:: examples/pool-create-response.json :language: javascript Show Pool details ================= .. rest_method:: GET /v2/lbaas/pools/{pool_id} Shows the details of a pool. If you are not an administrative user and the parent load balancer does not belong to your project, the service returns the HTTP ``Forbidden (403)`` response code. This operation does not require a request body. .. rest_status_code:: success ../http-status.yaml - 200 .. rest_status_code:: error ../http-status.yaml - 401 - 403 - 404 - 500 Request ------- .. rest_parameters:: ../parameters.yaml - fields: fields - pool_id: path-pool-id Curl Example ------------ .. literalinclude:: examples/pool-show-curl :language: bash Response Parameters ------------------- .. rest_parameters:: ../parameters.yaml - admin_state_up: admin_state_up - ca_tls_container_ref: ca_tls_container_ref - created_at: created_at - crl_container_ref: crl_container_ref - description: description - healthmonitor_id: healthmonitor-id - id: pool-id - lb_algorithm: lb-algorithm - listeners: listener-ids - loadbalancers: loadbalancer-ids - members: member-ids - name: name - operating_status: operating_status - project_id: project_id - protocol: protocol-pools - provisioning_status: provisioning_status - session_persistence: session_persistence - tags: tags - tls_enabled: tls_enabled - tls_ciphers: tls_ciphers - tls_container_ref: tls_container_ref - updated_at: updated_at Response Example ---------------- .. literalinclude:: examples/pool-show-response.json :language: javascript Update a Pool ============= .. rest_method:: PUT /v2/lbaas/pools/{pool_id} Update an existing pool. If the request is valid, the service returns the ``Accepted (202)`` response code. To confirm the update, check that the pool provisioning status is ``ACTIVE``. If the status is ``PENDING_UPDATE``, use a GET operation to poll the pool object for changes. This operation returns the updated pool object with the ``ACTIVE``, ``PENDING_UPDATE``, or ``ERROR`` provisioning status. .. rest_status_code:: success ../http-status.yaml - 202 .. rest_status_code:: error ../http-status.yaml - 400 - 401 - 403 - 404 - 409 - 500 Request ------- .. rest_parameters:: ../parameters.yaml - admin_state_up: admin_state_up-default-optional - ca_tls_container_ref: ca_tls_container_ref-optional - crl_container_ref: crl_container_ref-optional - description: description-optional - lb_algorithm: lb-algorithm-optional - name: name-optional - pool_id: path-pool-id - session_persistence: session_persistence-optional - tags: tags-optional - tls_enabled: tls_enabled-optional - tls_ciphers: tls_ciphers-optional - tls_container_ref: tls_container_ref-optional Request Example --------------- .. literalinclude:: examples/pool-update-request.json :language: javascript Curl Example ------------ .. literalinclude:: examples/pool-update-curl :language: bash Response Parameters ------------------- .. rest_parameters:: ../parameters.yaml - admin_state_up: admin_state_up - ca_tls_container_ref: ca_tls_container_ref - created_at: created_at - crl_container_ref: crl_container_ref - description: description - healthmonitor_id: healthmonitor-id - id: pool-id - lb_algorithm: lb-algorithm - listeners: listener-ids - loadbalancers: loadbalancer-ids - members: member-ids - name: name - operating_status: operating_status - project_id: project_id - protocol: protocol-pools - provisioning_status: provisioning_status - session_persistence: session_persistence - tags: tags - tls_enabled: tls_enabled - tls_ciphers: tls_ciphers - tls_container_ref: tls_container_ref - updated_at: updated_at Response Example ---------------- .. literalinclude:: examples/pool-update-response.json :language: javascript Remove a Pool ============= .. rest_method:: DELETE /v2/lbaas/pools/{pool_id} Removes a pool and its associated configuration from the load balancer. The API immediately purges any and all configuration data, depending on the configuration settings. You cannot recover it. .. rest_status_code:: success ../http-status.yaml - 204 .. rest_status_code:: error ../http-status.yaml - 400 - 401 - 403 - 404 - 409 - 500 Request ------- .. rest_parameters:: ../parameters.yaml - pool_id: path-pool-id Curl Example ------------ .. literalinclude:: examples/pool-delete-curl :language: bash Response -------- There is no body content for the response of a successful DELETE request.