From 639aa1cd04b6df13400ea954dcf08944f034c9bc Mon Sep 17 00:00:00 2001 From: johnsom Date: Wed, 19 Apr 2017 11:53:27 -0700 Subject: [PATCH] Add v2 pool API section This patch adds the pool section to the v2 API reference. Change-Id: I70e5cb07a4435f58f5da3999be70162efa7f0bd8 Partial-Bug: #1558385 --- api-ref/source/parameters.yaml | 106 ++++- .../v2/examples/listener-create-response.json | 1 - .../v2/examples/listener-show-response.json | 1 - .../v2/examples/listener-update-response.json | 1 - .../v2/examples/listeners-list-response.json | 1 - .../loadbalancer-create-response.json | 1 - .../loadbalancer-full-create-response.json | 9 +- .../examples/loadbalancer-show-response.json | 1 - .../loadbalancer-update-response.json | 1 - .../examples/loadbalancers-list-response.json | 1 - api-ref/source/v2/examples/pool-create-curl | 1 + .../v2/examples/pool-create-request.json | 14 + .../v2/examples/pool-create-response.json | 31 ++ api-ref/source/v2/examples/pool-delete-curl | 1 + .../pool-session-persistence-obj.json | 1 + api-ref/source/v2/examples/pool-show-curl | 1 + .../v2/examples/pool-show-response.json | 31 ++ api-ref/source/v2/examples/pool-update-curl | 1 + .../v2/examples/pool-update-request.json | 10 + .../v2/examples/pool-update-response.json | 31 ++ api-ref/source/v2/examples/pools-list-curl | 1 + .../v2/examples/pools-list-response.json | 38 ++ api-ref/source/v2/general.inc | 32 +- api-ref/source/v2/index.rst | 5 + api-ref/source/v2/listener.inc | 62 ++- api-ref/source/v2/loadbalancer.inc | 6 - api-ref/source/v2/pool.inc | 431 ++++++++++++++++++ 27 files changed, 718 insertions(+), 102 deletions(-) create mode 100644 api-ref/source/v2/examples/pool-create-curl create mode 100644 api-ref/source/v2/examples/pool-create-request.json create mode 100644 api-ref/source/v2/examples/pool-create-response.json create mode 100644 api-ref/source/v2/examples/pool-delete-curl create mode 100644 api-ref/source/v2/examples/pool-session-persistence-obj.json create mode 100644 api-ref/source/v2/examples/pool-show-curl create mode 100644 api-ref/source/v2/examples/pool-show-response.json create mode 100644 api-ref/source/v2/examples/pool-update-curl create mode 100644 api-ref/source/v2/examples/pool-update-request.json create mode 100644 api-ref/source/v2/examples/pool-update-response.json create mode 100644 api-ref/source/v2/examples/pools-list-curl create mode 100644 api-ref/source/v2/examples/pools-list-response.json create mode 100644 api-ref/source/v2/pool.inc diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index c37029ee1b..a1ad8712fb 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -19,6 +19,12 @@ path-loadbalancer-id: in: path required: true type: string +path-pool-id: + description: | + The ID of the pool to query. + in: path + required: true + type: string ############################################################################### # Query fields ############################################################################### @@ -40,12 +46,6 @@ project_id_query: in: query required: false type: string -tenant_id_query: - description: | - The ID of the project to query. (deprecated) - in: query - required: false - type: string ############################################################################### # Body fields @@ -194,9 +194,15 @@ flavor-id-optional: in: body required: false type: string +healthmonitor-id: + description: | + The associated health monitor ID. + in: body + required: true + type: string healthmonitor-status: description: | - The associated healthmonitor status object. + The associated health monitor status object. in: body required: true type: object @@ -246,6 +252,20 @@ l7rules-status-object-list: in: body required: true type: array +lb-algorithm: + description: | + The load balancing algorithm for the pool. One of ``LEAST_CONNECTIONS``, + ``ROUND_ROBIN``, or ``SOURCE_IP``. + in: body + required: true + type: string +lb-algorithm-optional: + description: | + The load balancing algorithm for the pool. One of ``LEAST_CONNECTIONS``, + ``ROUND_ROBIN``, or ``SOURCE_IP``. + in: body + required: false + type: string listener: description: | A listener object. @@ -258,6 +278,18 @@ listener-id: in: body required: true type: string +listener-id-pool-optional: + description: | + The ID of the listener for the pool. Either ``listener_id`` or ``loadbalancer_id`` must be specified. + in: body + required: false + type: string +listener-ids: + description: | + A list of listener IDs. + in: body + required: true + type: array listeners: description: | The associated listener IDs, if any. @@ -288,6 +320,12 @@ loadbalancer-id: in: body required: true type: string +loadbalancer-id-pool-optional: + description: | + The ID of the load balancer for the pool. Either ``listener_id`` or ``loadbalancer_id`` must be specified. + in: body + required: false + type: string loadbalancer-ids: description: | A list of load balancer IDs. @@ -306,6 +344,12 @@ loadbalancers: in: body required: true type: array +member-ids: + description: | + A list of member IDs. + in: body + required: true + type: array members-status-object-list: description: | A list of members status objects. @@ -330,6 +374,12 @@ operating_status: in: body required: true type: string +pool-id: + description: | + The ID of the pool. + in: body + required: true + type: string pool-optional: description: | A pool object. @@ -372,6 +422,12 @@ protocol: in: body required: true type: integer +protocol-pools: + description: | + The protocol for the resource. One of ``HTTP``, ``HTTPS``, ``PROXY``, or ``TCP``. + in: body + required: true + type: string protocol_port: description: | The protocol port number for the resource. @@ -402,6 +458,36 @@ request_errors: in: body required: true type: integer +session_persistence: + description: | + A JSON object specifying the session persistence for the pool or ``null`` + for no session persistence. See :ref:`session_persistence`. Default is + ``null``. + in: body + required: true + type: object +session_persistence-optional: + description: | + A JSON object specifying the session persistence for the pool or ``null`` + for no session persistence. See :ref:`session_persistence`. Default is + ``null``. + in: body + required: false + type: object +session_persistence_cookie: + description: | + The name of the cookie to use for session persistence. Only applicable to + the ``APP_COOKIE`` session persistence type. + in: body + required: false + type: string +session_persistence_type: + description: | + Session persistence type for the pool. One of ``APP_COOKIE``, + ``HTTP_COOKIE``, ``SOURCE_IP``. + in: body + required: true + type: string sni_container_refs: description: | A list of URIs to the `key manager service @@ -433,12 +519,6 @@ statuses: in: body required: true type: object -tenant_id: - description: | - The ID of the project that owns the resource. (deprecated) - in: body - required: false - type: string total_connections: description: | The total connections handled. diff --git a/api-ref/source/v2/examples/listener-create-response.json b/api-ref/source/v2/examples/listener-create-response.json index e443d6bd3a..d8609cfd1f 100644 --- a/api-ref/source/v2/examples/listener-create-response.json +++ b/api-ref/source/v2/examples/listener-create-response.json @@ -2,7 +2,6 @@ "listener": { "description": "A great TLS listener", "admin_state_up": true, - "tenant_id": "e3cd678b11784734bc366148aa37580e", "project_id": "e3cd678b11784734bc366148aa37580e", "protocol": "TERMINATED_HTTPS", "protocol_port": 443, diff --git a/api-ref/source/v2/examples/listener-show-response.json b/api-ref/source/v2/examples/listener-show-response.json index b5a0a64770..acd7f7e5f1 100644 --- a/api-ref/source/v2/examples/listener-show-response.json +++ b/api-ref/source/v2/examples/listener-show-response.json @@ -2,7 +2,6 @@ "listener": { "description": "A great TLS listener", "admin_state_up": true, - "tenant_id": "e3cd678b11784734bc366148aa37580e", "project_id": "e3cd678b11784734bc366148aa37580e", "protocol": "TERMINATED_HTTPS", "protocol_port": 443, diff --git a/api-ref/source/v2/examples/listener-update-response.json b/api-ref/source/v2/examples/listener-update-response.json index d188230cf7..9afefbfe28 100644 --- a/api-ref/source/v2/examples/listener-update-response.json +++ b/api-ref/source/v2/examples/listener-update-response.json @@ -2,7 +2,6 @@ "listener": { "description": "An updated great TLS listener", "admin_state_up": true, - "tenant_id": "e3cd678b11784734bc366148aa37580e", "project_id": "e3cd678b11784734bc366148aa37580e", "protocol": "TERMINATED_HTTPS", "protocol_port": 443, diff --git a/api-ref/source/v2/examples/listeners-list-response.json b/api-ref/source/v2/examples/listeners-list-response.json index 165f8ed6c9..caa9f80b98 100644 --- a/api-ref/source/v2/examples/listeners-list-response.json +++ b/api-ref/source/v2/examples/listeners-list-response.json @@ -3,7 +3,6 @@ { "description": "A great TLS listener", "admin_state_up": true, - "tenant_id": "e3cd678b11784734bc366148aa37580e", "project_id": "e3cd678b11784734bc366148aa37580e", "protocol": "TERMINATED_HTTPS", "protocol_port": 443, diff --git a/api-ref/source/v2/examples/loadbalancer-create-response.json b/api-ref/source/v2/examples/loadbalancer-create-response.json index 0856ebabe2..4e57145cc2 100644 --- a/api-ref/source/v2/examples/loadbalancer-create-response.json +++ b/api-ref/source/v2/examples/loadbalancer-create-response.json @@ -2,7 +2,6 @@ "loadbalancer": { "description": "My favorite load balancer", "admin_state_up": true, - "tenant_id": "e3cd678b11784734bc366148aa37580e", "project_id": "e3cd678b11784734bc366148aa37580e", "provisioning_status": "PENDING_CREATE", "flavor": "", diff --git a/api-ref/source/v2/examples/loadbalancer-full-create-response.json b/api-ref/source/v2/examples/loadbalancer-full-create-response.json index 8a1f300adf..ee984a6df8 100644 --- a/api-ref/source/v2/examples/loadbalancer-full-create-response.json +++ b/api-ref/source/v2/examples/loadbalancer-full-create-response.json @@ -2,7 +2,6 @@ "loadbalancer": { "description": "My favorite load balancer", "admin_state_up": true, - "tenant_id": "e3cd678b11784734bc366148aa37580e", "project_id": "e3cd678b11784734bc366148aa37580e", "provisioning_status": "ACTIVE", "flavor": "", @@ -17,7 +16,6 @@ "default_pool": { "id": "c8cec227-410a-4a5b-af13-ecf38c2b0abb" }, - "tenant_id": "e3cd678b11784734bc366148aa37580e", "project_id": "e3cd678b11784734bc366148aa37580e", "default_tls_container_id": null, "connection_limit": -1, @@ -33,9 +31,8 @@ "default_tls_container_ref": null, "admin_state_up": true, "default_pool": { - "id": "b0577aff-c1f9-40c6-9a3b-7b1d2a669136", + "id": "b0577aff-c1f9-40c6-9a3b-7b1d2a669136" }, - "tenant_id": "e3cd678b11784734bc366148aa37580e", "project_id": "e3cd678b11784734bc366148aa37580e", "default_tls_container_id": null, "connection_limit": -1, @@ -50,7 +47,6 @@ "description": "", "admin_state_up": true, "rules": [], - "tenant_id": "e3cd678b11784734bc366148aa37580e", "project_id": "e3cd678b11784734bc366148aa37580e", "listener_id": "95de30ec-67f4-437b-b3f3-22c5d9ef9828", "redirect_url": "https://www.example.com/", @@ -65,7 +61,6 @@ "default_tls_container_ref": null, "admin_state_up": true, "default_pool": null, - "tenant_id": "e3cd678b11784734bc366148aa37580e", "project_id": "e3cd678b11784734bc366148aa37580e", "default_tls_container_id": null, "connection_limit": -1, @@ -91,7 +86,6 @@ "healthmonitor": { "name": "", "admin_state_up": true, - "tenant_id": "e3cd678b11784734bc366148aa37580e", "project_id": "e3cd678b11784734bc366148aa37580e", "delay": 3, "expected_codes": "200,201,202", @@ -109,7 +103,6 @@ "weight": 1, "admin_state_up": true, "subnet_id": "bbb35f84-35cc-4b2f-84c2-a6a29bba68aa", - "tenant_id": "e3cd678b11784734bc366148aa37580e", "project_id": "e3cd678b11784734bc366148aa37580e", "address": "192.0.2.16", "protocol_port": 80, diff --git a/api-ref/source/v2/examples/loadbalancer-show-response.json b/api-ref/source/v2/examples/loadbalancer-show-response.json index 3496551e40..900a47eb42 100644 --- a/api-ref/source/v2/examples/loadbalancer-show-response.json +++ b/api-ref/source/v2/examples/loadbalancer-show-response.json @@ -2,7 +2,6 @@ "loadbalancer": { "description": "My favorite load balancer", "admin_state_up": true, - "tenant_id": "e3cd678b11784734bc366148aa37580e", "project_id": "e3cd678b11784734bc366148aa37580e", "provisioning_status": "PENDING_CREATE", "flavor": "", diff --git a/api-ref/source/v2/examples/loadbalancer-update-response.json b/api-ref/source/v2/examples/loadbalancer-update-response.json index e6c7cb78c7..6845b00407 100644 --- a/api-ref/source/v2/examples/loadbalancer-update-response.json +++ b/api-ref/source/v2/examples/loadbalancer-update-response.json @@ -2,7 +2,6 @@ "loadbalancer": { "description": "Temporarily disabled load balancer", "admin_state_up": false, - "tenant_id": "e3cd678b11784734bc366148aa37580e", "project_id": "e3cd678b11784734bc366148aa37580e", "provisioning_status": "PENDING_UPDATE", "flavor": "", diff --git a/api-ref/source/v2/examples/loadbalancers-list-response.json b/api-ref/source/v2/examples/loadbalancers-list-response.json index 67c2a0c6a3..4032fa2e81 100644 --- a/api-ref/source/v2/examples/loadbalancers-list-response.json +++ b/api-ref/source/v2/examples/loadbalancers-list-response.json @@ -3,7 +3,6 @@ { "description": "My favorite load balancer", "admin_state_up": true, - "tenant_id": "e3cd678b11784734bc366148aa37580e", "project_id": "e3cd678b11784734bc366148aa37580e", "provisioning_status": "ACTIVE", "flavor": "a7ae5d5a-d855-4f9a-b187-af66b53f4d04", diff --git a/api-ref/source/v2/examples/pool-create-curl b/api-ref/source/v2/examples/pool-create-curl new file mode 100644 index 0000000000..53d9310ed8 --- /dev/null +++ b/api-ref/source/v2/examples/pool-create-curl @@ -0,0 +1 @@ +curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: " -d '{"pool":{"lb_algorithm":"ROUND_ROBIN","protocol":"HTTP","description":"Super Round Robin Pool","admin_state_up":true,"session_persistence":{"cookie_name":"ChocolateChip","type":"APP_COOKIE"},"listener_id":"023f2e34-7806-443b-bfae-16c324569a3d","name":"super-pool"}}' http://198.51.100.10:9876/v2.0/lbaas/pools diff --git a/api-ref/source/v2/examples/pool-create-request.json b/api-ref/source/v2/examples/pool-create-request.json new file mode 100644 index 0000000000..a2632ef040 --- /dev/null +++ b/api-ref/source/v2/examples/pool-create-request.json @@ -0,0 +1,14 @@ +{ + "pool": { + "lb_algorithm": "ROUND_ROBIN", + "protocol": "HTTP", + "description": "Super Round Robin Pool", + "admin_state_up": true, + "session_persistence": { + "cookie_name": "ChocolateChip", + "type": "APP_COOKIE" + }, + "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d", + "name": "super-pool" + } +} diff --git a/api-ref/source/v2/examples/pool-create-response.json b/api-ref/source/v2/examples/pool-create-response.json new file mode 100644 index 0000000000..f9a44529d5 --- /dev/null +++ b/api-ref/source/v2/examples/pool-create-response.json @@ -0,0 +1,31 @@ +{ + "pool": { + "lb_algorithm": "ROUND_ROBIN", + "protocol": "HTTP", + "description": "Super Round Robin Pool", + "admin_state_up": true, + "loadbalancers": [ + { + "id": "607226db-27ef-4d41-ae89-f2a800e9c2db" + } + ], + "created_at": "2017-05-10T18:14:44", + "provisioning_status": "ACTIVE", + "updated_at": "2017-05-10T23:08:12", + "session_persistence": { + "cookie_name": "ChocolateChip", + "type": "APP_COOKIE" + }, + "listeners": [ + { + "id": "023f2e34-7806-443b-bfae-16c324569a3d" + } + ], + "members": [], + "healthmonitor_id": null, + "project_id": "e3cd678b11784734bc366148aa37580e", + "id": "4029d267-3983-4224-a3d0-afb3fe16a2cd", + "operating_status": "ONLINE", + "name": "super-pool" + } +} diff --git a/api-ref/source/v2/examples/pool-delete-curl b/api-ref/source/v2/examples/pool-delete-curl new file mode 100644 index 0000000000..50bc64b613 --- /dev/null +++ b/api-ref/source/v2/examples/pool-delete-curl @@ -0,0 +1 @@ +curl -X DELETE -H "X-Auth-Token: " http://198.51.100.10:9876/v2.0/lbaas/pools/4029d267-3983-4224-a3d0-afb3fe16a2cd diff --git a/api-ref/source/v2/examples/pool-session-persistence-obj.json b/api-ref/source/v2/examples/pool-session-persistence-obj.json new file mode 100644 index 0000000000..385be47c80 --- /dev/null +++ b/api-ref/source/v2/examples/pool-session-persistence-obj.json @@ -0,0 +1 @@ +{"cookie_name": "my_app_cookie", "type": "APP_COOKIE"} diff --git a/api-ref/source/v2/examples/pool-show-curl b/api-ref/source/v2/examples/pool-show-curl new file mode 100644 index 0000000000..04f74f3940 --- /dev/null +++ b/api-ref/source/v2/examples/pool-show-curl @@ -0,0 +1 @@ +curl -X GET -H "X-Auth-Token: " http://198.51.100.10:9876/v2.0/lbaas/pools/24a43e68-36de-45f6-89cf-c03df583131d diff --git a/api-ref/source/v2/examples/pool-show-response.json b/api-ref/source/v2/examples/pool-show-response.json new file mode 100644 index 0000000000..f9a44529d5 --- /dev/null +++ b/api-ref/source/v2/examples/pool-show-response.json @@ -0,0 +1,31 @@ +{ + "pool": { + "lb_algorithm": "ROUND_ROBIN", + "protocol": "HTTP", + "description": "Super Round Robin Pool", + "admin_state_up": true, + "loadbalancers": [ + { + "id": "607226db-27ef-4d41-ae89-f2a800e9c2db" + } + ], + "created_at": "2017-05-10T18:14:44", + "provisioning_status": "ACTIVE", + "updated_at": "2017-05-10T23:08:12", + "session_persistence": { + "cookie_name": "ChocolateChip", + "type": "APP_COOKIE" + }, + "listeners": [ + { + "id": "023f2e34-7806-443b-bfae-16c324569a3d" + } + ], + "members": [], + "healthmonitor_id": null, + "project_id": "e3cd678b11784734bc366148aa37580e", + "id": "4029d267-3983-4224-a3d0-afb3fe16a2cd", + "operating_status": "ONLINE", + "name": "super-pool" + } +} diff --git a/api-ref/source/v2/examples/pool-update-curl b/api-ref/source/v2/examples/pool-update-curl new file mode 100644 index 0000000000..1618f6a974 --- /dev/null +++ b/api-ref/source/v2/examples/pool-update-curl @@ -0,0 +1 @@ +curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: " -d '{"pool":{"lb_algorithm":"LEAST_CONNECTIONS","session_persistence":{"type":"SOURCE_IP"},"description":"second description","name":"second_name"}}' http://198.51.100.10:9876/v2.0/lbaas/pools/4029d267-3983-4224-a3d0-afb3fe16a2cd diff --git a/api-ref/source/v2/examples/pool-update-request.json b/api-ref/source/v2/examples/pool-update-request.json new file mode 100644 index 0000000000..1cd31847ff --- /dev/null +++ b/api-ref/source/v2/examples/pool-update-request.json @@ -0,0 +1,10 @@ +{ + "pool": { + "lb_algorithm": "LEAST_CONNECTIONS", + "session_persistence": { + "type": "SOURCE_IP" + }, + "description": "Super Least Connections Pool", + "name": "super-least-conn-pool" + } +} diff --git a/api-ref/source/v2/examples/pool-update-response.json b/api-ref/source/v2/examples/pool-update-response.json new file mode 100644 index 0000000000..23ac0d6235 --- /dev/null +++ b/api-ref/source/v2/examples/pool-update-response.json @@ -0,0 +1,31 @@ +{ + "pool": { + "lb_algorithm": "LEAST_CONNECTIONS", + "protocol": "HTTP", + "description": "Super Least Connections Pool", + "admin_state_up": true, + "loadbalancers": [ + { + "id": "607226db-27ef-4d41-ae89-f2a800e9c2db" + } + ], + "created_at": "2017-05-10T18:14:44", + "provisioning_status": "ACTIVE", + "updated_at": "2017-05-10T23:08:12", + "session_persistence": { + "cookie_name": null, + "type": "SOURCE_IP" + }, + "listeners": [ + { + "id": "023f2e34-7806-443b-bfae-16c324569a3d" + } + ], + "members": [], + "healthmonitor_id": null, + "project_id": "e3cd678b11784734bc366148aa37580e", + "id": "4029d267-3983-4224-a3d0-afb3fe16a2cd", + "operating_status": "ONLINE", + "name": "super-least-conn-pool" + } +} diff --git a/api-ref/source/v2/examples/pools-list-curl b/api-ref/source/v2/examples/pools-list-curl new file mode 100644 index 0000000000..06549ba91f --- /dev/null +++ b/api-ref/source/v2/examples/pools-list-curl @@ -0,0 +1 @@ +curl -X GET -H "X-Auth-Token: " http://198.51.100.10:9876/v2.0/lbaas/pools?project_id=e3cd678b11784734bc366148aa37580e diff --git a/api-ref/source/v2/examples/pools-list-response.json b/api-ref/source/v2/examples/pools-list-response.json new file mode 100644 index 0000000000..d194029799 --- /dev/null +++ b/api-ref/source/v2/examples/pools-list-response.json @@ -0,0 +1,38 @@ +{ + "pools": [ + { + "lb_algorithm": "ROUND_ROBIN", + "protocol": "HTTP", + "description": "My round robin pool", + "admin_state_up": true, + "loadbalancers": [ + { + "id": "607226db-27ef-4d41-ae89-f2a800e9c2db" + } + ], + "created_at": "2017-04-13T18:14:44", + "provisioning_status": "ACTIVE", + "updated_at": "2017-04-13T23:08:12", + "session_persistence": { + "cookie_name": null, + "type": "SOURCE_IP" + }, + "listeners": [ + { + "id": "023f2e34-7806-443b-bfae-16c324569a3d" + } + ], + "members": [ + { + "id": "5bc73753-348f-4b5a-8f9c-10bd7b30dc35", + "id": "692e8358-f8fd-4b92-bbca-6e4b97c75571" + } + ], + "healthmonitor_id": null, + "project_id": "e3cd678b11784734bc366148aa37580e", + "id": "ddb2b28f-89e9-45d3-a329-a359c3e39e4a", + "operating_status": "ONLINE", + "name": "round_robin_pool" + } + ] +} diff --git a/api-ref/source/v2/general.inc b/api-ref/source/v2/general.inc index 9ec9b90a41..fac31e3c27 100644 --- a/api-ref/source/v2/general.inc +++ b/api-ref/source/v2/general.inc @@ -44,7 +44,7 @@ the full API call for ``/v2.0/lbaas/loadbalancers`` is ``http://198.51.100.10:9876/v2.0/lbaas/loadbalancers``. Depending on the deployment, the ``load-balancer`` ``endpoint URL`` might be -http or https, a custom port, a custom path, and include your tenant id. The +http or https, a custom port, a custom path, and include your project id. The only way to know the URLs for your deployment is by using the service catalog. The ``load-balancer`` ``endpoint URL`` should never be hard coded in applications, even if they are only expected to work at a single site. It @@ -87,9 +87,6 @@ header. You obtain the token by authenticating to the Keystone endpoint. When Keystone is enabled, the ``project_id`` attribute is not required in create requests because the project ID is derived from the authentication token. -NOTE: Currently the Octavia API accepts the deprecated ``tenant_id`` -attribute for the project ID for backward compatibility. - The default authorization settings allow only administrative users to create resources on behalf of a different project. @@ -118,18 +115,6 @@ Request format The Octavia API v2.0 only accepts requests with the JSON data serialization format. The ``Content-Type`` header is ignored. -Tenant and project attributes in requests ------------------------------------------ - -Starting with the Newton release of the Octavia service, the Octavia API -accepts the ``project_id`` attribute in addition to the ``tenant_id`` attribute -in requests. The ``tenant_id`` attribute is accepted for backward compatibility. -If both the ``project_id`` and the ``tenant_id`` attribute are provided in the -same request, ``project_id`` will be used. - -The ``tenant_id`` attribute is deprecated and will be removed in a future -release. - Response format --------------- @@ -144,18 +129,6 @@ Query extension - **GET** *publicURL*/loadbalancers.json -Tenant and project attributes in responses ------------------------------------------- - -Starting with the Newton release of the Octavia service, the Octavia API -returns a ``project_id`` attribute in responses, while still returning a -``tenant_id`` attribute for backward compatibility. The values will always be -identical. - -The ``tenant_id`` attribute is deprecated and will be removed in a future -release. - - .. _filtering: Filtering and column selection @@ -288,7 +261,6 @@ behavior regardless of the particular plug-in running in the background. "provisioning_status": "ACTIVE", "vip_port_id": "1e20d91d-8df9-4c15-9778-28bc89226c19", "vip_address": "203.0.113.10", - "tenant_id": "bf325b04-e7b1-4002-9b10-f4984630367f", "project_id": "bf325b04-e7b1-4002-9b10-f4984630367f" }, { @@ -304,7 +276,6 @@ behavior regardless of the particular plug-in running in the background. "provisioning_status": "ACTIVE", "vip_port_id": "21f7ac04-6824-4222-93cf-46e0d70607f9", "vip_address": "203.0.113.20", - "tenant_id": "bf325b04-e7b1-4002-9b10-f4984630367f", "project_id": "bf325b04-e7b1-4002-9b10-f4984630367f" } ], @@ -353,7 +324,6 @@ The last page won't show the "next" links "provisioning_status": "ACTIVE", "vip_port_id": "f777a1c7-7f59-4a36-ad34-24dfebaf19e6", "vip_address": "203.0.113.50", - "tenant_id": "bf325b04-e7b1-4002-9b10-f4984630367f", "project_id": "bf325b04-e7b1-4002-9b10-f4984630367f" } ], diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst index 798d8d0a3c..37b3b0106f 100644 --- a/api-ref/source/v2/index.rst +++ b/api-ref/source/v2/index.rst @@ -20,3 +20,8 @@ Load Balancers Listeners --------- .. include:: listener.inc + +----- +Pools +----- +.. include:: pool.inc diff --git a/api-ref/source/v2/listener.inc b/api-ref/source/v2/listener.inc index 08fec34257..3094b89f2c 100644 --- a/api-ref/source/v2/listener.inc +++ b/api-ref/source/v2/listener.inc @@ -33,7 +33,6 @@ Request - fields: fields - project_id: project_id_query - - tenant_id: tenant_id_query Curl Example ------------ @@ -64,7 +63,6 @@ Response Parameters - protocol_port: protocol_port - provisioning_status: provisioning_status - sni_container_refs: sni_container_refs - - tenant_id: tenant_id Response Example ---------------- @@ -103,7 +101,7 @@ data that is not valid, the service returns the HTTP ``Bad Request response body. Validation errors require that you correct the error and submit the request again. -Specifying a project_id or tenant_id is deprecated. The listener will inherit +Specifying a project_id is deprecated. The listener will inherit the project_id of the parent load balancer. You can configure all documented features of the listener at creation time by @@ -125,35 +123,6 @@ provisioning status. - 500 - 503 -.. _header_insertions: - -Supported HTTP Header Insertions --------------------------------- - -HTTP header insertion allows you to insert additional HTTP headers as the -requests are passed to the backend members. This allows you to expose -information that would have otherwise not be visible to the backend members. - -The default is to not insert these headers. - -.. note:: - Both the key and the values are always specified as strings when specifying - header insertions. - -HTTP Header Insertion Object -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. rest_parameters:: ../parameters.yaml - - - X-Forwarded-For: x_forwarded_for - - X-Forwarded-Port: x_forwarded_port - -HTTP Header Insertion Object Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. literalinclude:: examples/http-header-insertion-obj.json - :language: javascript - Request ------- @@ -174,7 +143,31 @@ Request - protocol: protocol - protocol_port: protocol_port - sni_container_refs: sni_container_refs-optional - - tenant_id: tenant_id + +.. _header_insertions: + +Supported HTTP Header Insertions +-------------------------------- + +.. note:: + Both the key and the values are always specified as strings when specifying + header insertions. + + ++------------------+---------+------------------------------------------------+ +| Key | Value | Description | ++==================+=========+================================================+ +| X-Forwarded-For | boolean | When ``true`` a ``X-Forwarded-For`` header is | +| | | inserted into the request to the backend | +| | | ``member`` that specifies the client IP | +| | | address. | ++------------------+---------+------------------------------------------------+ +| X-Forwarded-Port | integer | A ``X-Forwarded-Port`` header is inserted into | +| | | the request to the backend ``member`` that | +| | | specifies the integer provided. Typically this | +| | | is used to indicate the port the client | +| | | connected to on the load balancer. | ++------------------+---------+------------------------------------------------+ Request Example ---------------- @@ -211,7 +204,6 @@ Response Parameters - protocol_port: protocol_port - provisioning_status: provisioning_status - sni_container_refs: sni_container_refs - - tenant_id: tenant_id Response Example ---------------- @@ -279,7 +271,6 @@ Response Parameters - protocol_port: protocol_port - provisioning_status: provisioning_status - sni_container_refs: sni_container_refs - - tenant_id: tenant_id Response Example ---------------- @@ -365,7 +356,6 @@ Response Parameters - protocol_port: protocol_port - provisioning_status: provisioning_status - sni_container_refs: sni_container_refs - - tenant_id: tenant_id Response Example ---------------- diff --git a/api-ref/source/v2/loadbalancer.inc b/api-ref/source/v2/loadbalancer.inc index 191212cc2d..5b6b2fe883 100644 --- a/api-ref/source/v2/loadbalancer.inc +++ b/api-ref/source/v2/loadbalancer.inc @@ -33,7 +33,6 @@ Request - fields: fields - project_id: project_id_query - - tenant_id: tenant_id_query Curl Example ------------ @@ -59,7 +58,6 @@ Response Parameters - project_id: project_id - provider: provider - provisioning_status: provisioning_status - - tenant_id: tenant_id - vip_address: vip_address - vip_network_id: vip_network_id - vip_port_id: vip_port_id @@ -151,7 +149,6 @@ Request - name: name-optional - project_id: project_id-optional - provider: provider-optional - - tenant_id: tenant_id - vip_address: vip_address-optional - vip_network_id: vip_network_id-optional - vip_port_id: vip_port_id-optional @@ -187,7 +184,6 @@ Response Parameters - project_id: project_id - provider: provider - provisioning_status: provisioning_status - - tenant_id: tenant_id - vip_address: vip_address - vip_network_id: vip_network_id - vip_port_id: vip_port_id @@ -277,7 +273,6 @@ Response Parameters - project_id: project_id - provider: provider - provisioning_status: provisioning_status - - tenant_id: tenant_id - vip_address: vip_address - vip_network_id: vip_network_id - vip_port_id: vip_port_id @@ -359,7 +354,6 @@ Response Parameters - project_id: project_id - provider: provider - provisioning_status: provisioning_status - - tenant_id: tenant_id - vip_address: vip_address - vip_network_id: vip_network_id - vip_port_id: vip_port_id diff --git a/api-ref/source/v2/pool.inc b/api-ref/source/v2/pool.inc new file mode 100644 index 0000000000..b2db96820e --- /dev/null +++ b/api-ref/source/v2/pool.inc @@ -0,0 +1,431 @@ +.. -*- rst -*- + +List pools +========== + +.. rest_method:: GET /v2.0/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 + - created_at: created_at + - 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 + +Response Example +---------------- + +.. literalinclude:: examples/pools-list-response.json + :language: javascript + +Create Pool +=========== + +.. rest_method:: POST /v2.0/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.0/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``, or ``TCP``. + +- ``lb_algorithm`` The load-balancer algorithm, such as + ``ROUND_ROBIN``, ``LEAST_CONNECTIONS``, and ``SOURCE_IP``, 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. + +.. rest_status_code:: success ../http-status.yaml + + - 201 + +.. rest_status_code:: error ../http-status.yaml + + - 400 + - 401 + - 403 + - 404 + - 500 + - 503 + +Request +------- + +.. rest_parameters:: ../parameters.yaml + + - admin_state_up: admin_state_up-default-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 + +.. _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 + +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 + - created_at: created_at + - 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 + +Response Example +---------------- + +.. literalinclude:: examples/pool-create-response.json + :language: javascript + +Show Pool details +================= + +.. rest_method:: GET /v2.0/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 + + - 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 + - created_at: created_at + - 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 + +Response Example +---------------- + +.. literalinclude:: examples/pool-show-response.json + :language: javascript + +Update a pool +============= + +.. rest_method:: PUT /v2.0/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 + - description: description-optional + - lb_algorithm: lb-algorithm-optional + - name: name-optional + - pool_id: path-pool-id + - session_persistence: session_persistence-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 + - created_at: created_at + - 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 + +Response Example +---------------- + +.. literalinclude:: examples/pool-update-response.json + :language: javascript + +Remove a pool +============= + +.. rest_method:: DELETE /v2.0/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.