openstack/octavia
Code Issues Proposed changes

Add v2 L7 Rule API section

Browse Source 
This patch adds the L7 rule section to the v2 API reference.

Change-Id: I43ad86c7cc72b4844247c39f76f30dde349e7a65
Partial-Bug: #1558385
This commit is contained in:
johnsom 2017-06-27 10:00:42 -07:00
parent a6b3c798bf
commit debcbc50c8
17 changed files with 541 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
api-ref/source/parameters.yaml
View File

@ -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

2
api-ref/source/v2/examples/l7policy-create-response.json
View File

@ -1,5 +1,5 @@
{
"l7policies": [
"l7policy": [
{
"listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
"description": "Redirect requests to example.com",

2
api-ref/source/v2/examples/l7policy-show-response.json
View File

@ -1,5 +1,5 @@
{
"l7policies":
"l7policy":
{
"listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
"description": "Redirect requests to example.com",

2
api-ref/source/v2/examples/l7policy-update-response.json
View File

@ -1,5 +1,5 @@
{
"l7policies":
"l7policy":
{
"listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
"description": "Redirect requests to example.com",

1
api-ref/source/v2/examples/l7rule-create-curl Normal file
View File

@ -0,0 +1 @@
curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <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

9
api-ref/source/v2/examples/l7rule-create-request.json Normal file
View File

@ -0,0 +1,9 @@
{
"rule": {
"compare_type": "REGEX",
"invert": false,
"type": "PATH",
"value": "/images*",
"admin_state_up": true
}
}

17
api-ref/source/v2/examples/l7rule-create-response.json Normal file
View File

@ -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"
}
}

1
api-ref/source/v2/examples/l7rule-delete-curl Normal file
View File

@ -0,0 +1 @@
curl -X DELETE -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules/16621dbb-a736-4888-a57a-3ecd53df784c

1
api-ref/source/v2/examples/l7rule-show-curl Normal file
View File

@ -0,0 +1 @@
curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules/16621dbb-a736-4888-a57a-3ecd53df784c

17
api-ref/source/v2/examples/l7rule-show-response.json Normal file
View File

@ -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"
}
}

1
api-ref/source/v2/examples/l7rule-update-curl Normal file
View File

@ -0,0 +1 @@
curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <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

9
api-ref/source/v2/examples/l7rule-update-request.json Normal file
View File

@ -0,0 +1,9 @@
{
"rule": {
"compare_type": "REGEX",
"invert": true,
"type": "PATH",
"value": "/images/special*",
"admin_state_up": true
}
}

17
api-ref/source/v2/examples/l7rule-update-response.json Normal file
View File

@ -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"
}
}

1
api-ref/source/v2/examples/l7rules-list-curl Normal file
View File

@ -0,0 +1 @@
curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules

18
api-ref/source/v2/examples/l7rules-list-response.json Normal file
View File

@ -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"
}
]
}

5
api-ref/source/v2/index.rst
View File

@ -40,3 +40,8 @@ Health Monitor
L7 Policies
-----------
.. include:: l7policy.inc
--------
L7 Rules
--------
.. include:: l7rule.inc

348
api-ref/source/v2/l7rule.inc Normal file
View File

@ -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<prov_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.