openstack/neutron-lib
Code Issues Proposed changes

[Docs] Add api-ref for the address groups

Browse Source 
Related-blueprint: bp/address-groups-in-sg-rules
Change-Id: Ied4947ce0d52b84e501cac117f29882d6e6dba98
This commit is contained in:
Slawek Kaplonski 2021-07-05 11:26:41 +02:00
parent 303258fbfc
commit 3a07a644ef
13 changed files with 448 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

305
api-ref/source/v2/address-groups.inc Normal file
View File

@ -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 <https://wiki.openstack.org/wiki/Neutron/APIv2
-specification#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 <https://wiki.openstack.org/wiki/Neutron/APIv2
-specification#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

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

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

43
api-ref/source/v2/parameters.yaml
View File

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

5
api-ref/source/v2/samples/address-groups/address-group-add-addresses-request.json Normal file
View File

@ -0,0 +1,5 @@
{
"address_group": {
"addresses": ["10.0.2.100/32"]
}
}

14
api-ref/source/v2/samples/address-groups/address-group-add-addresses-response.json Normal file
View File

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

7
api-ref/source/v2/samples/address-groups/address-group-create-request.json Normal file
View File

@ -0,0 +1,7 @@
{
"address_group": {
"addresses": [],
"name": "address-group-2",
"description": "docs example group"
}
}

10
api-ref/source/v2/samples/address-groups/address-group-create-response.json Normal file
View File

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

5
api-ref/source/v2/samples/address-groups/address-group-remove-addresses-request.json Normal file
View File

@ -0,0 +1,5 @@
{
"address_group": {
"addresses": ["10.0.2.100/32"]
}
}

13
api-ref/source/v2/samples/address-groups/address-group-remove-addresses-response.json Normal file
View File

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

10
api-ref/source/v2/samples/address-groups/address-group-show-response.json Normal file
View File

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

5
api-ref/source/v2/samples/address-groups/address-group-update-request.json Normal file
View File

@ -0,0 +1,5 @@
{
"address_group": {
"description": "AG description"
}
}

14
api-ref/source/v2/samples/address-groups/address-group-update-response.json Normal file
View File

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

16
api-ref/source/v2/samples/address-groups/address-groups-list-response.json Normal file
View File

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