From debcbc50c8d4f8295252e9f93b51b9942f5482ed Mon Sep 17 00:00:00 2001 From: johnsom Date: Tue, 27 Jun 2017 10:00:42 -0700 Subject: [PATCH] Add v2 L7 Rule API section This patch adds the L7 rule section to the v2 API reference. Change-Id: I43ad86c7cc72b4844247c39f76f30dde349e7a65 Partial-Bug: #1558385 --- api-ref/source/parameters.yaml | 99 ++++- .../v2/examples/l7policy-create-response.json | 2 +- .../v2/examples/l7policy-show-response.json | 2 +- .../v2/examples/l7policy-update-response.json | 2 +- api-ref/source/v2/examples/l7rule-create-curl | 1 + .../v2/examples/l7rule-create-request.json | 9 + .../v2/examples/l7rule-create-response.json | 17 + api-ref/source/v2/examples/l7rule-delete-curl | 1 + api-ref/source/v2/examples/l7rule-show-curl | 1 + .../v2/examples/l7rule-show-response.json | 17 + api-ref/source/v2/examples/l7rule-update-curl | 1 + .../v2/examples/l7rule-update-request.json | 9 + .../v2/examples/l7rule-update-response.json | 17 + api-ref/source/v2/examples/l7rules-list-curl | 1 + .../v2/examples/l7rules-list-response.json | 18 + api-ref/source/v2/index.rst | 5 + api-ref/source/v2/l7rule.inc | 348 ++++++++++++++++++ 17 files changed, 541 insertions(+), 9 deletions(-) create mode 100644 api-ref/source/v2/examples/l7rule-create-curl create mode 100644 api-ref/source/v2/examples/l7rule-create-request.json create mode 100644 api-ref/source/v2/examples/l7rule-create-response.json create mode 100644 api-ref/source/v2/examples/l7rule-delete-curl create mode 100644 api-ref/source/v2/examples/l7rule-show-curl create mode 100644 api-ref/source/v2/examples/l7rule-show-response.json create mode 100644 api-ref/source/v2/examples/l7rule-update-curl create mode 100644 api-ref/source/v2/examples/l7rule-update-request.json create mode 100644 api-ref/source/v2/examples/l7rule-update-response.json create mode 100644 api-ref/source/v2/examples/l7rules-list-curl create mode 100644 api-ref/source/v2/examples/l7rules-list-response.json create mode 100644 api-ref/source/v2/l7rule.inc diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index b3e75905fc..e8e0b17f7d 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -13,6 +13,12 @@ path-l7policy-id: in: path required: true type: string +path-l7rule-id: + description: | + The ID of the L7 rule to query. + in: path + required: true + type: string path-listener-id: description: | The ID of the listener to query. @@ -150,13 +156,15 @@ bytes_out: type: integer connection_limit: description: | - The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections. + The maximum number of connections permitted for this listener. Default + value is -1 which represents infinite connections. in: body required: true type: integer connection_limit-optional: description: | - The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections. + The maximum number of connections permitted for this listener. Default + value is -1 which represents infinite connections. in: body required: false type: integer @@ -454,6 +462,81 @@ l7policy-rule-ids: in: body required: true type: array +l7rule-compare_type: + description: | + The comparison type for the L7 rule. One of ``CONTAINS``, ``ENDS_WITH``, + ``EQUAL_TO``, ``REGEX``, or ``STARTS_WITH``. + in: body + required: true + type: string +l7rule-compare_type-optional: + description: | + The comparison type for the L7 rule. One of ``CONTAINS``, ``ENDS_WITH``, + ``EQUAL_TO``, ``REGEX``, or ``STARTS_WITH``. + in: body + required: false + type: string +l7rule-id: + description: | + The ID of the L7 rule. + in: body + required: true + type: string +l7rule-invert: + description: | + When ``true`` the logic of the rule is inverted. For example, with + invert ``true``, `equal to` would become `not equal to`. + in: body + required: true + type: boolean +l7rule-invert-optional: + description: | + When ``true`` the logic of the rule is inverted. For example, with + invert ``true``, `equal to` would become `not equal to`. + Default is ``false``. + in: body + required: false + type: boolean +l7rule-key: + description: | + The key to use for the comparison. For example, the name of the cookie + to evaluate. + in: body + required: true + type: string +l7rule-key-optional: + description: | + The key to use for the comparison. For example, the name of the cookie + to evaluate. + in: body + required: false + type: string +l7rule-type: + description: | + The L7 rule type. One of ``COOKIE``, ``FILE_TYPE``, ``HEADER``, + ``HOST_NAME``, or ``PATH``. + in: body + required: true + type: string +l7rule-type-optional: + description: | + The L7 rule type. One of ``COOKIE``, ``FILE_TYPE``, ``HEADER``, + ``HOST_NAME``, or ``PATH``. + in: body + required: false + type: string +l7rule-value: + description: | + The value to use for the comparison. For example, the file type to compare. + in: body + required: true + type: string +l7rule-value-optional: + description: | + The value to use for the comparison. For example, the file type to compare. + in: body + required: false + type: string l7rules-status-object-list: description: | A list of L7 rule status objects. @@ -488,7 +571,8 @@ listener-id: type: string listener-id-pool-optional: description: | - The ID of the listener for the pool. Either ``listener_id`` or ``loadbalancer_id`` must be specified. + The ID of the listener for the pool. Either ``listener_id`` or + ``loadbalancer_id`` must be specified. in: body required: false type: string @@ -530,7 +614,8 @@ loadbalancer-id: 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. + The ID of the load balancer for the pool. Either ``listener_id`` or + ``loadbalancer_id`` must be specified. in: body required: false type: string @@ -660,13 +745,15 @@ project_id-optional-deprecated: type: string protocol: description: | - The protocol for the resource. One of ``HTTP``, ``HTTPS``, ``TCP``, or ``TERMINATED_HTTPS``. + The protocol for the resource. One of ``HTTP``, ``HTTPS``, ``TCP``, or + ``TERMINATED_HTTPS``. in: body required: true type: integer protocol-pools: description: | - The protocol for the resource. One of ``HTTP``, ``HTTPS``, ``PROXY``, or ``TCP``. + The protocol for the resource. One of ``HTTP``, ``HTTPS``, ``PROXY``, or + ``TCP``. in: body required: true type: string diff --git a/api-ref/source/v2/examples/l7policy-create-response.json b/api-ref/source/v2/examples/l7policy-create-response.json index 8816406bd5..bf34fd263e 100644 --- a/api-ref/source/v2/examples/l7policy-create-response.json +++ b/api-ref/source/v2/examples/l7policy-create-response.json @@ -1,5 +1,5 @@ { - "l7policies": [ + "l7policy": [ { "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d", "description": "Redirect requests to example.com", diff --git a/api-ref/source/v2/examples/l7policy-show-response.json b/api-ref/source/v2/examples/l7policy-show-response.json index f4bfc0828f..54342b7c91 100644 --- a/api-ref/source/v2/examples/l7policy-show-response.json +++ b/api-ref/source/v2/examples/l7policy-show-response.json @@ -1,5 +1,5 @@ { - "l7policies": + "l7policy": { "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d", "description": "Redirect requests to example.com", diff --git a/api-ref/source/v2/examples/l7policy-update-response.json b/api-ref/source/v2/examples/l7policy-update-response.json index c451aa2062..7f67b6c628 100644 --- a/api-ref/source/v2/examples/l7policy-update-response.json +++ b/api-ref/source/v2/examples/l7policy-update-response.json @@ -1,5 +1,5 @@ { - "l7policies": + "l7policy": { "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d", "description": "Redirect requests to example.com", diff --git a/api-ref/source/v2/examples/l7rule-create-curl b/api-ref/source/v2/examples/l7rule-create-curl new file mode 100644 index 0000000000..bee69264ce --- /dev/null +++ b/api-ref/source/v2/examples/l7rule-create-curl @@ -0,0 +1 @@ +curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: " -d '{"rule":{"compare_type":"REGEX","invert":false,"type":"PATH","value":"/images*","admin_state_up":true}}' http://198.51.100.10:9876/v2.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules diff --git a/api-ref/source/v2/examples/l7rule-create-request.json b/api-ref/source/v2/examples/l7rule-create-request.json new file mode 100644 index 0000000000..d9e46b9411 --- /dev/null +++ b/api-ref/source/v2/examples/l7rule-create-request.json @@ -0,0 +1,9 @@ +{ + "rule": { + "compare_type": "REGEX", + "invert": false, + "type": "PATH", + "value": "/images*", + "admin_state_up": true + } +} diff --git a/api-ref/source/v2/examples/l7rule-create-response.json b/api-ref/source/v2/examples/l7rule-create-response.json new file mode 100644 index 0000000000..049e8ad1e3 --- /dev/null +++ b/api-ref/source/v2/examples/l7rule-create-response.json @@ -0,0 +1,17 @@ +{ + "rule": + { + "created_at": "2017-06-27T15:52:27", + "compare_type": "REGEX", + "provisioning_status": "PENDING_CREATE", + "invert": false, + "admin_state_up": true, + "updated_at": "2017-06-27T15:52:28", + "value": "/images*", + "key": null, + "project_id": "e3cd678b11784734bc366148aa37580e", + "type": "PATH", + "id": "16621dbb-a736-4888-a57a-3ecd53df784c", + "operating_status": "OFFLINE" + } +} diff --git a/api-ref/source/v2/examples/l7rule-delete-curl b/api-ref/source/v2/examples/l7rule-delete-curl new file mode 100644 index 0000000000..de76157355 --- /dev/null +++ b/api-ref/source/v2/examples/l7rule-delete-curl @@ -0,0 +1 @@ +curl -X DELETE -H "X-Auth-Token: " http://198.51.100.10:9876/v2.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules/16621dbb-a736-4888-a57a-3ecd53df784c diff --git a/api-ref/source/v2/examples/l7rule-show-curl b/api-ref/source/v2/examples/l7rule-show-curl new file mode 100644 index 0000000000..95cea02d5d --- /dev/null +++ b/api-ref/source/v2/examples/l7rule-show-curl @@ -0,0 +1 @@ +curl -X GET -H "X-Auth-Token: " http://198.51.100.10:9876/v2.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules/16621dbb-a736-4888-a57a-3ecd53df784c diff --git a/api-ref/source/v2/examples/l7rule-show-response.json b/api-ref/source/v2/examples/l7rule-show-response.json new file mode 100644 index 0000000000..6c7547ade5 --- /dev/null +++ b/api-ref/source/v2/examples/l7rule-show-response.json @@ -0,0 +1,17 @@ +{ + "rule": + { + "created_at": "2017-06-27T15:52:27", + "compare_type": "REGEX", + "provisioning_status": "ACTIVE", + "invert": false, + "admin_state_up": true, + "updated_at": "2017-06-27T15:52:28", + "value": "/images*", + "key": null, + "project_id": "e3cd678b11784734bc366148aa37580e", + "type": "PATH", + "id": "16621dbb-a736-4888-a57a-3ecd53df784c", + "operating_status": "ONLINE" + } +} diff --git a/api-ref/source/v2/examples/l7rule-update-curl b/api-ref/source/v2/examples/l7rule-update-curl new file mode 100644 index 0000000000..534e96dde1 --- /dev/null +++ b/api-ref/source/v2/examples/l7rule-update-curl @@ -0,0 +1 @@ +curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: " -d '{"rule":{"compare_type":"REGEX","invert":true,"type":"PATH","value":"/images/special*","admin_state_up":true}}' http://198.51.100.10:9876/v2.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules/16621dbb-a736-4888-a57a-3ecd53df784c diff --git a/api-ref/source/v2/examples/l7rule-update-request.json b/api-ref/source/v2/examples/l7rule-update-request.json new file mode 100644 index 0000000000..e2f72019a0 --- /dev/null +++ b/api-ref/source/v2/examples/l7rule-update-request.json @@ -0,0 +1,9 @@ +{ + "rule": { + "compare_type": "REGEX", + "invert": true, + "type": "PATH", + "value": "/images/special*", + "admin_state_up": true + } +} diff --git a/api-ref/source/v2/examples/l7rule-update-response.json b/api-ref/source/v2/examples/l7rule-update-response.json new file mode 100644 index 0000000000..5f50ab7c3f --- /dev/null +++ b/api-ref/source/v2/examples/l7rule-update-response.json @@ -0,0 +1,17 @@ +{ + "rule": + { + "created_at": "2017-06-27T15:52:27", + "compare_type": "REGEX", + "provisioning_status": "PENDING_UPDATE", + "invert": true, + "admin_state_up": true, + "updated_at": "2017-06-27T15:58:28", + "value": "/images/special*", + "key": null, + "project_id": "e3cd678b11784734bc366148aa37580e", + "type": "PATH", + "id": "16621dbb-a736-4888-a57a-3ecd53df784c", + "operating_status": "ONLINE" + } +} diff --git a/api-ref/source/v2/examples/l7rules-list-curl b/api-ref/source/v2/examples/l7rules-list-curl new file mode 100644 index 0000000000..96838376f7 --- /dev/null +++ b/api-ref/source/v2/examples/l7rules-list-curl @@ -0,0 +1 @@ +curl -X GET -H "X-Auth-Token: " http://198.51.100.10:9876/v2.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules diff --git a/api-ref/source/v2/examples/l7rules-list-response.json b/api-ref/source/v2/examples/l7rules-list-response.json new file mode 100644 index 0000000000..c55139d8d1 --- /dev/null +++ b/api-ref/source/v2/examples/l7rules-list-response.json @@ -0,0 +1,18 @@ +{ + "rules": [ + { + "created_at": "2017-06-27T15:52:27", + "compare_type": "REGEX", + "provisioning_status": "ACTIVE", + "invert": false, + "admin_state_up": true, + "updated_at": "2017-06-27T15:52:28", + "value": "/images*", + "key": null, + "project_id": "e3cd678b11784734bc366148aa37580e", + "type": "PATH", + "id": "16621dbb-a736-4888-a57a-3ecd53df784c", + "operating_status": "ONLINE" + } + ] +} diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst index de840b57c4..1604512954 100644 --- a/api-ref/source/v2/index.rst +++ b/api-ref/source/v2/index.rst @@ -40,3 +40,8 @@ Health Monitor L7 Policies ----------- .. include:: l7policy.inc + +-------- +L7 Rules +-------- +.. include:: l7rule.inc diff --git a/api-ref/source/v2/l7rule.inc b/api-ref/source/v2/l7rule.inc new file mode 100644 index 0000000000..2f424a098c --- /dev/null +++ b/api-ref/source/v2/l7rule.inc @@ -0,0 +1,348 @@ +.. -*- rst -*- + +List L7 Rules +============= + +.. rest_method:: GET /v2.0/lbaas/l7policies/{l7policy_id}/rules + +Lists all L7 rules 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 L7 policies 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 + - l7policy_id: path-l7policy-id + - project_id: project_id_query + +Curl Example +------------ + +.. literalinclude:: examples/l7rules-list-curl + :language: bash + +Response Parameters +------------------- + +.. rest_parameters:: ../parameters.yaml + + - admin_state_up: admin_state_up + - compare_type: l7rule-compare_type + - created_at: created_at + - id: l7rule-id + - invert: l7rule-invert + - key: l7rule-key + - operating_status: operating_status + - project_id: project_id + - provisioning_status: provisioning_status + - type: l7rule-type + - updated_at: updated_at + - value: l7rule-value + +Response Example +---------------- + +.. literalinclude:: examples/l7rules-list-response.json + :language: javascript + +Create an L7 Rule +================= + +.. rest_method:: POST /v2.0/lbaas/l7policies/{l7policy_id}/rules + +Creates a L7 rule. + +This operation provisions a new L7 rule 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 that contains a unique ID and the status +of provisioning the L7 rule. + +In the response, the L7 rule :ref:`provisioning status` is +``ACTIVE``, ``PENDING_CREATE``, or ``ERROR``. + +If the status is ``PENDING_CREATE``, issue GET +``/v2.0/lbaas/l7policies/{l7policy_id}/rules/{l7rule_id}`` to view the +progress of the provisioning operation. When the L7 rule status changes +to ``ACTIVE``, the L7 rule is successfully provisioned and +is ready for further configuration. + +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. + +All the rules associated with a given policy are logically ANDed together. A +request must match all the policy’s rules to match the policy. + +If you need to express a logical OR operation between rules, then do this by +creating multiple policies with the same action. + +.. 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 + - compare_type: l7rule-compare_type + - invert: l7rule-invert-optional + - key: l7rule-key-optional + - l7policy_id: path-l7policy-id + - project_id: project_id-optional + - type: l7rule-type + - value: l7rule-value + +Request Example +---------------- + +.. literalinclude:: examples/l7rule-create-request.json + :language: javascript + +Curl Example +------------ + +.. literalinclude:: examples/l7rule-create-curl + :language: bash + +Response Parameters +------------------- + +.. rest_parameters:: ../parameters.yaml + + - admin_state_up: admin_state_up + - compare_type: l7rule-compare_type + - created_at: created_at + - id: l7rule-id + - invert: l7rule-invert + - key: l7rule-key + - operating_status: operating_status + - project_id: project_id + - provisioning_status: provisioning_status + - type: l7rule-type + - updated_at: updated_at + - value: l7rule-value + +Response Example +---------------- + +.. literalinclude:: examples/l7rule-create-response.json + :language: javascript + +Show L7 Rule details +========================== + +.. rest_method:: GET /v2.0/lbaas/l7policies/{l7policy_id}/rules/{l7rule_id} + +Shows the details of a L7 rule. + +If you are not an administrative user and the L7 rule object 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 + - l7policy_id: path-l7policy-id + - l7rule_id: path-l7rule-id + +Curl Example +------------ + +.. literalinclude:: examples/l7rule-show-curl + :language: bash + +Response Parameters +------------------- + +.. rest_parameters:: ../parameters.yaml + + - admin_state_up: admin_state_up + - compare_type: l7rule-compare_type + - created_at: created_at + - id: l7rule-id + - invert: l7rule-invert + - key: l7rule-key + - operating_status: operating_status + - project_id: project_id + - provisioning_status: provisioning_status + - type: l7rule-type + - updated_at: updated_at + - value: l7rule-value + +Response Example +---------------- + +.. literalinclude:: examples/l7rule-show-response.json + :language: javascript + +Update a L7 Rule +================ + +.. rest_method:: PUT /v2.0/lbaas/l7policies/{l7policy_id}/rules/{l7rule_id} + +Updates a L7 rule. + +If the request is valid, the service returns the ``Accepted (202)`` +response code. To confirm the update, check that the L7 rule +provisioning status is ``ACTIVE``. If the status is +``PENDING_UPDATE``, use a GET operation to poll the L7 rule +object for changes. + +This operation returns the updated L7 rule 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 + - compare_type: l7rule-compare_type-optional + - invert: l7rule-invert-optional + - key: l7rule-key-optional + - l7policy_id: path-l7policy-id + - l7rule_id: path-l7rule-id + - type: l7rule-type-optional + - value: l7rule-value-optional + +Request Example +--------------- + +.. literalinclude:: examples/l7rule-update-request.json + :language: javascript + +Curl Example +------------ + +.. literalinclude:: examples/l7rule-update-curl + :language: bash + +Response Parameters +------------------- + +.. rest_parameters:: ../parameters.yaml + + - admin_state_up: admin_state_up + - compare_type: l7rule-compare_type + - created_at: created_at + - id: l7rule-id + - invert: l7rule-invert + - key: l7rule-key + - operating_status: operating_status + - project_id: project_id + - provisioning_status: provisioning_status + - type: l7rule-type + - updated_at: updated_at + - value: l7rule-value + +Response Example +---------------- + +.. literalinclude:: examples/l7rule-update-response.json + :language: javascript + +Remove a L7 Rule +================ + +.. rest_method:: DELETE /v2.0/lbaas/l7policies/{l7policy_id}/rules/{l7rule_id} + +Removes a L7 rule and its associated configuration from the project. + +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 + + - l7policy_id: path-l7policy-id + - l7rule_id: path-l7rule-id + +Curl Example +------------ + +.. literalinclude:: examples/l7rule-delete-curl + :language: bash + +Response +-------- + +There is no body content for the response of a successful DELETE request.