From 3a07a644ef1461640a0c0fec3479b580f27d3eac Mon Sep 17 00:00:00 2001 From: Slawek Kaplonski Date: Mon, 5 Jul 2021 11:26:41 +0200 Subject: [PATCH] [Docs] Add api-ref for the address groups Related-blueprint: bp/address-groups-in-sg-rules Change-Id: Ied4947ce0d52b84e501cac117f29882d6e6dba98 --- api-ref/source/v2/address-groups.inc | 305 ++++++++++++++++++ api-ref/source/v2/index.rst | 1 + api-ref/source/v2/parameters.yaml | 43 +++ .../address-group-add-addresses-request.json | 5 + .../address-group-add-addresses-response.json | 14 + .../address-group-create-request.json | 7 + .../address-group-create-response.json | 10 + ...ddress-group-remove-addresses-request.json | 5 + ...dress-group-remove-addresses-response.json | 13 + .../address-group-show-response.json | 10 + .../address-group-update-request.json | 5 + .../address-group-update-response.json | 14 + .../address-groups-list-response.json | 16 + 13 files changed, 448 insertions(+) create mode 100644 api-ref/source/v2/address-groups.inc create mode 100644 api-ref/source/v2/samples/address-groups/address-group-add-addresses-request.json create mode 100644 api-ref/source/v2/samples/address-groups/address-group-add-addresses-response.json create mode 100644 api-ref/source/v2/samples/address-groups/address-group-create-request.json create mode 100644 api-ref/source/v2/samples/address-groups/address-group-create-response.json create mode 100644 api-ref/source/v2/samples/address-groups/address-group-remove-addresses-request.json create mode 100644 api-ref/source/v2/samples/address-groups/address-group-remove-addresses-response.json create mode 100644 api-ref/source/v2/samples/address-groups/address-group-show-response.json create mode 100644 api-ref/source/v2/samples/address-groups/address-group-update-request.json create mode 100644 api-ref/source/v2/samples/address-groups/address-group-update-response.json create mode 100644 api-ref/source/v2/samples/address-groups/address-groups-list-response.json diff --git a/api-ref/source/v2/address-groups.inc b/api-ref/source/v2/address-groups.inc new file mode 100644 index 000000000..695841f2b --- /dev/null +++ b/api-ref/source/v2/address-groups.inc @@ -0,0 +1,305 @@ +.. -*- rst -*- + +============== +Address groups +============== + +Lists, creates, shows details for, updates, and deletes address groups. + +Show address group +================== + +.. rest_method:: GET /v2.0/address-groups/{address_group_id} + +Shows information for an address group. + +Use the ``fields`` query parameter to control which fields are returned in the response body. +For information, see `Filtering and Column Selection `__. + +Normal response codes: 200 + +Error response codes: 401, 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - address_group_id: address_group_id-path + - fields: fields + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - address_group: address_group + - id: address_group_id_body + - name: name + - description: description + - tenant_id: project_id + - project_id: project_id + - addresses: addresses + +Response Example +---------------- + +.. literalinclude:: samples/address-groups/address-group-show-response.json + :language: javascript + +Update an address group +======================= + +.. rest_method:: PUT /v2.0/address-groups/{address_group_id} + +Updates an address group. + +Normal response codes: 200 + +Error response codes: 400, 401, 403, 404, 412 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - address_group_id: address_group_id-path + - address_group: address_group + - name: name-request + - description: description + +Request Example +--------------- + +.. literalinclude:: samples/address-groups/address-group-update-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - address_group: address_group + - id: address_group_id_body + - name: name + - description: description + - tenant_id: project_id + - project_id: project_id + - addresses: addresses + +Response Example +---------------- + +.. literalinclude:: samples/address-groups/address-group-update-response.json + :language: javascript + +Delete an address group +======================= + +.. rest_method:: DELETE /v2.0/address-groups/{address_group_id} + +Deletes an address group. + +Normal response codes: 204 + +Error response codes: 401, 404, 412 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - address_group_id: address_group_id-path + +Response +-------- + +There is no body content for the response of a successful DELETE request. + +List address groups +=================== + +.. rest_method:: GET /v2.0/address-groups + +Lists address groups that the project has access to. + +Default policy settings return only the address groups owned by +the project of the user submitting the request, unless the +user has administrative role. + +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 `Filtering and Column Selection `__. + +Normal response codes: 200 + +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - id: id-query + - name: name-query + - tenant_id: project_id-query + - project_id: project_id-query + - sort_key: address_group-sort_key + - fields: fields + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - address_groups: address_groups + - id: address_group_id_body + - name: name + - tenant_id: project_id + - project_id: project_id + - addresses: addresses + +Response Example +---------------- + +.. literalinclude:: samples/address-groups/address-groups-list-response.json + :language: javascript + +Create address group +==================== + +.. rest_method:: POST /v2.0/address-groups + +Creates an address group. + +Normal response codes: 201 + +Error response codes: 400, 401, 403, 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - address_group_id: address_group_id-path + - address_group: address_group + - name: name-request + - description: description + - addresses: addresses + +Request Example +--------------- + +.. literalinclude:: samples/address-groups/address-group-create-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - address_group: address_group + - id: address_group_id_body + - name: name + - description: description + - tenant_id: project_id + - project_id: project_id + - addresses: addresses + +Response Example +---------------- + +.. literalinclude:: samples/address-groups/address-group-create-response.json + :language: javascript + +Add IP addresses to address group +================================= + +.. rest_method:: PUT /v2.0/address-group/{address_group_id}/add_addresses + +Atomically adds a set of IP addresses to the address group's already existing +addresses. + +Normal response codes: 200 + +Error response codes: 400, 401, 404, 412 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - address_group_id: address_group_id-path + - addresses: addresses + +Request Example +--------------- + +.. literalinclude:: samples/address-groups/address-group-add-addresses-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - address_group: address_group + - id: address_group_id_body + - name: name + - description: description + - tenant_id: project_id + - project_id: project_id + - addresses: addresses + +Response Example +---------------- + +.. literalinclude:: samples/address-groups/address-group-add-addresses-response.json + :language: javascript + +Remove IP addresses to address group +==================================== + +.. rest_method:: PUT /v2.0/address-group/{address_group_id}/remove_addresses + +Atomically removes a set of IP addresses from the address group's already +existing addresses. + +Normal response codes: 200 + +Error response codes: 400, 401, 404, 412 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - address_group_id: address_group_id-path + - addresses: addresses + +Request Example +--------------- + +.. literalinclude:: samples/address-groups/address-group-remove-addresses-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - address_group: address_group + - id: address_group_id_body + - name: name + - description: description + - tenant_id: project_id + - project_id: project_id + - addresses: addresses + +Response Example +---------------- + +.. literalinclude:: samples/address-groups/address-group-remove-addresses-response.json + :language: javascript diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst index 6a621996d..eb530b170 100644 --- a/api-ref/source/v2/index.rst +++ b/api-ref/source/v2/index.rst @@ -37,6 +37,7 @@ Layer 3 Networking ######## Security ######## +.. include:: address-groups.inc .. include:: fwaas-v2.inc .. include:: rbac-policy.inc .. include:: security-group-rules.inc diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index 38398c3a1..8f78be893 100644 --- a/api-ref/source/v2/parameters.yaml +++ b/api-ref/source/v2/parameters.yaml @@ -1,6 +1,12 @@ # variables in header # variables in path +address_group_id-path: + description: | + The ID of the address group. + in: path + required: true + type: string address_scope_id-path: description: | The ID of the address scope. @@ -298,6 +304,19 @@ vpnservice_id-path: required: true type: string # variables in query +address_group-sort_key: + description: | + Sorts by an address group attribute. You can specify multiple pairs of sort + key and sort direction query parameters. The sort keys are limited to: + + - ``id`` + - ``name`` + - ``project_id`` + - ``shared`` + - ``tenant_id`` + in: query + required: false + type: string address_scope-sort_key: description: | Sorts by an address scope attribute. You can specify multiple pairs of sort @@ -1527,6 +1546,24 @@ address: in: body required: true type: string +address_group: + description: | + An ``address group`` object. + in: body + required: true + type: object +address_group_id_body: + description: | + The ID of the address group. + in: body + required: true + type: string +address_groups: + description: | + A list of ``address group`` objects. + in: body + required: true + type: array address_scope: description: | An ``address scope`` object. @@ -1551,6 +1588,12 @@ address_scopes: in: body required: true type: array +addresses: + description: | + A list of IP addresses. + in: body + required: true + type: array admin_state_up: description: | The administrative state of the resource, which is diff --git a/api-ref/source/v2/samples/address-groups/address-group-add-addresses-request.json b/api-ref/source/v2/samples/address-groups/address-group-add-addresses-request.json new file mode 100644 index 000000000..c72a06bc2 --- /dev/null +++ b/api-ref/source/v2/samples/address-groups/address-group-add-addresses-request.json @@ -0,0 +1,5 @@ +{ + "address_group": { + "addresses": ["10.0.2.100/32"] + } +} diff --git a/api-ref/source/v2/samples/address-groups/address-group-add-addresses-response.json b/api-ref/source/v2/samples/address-groups/address-group-add-addresses-response.json new file mode 100644 index 000000000..4d33c59b4 --- /dev/null +++ b/api-ref/source/v2/samples/address-groups/address-group-add-addresses-response.json @@ -0,0 +1,14 @@ +{ + "address_group": { + "id": "9ace2ef6-bd57-426a-9223-cf1751d26db9", + "name": "doc-address-group", + "project_id": "c9a6f447205640e89523df967c26f4d5", + "addresses": [ + "10.0.1.34/32", + "10.0.2.100/32", + "192.168.100.0/24" + ], + "description": "AG description", + "tenant_id": "c9a6f447205640e89523df967c26f4d5" + } +} diff --git a/api-ref/source/v2/samples/address-groups/address-group-create-request.json b/api-ref/source/v2/samples/address-groups/address-group-create-request.json new file mode 100644 index 000000000..ef7cbf5b5 --- /dev/null +++ b/api-ref/source/v2/samples/address-groups/address-group-create-request.json @@ -0,0 +1,7 @@ +{ + "address_group": { + "addresses": [], + "name": "address-group-2", + "description": "docs example group" + } +} diff --git a/api-ref/source/v2/samples/address-groups/address-group-create-response.json b/api-ref/source/v2/samples/address-groups/address-group-create-response.json new file mode 100644 index 000000000..d54ebcf59 --- /dev/null +++ b/api-ref/source/v2/samples/address-groups/address-group-create-response.json @@ -0,0 +1,10 @@ +{ + "address_group": { + "id": "9f60873a-9bb0-45c9-ac25-b1d5d668d955", + "name": "address-group-2", + "project_id": "c9a6f447205640e89523df967c26f4d5", + "addresses": [], + "description": "docs example group", + "tenant_id": "c9a6f447205640e89523df967c26f4d5" + } +} diff --git a/api-ref/source/v2/samples/address-groups/address-group-remove-addresses-request.json b/api-ref/source/v2/samples/address-groups/address-group-remove-addresses-request.json new file mode 100644 index 000000000..c72a06bc2 --- /dev/null +++ b/api-ref/source/v2/samples/address-groups/address-group-remove-addresses-request.json @@ -0,0 +1,5 @@ +{ + "address_group": { + "addresses": ["10.0.2.100/32"] + } +} diff --git a/api-ref/source/v2/samples/address-groups/address-group-remove-addresses-response.json b/api-ref/source/v2/samples/address-groups/address-group-remove-addresses-response.json new file mode 100644 index 000000000..3d1f0ddbd --- /dev/null +++ b/api-ref/source/v2/samples/address-groups/address-group-remove-addresses-response.json @@ -0,0 +1,13 @@ +{ + "address_group": { + "id": "9ace2ef6-bd57-426a-9223-cf1751d26db9", + "name": "doc-address-group", + "project_id": "c9a6f447205640e89523df967c26f4d5", + "addresses": [ + "10.0.1.34/32", + "192.168.100.0/24" + ], + "description": "AG description", + "tenant_id": "c9a6f447205640e89523df967c26f4d5" + } +} diff --git a/api-ref/source/v2/samples/address-groups/address-group-show-response.json b/api-ref/source/v2/samples/address-groups/address-group-show-response.json new file mode 100644 index 000000000..97b7fdedf --- /dev/null +++ b/api-ref/source/v2/samples/address-groups/address-group-show-response.json @@ -0,0 +1,10 @@ +{ + "addresses": [ + "10.0.1.34/32", + "192.168.100.0/24" + ], + "description": "", + "id": "9ace2ef6-bd57-426a-9223-cf1751d26db9", + "name": "doc-address-group", + "project_id": "c9a6f447205640e89523df967c26f4d5" +} diff --git a/api-ref/source/v2/samples/address-groups/address-group-update-request.json b/api-ref/source/v2/samples/address-groups/address-group-update-request.json new file mode 100644 index 000000000..279c4429a --- /dev/null +++ b/api-ref/source/v2/samples/address-groups/address-group-update-request.json @@ -0,0 +1,5 @@ +{ + "address_group": { + "description": "AG description" + } +} diff --git a/api-ref/source/v2/samples/address-groups/address-group-update-response.json b/api-ref/source/v2/samples/address-groups/address-group-update-response.json new file mode 100644 index 000000000..4d33c59b4 --- /dev/null +++ b/api-ref/source/v2/samples/address-groups/address-group-update-response.json @@ -0,0 +1,14 @@ +{ + "address_group": { + "id": "9ace2ef6-bd57-426a-9223-cf1751d26db9", + "name": "doc-address-group", + "project_id": "c9a6f447205640e89523df967c26f4d5", + "addresses": [ + "10.0.1.34/32", + "10.0.2.100/32", + "192.168.100.0/24" + ], + "description": "AG description", + "tenant_id": "c9a6f447205640e89523df967c26f4d5" + } +} diff --git a/api-ref/source/v2/samples/address-groups/address-groups-list-response.json b/api-ref/source/v2/samples/address-groups/address-groups-list-response.json new file mode 100644 index 000000000..9b264a210 --- /dev/null +++ b/api-ref/source/v2/samples/address-groups/address-groups-list-response.json @@ -0,0 +1,16 @@ +{ + "address_groups": [ + { + "id": "9ace2ef6-bd57-426a-9223-cf1751d26db9", + "name": "doc-address-group", + "project_id": "c9a6f447205640e89523df967c26f4d5", + "addresses": [ + "10.0.1.34/32", + "10.0.2.100/32", + "192.168.100.0/24" + ], + "description": "", + "tenant_id": "c9a6f447205640e89523df967c26f4d5" + } + ] +}