From e5d138b2386af0c74b224863ab82b94754e7e25a Mon Sep 17 00:00:00 2001 From: silvacarloss Date: Mon, 29 Mar 2021 15:48:26 -0300 Subject: [PATCH] Add api-ref for security service update Updates the API reference to fit into the changes merged in the add/update security service in share networks feature. Change-Id: Id7dd45dc23c41c1ade28b042f87b216142b8a062 --- api-ref/source/parameters.yaml | 77 +++++ ...rk-add-security-service-check-request.json | 6 + ...k-add-security-service-check-response.json | 11 + ...network-add-security-service-response.json | 4 +- ...-network-create-response-with-subnets.json | 2 + .../share-network-create-response.json | 4 +- ...ecurity-service-response-with-subnets.json | 2 + ...work-remove-security-service-response.json | 4 +- .../share-network-reset-state-request.json | 5 + ...re-network-show-response-with-subnets.json | 2 + .../samples/share-network-show-response.json | 4 +- ...-network-update-response-with-subnets.json | 2 + .../share-network-update-response.json | 4 +- ...update-security-service-check-request.json | 7 + ...pdate-security-service-check-response.json | 11 + ...twork-update-security-service-request.json | 6 + ...work-update-security-service-response.json | 28 ++ .../samples/share-server-manage-response.json | 3 +- .../samples/share-server-show-response.json | 3 +- api-ref/source/share-networks.inc | 267 ++++++++++++++++++ api-ref/source/share-servers.inc | 2 + 21 files changed, 447 insertions(+), 7 deletions(-) create mode 100644 api-ref/source/samples/share-network-add-security-service-check-request.json create mode 100644 api-ref/source/samples/share-network-add-security-service-check-response.json create mode 100644 api-ref/source/samples/share-network-reset-state-request.json create mode 100644 api-ref/source/samples/share-network-update-security-service-check-request.json create mode 100644 api-ref/source/samples/share-network-update-security-service-check-response.json create mode 100644 api-ref/source/samples/share-network-update-security-service-request.json create mode 100644 api-ref/source/samples/share-network-update-security-service-response.json diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 22e47f7ef1..a9c7530007 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -881,6 +881,12 @@ created_at: in: body required: true type: string +current_share_network_security_service_id: + description: | + The id of a security service that is currently attached to a share network. + in: body + required: true + type: string deny_access: description: | The ``deny_access`` object. @@ -1230,6 +1236,12 @@ host_share_server_migration: in: body required: true type: string +hosts_check_result: + description: | + Result received from each host in a check operation. + in: body + required: true + type: object id_13: description: | The share instance ID. @@ -1659,6 +1671,13 @@ new_share_network_id_server_migration: in: body required: false type: string +new_share_network_security_service_id: + description: | + The id of a security service that is intended to be attached to a share + network after a share network security service update operation. + in: body + required: true + type: string new_share_type_id: description: | If willing to retype the share so it can be allocated in the @@ -1711,6 +1730,14 @@ nondisruptive_server_migration: in: body required: true type: boolean +operation_is_compatible: + description: | + Indicates the result of a check operation. If ``True``, means that all + share backends that would be involved in the proccess can hold such + operation. + in: body + required: true + type: boolean os-share-type-access:is_public: description: | Indicates whether a share type is publicly @@ -2149,6 +2176,25 @@ requested_capabilities: in: body required: true type: object +requested_check_operation: + description: | + Information about the requested operation. + in: body + required: true + type: object +requested_operation: + description: | + Data about the operation that was requested. + in: body + required: true + type: object +requested_operation_name: + description: | + The name of the check operation that was triggered in manila, being + ``add_security_service`` or ``check_security_service``. + in: body + required: true + type: string required_extra_specs: description: | The required extra specifications for the share @@ -2158,6 +2204,14 @@ required_extra_specs: in: body required: true type: object +reset_operation: + description: | + Whether a share network security service check update or add operation for + a given share server should ignore previous check results, and query all + enable share backends again or not. + in: body + required: true + type: boolean reset_status: description: | The ``reset_status`` object. @@ -2289,6 +2343,13 @@ security_service_type_request: in: body required: false type: string +security_service_update_support: + description: | + Whether a share server supports security service updates or not. + in: body + required: true + type: boolean + min_version: 2.63 security_service_user: description: | The security service user or group name that is used by the project. @@ -2605,6 +2666,14 @@ share_network_security_service_id: in: body required: true type: string +share_network_security_service_update_support: + description: | + Whether all share servers within the share network support updating a + security service when a share network is already being used or not. + in: body + required: true + type: boolean + min_version: 2.63 share_network_share_network_subnets: description: | A list of share network subnets that pertain to the related share network. @@ -2612,6 +2681,14 @@ share_network_share_network_subnets: required: true type: array min_version: 2.51 +share_network_status: + description: | + The status of a share network. Possible values are: ``active``, ``error`` + or ``network_change``. + in: body + required: true + type: string + min_version: 2.63 share_network_subnet_availability_zone: description: | The name of the availability zone that the share network subnet belongs to. diff --git a/api-ref/source/samples/share-network-add-security-service-check-request.json b/api-ref/source/samples/share-network-add-security-service-check-request.json new file mode 100644 index 0000000000..35774e34c8 --- /dev/null +++ b/api-ref/source/samples/share-network-add-security-service-check-request.json @@ -0,0 +1,6 @@ +{ + "add_security_service_check": { + "security_service_id": "8971c5f6-52ec-4c53-bf6a-3fae38a9221e", + "reset_operation": false + } +} \ No newline at end of file diff --git a/api-ref/source/samples/share-network-add-security-service-check-response.json b/api-ref/source/samples/share-network-add-security-service-check-response.json new file mode 100644 index 0000000000..60cf9313e2 --- /dev/null +++ b/api-ref/source/samples/share-network-add-security-service-check-response.json @@ -0,0 +1,11 @@ +{ + "compatible": true, + "requested_operation": { + "operation": "add_security_service", + "current_security_service": null, + "new_security_service": "8971c5f6-52ec-4c53-bf6a-3fae38a9221e" + }, + "hosts_check_result": { + "ubuntu@dummy2": null + } +} \ No newline at end of file diff --git a/api-ref/source/samples/share-network-add-security-service-response.json b/api-ref/source/samples/share-network-add-security-service-response.json index 6a40160a1d..d1e8bc3111 100644 --- a/api-ref/source/samples/share-network-add-security-service-response.json +++ b/api-ref/source/samples/share-network-add-security-service-response.json @@ -13,6 +13,8 @@ "network_type": null, "description": null, "gateway": null, - "mtu": null + "mtu": null, + "security_service_update_support": true, + "status": "active" } } diff --git a/api-ref/source/samples/share-network-create-response-with-subnets.json b/api-ref/source/samples/share-network-create-response-with-subnets.json index a90e2afe00..ee3251bd0c 100644 --- a/api-ref/source/samples/share-network-create-response-with-subnets.json +++ b/api-ref/source/samples/share-network-create-response-with-subnets.json @@ -6,6 +6,8 @@ "id": "77eb3421-4549-4789-ac39-0d5185d68c29", "project_id": "e10a683c20da41248cfd5e1ab3d88c62", "description": "This is my share network", + "security_service_update_support": true, + "status": "active", "share_network_subnets": [ { "id": "91cc63b5-6c61-4078-b054-560923709654", diff --git a/api-ref/source/samples/share-network-create-response.json b/api-ref/source/samples/share-network-create-response.json index adb8a595a1..b9581af8db 100644 --- a/api-ref/source/samples/share-network-create-response.json +++ b/api-ref/source/samples/share-network-create-response.json @@ -13,6 +13,8 @@ "network_type": null, "description": "This is my share network", "gateway": null, - "mtu": null + "mtu": null, + "security_service_update_support": true, + "status": "active" } } diff --git a/api-ref/source/samples/share-network-remove-security-service-response-with-subnets.json b/api-ref/source/samples/share-network-remove-security-service-response-with-subnets.json index ba0fff562e..77110ea035 100644 --- a/api-ref/source/samples/share-network-remove-security-service-response-with-subnets.json +++ b/api-ref/source/samples/share-network-remove-security-service-response-with-subnets.json @@ -6,6 +6,8 @@ "id": "d8ae6799-2567-4a89-aafb-fa4424350d2b", "project_id": "16e1ab15c35a457e9c2b2aa189f544e1", "description": null, + "security_service_update_support": true, + "status": "active", "share_network_subnets": [ { "id": "e4db03dc-6041-4c6a-a8f9-80bb4141a1eb", diff --git a/api-ref/source/samples/share-network-remove-security-service-response.json b/api-ref/source/samples/share-network-remove-security-service-response.json index 6a40160a1d..d1e8bc3111 100644 --- a/api-ref/source/samples/share-network-remove-security-service-response.json +++ b/api-ref/source/samples/share-network-remove-security-service-response.json @@ -13,6 +13,8 @@ "network_type": null, "description": null, "gateway": null, - "mtu": null + "mtu": null, + "security_service_update_support": true, + "status": "active" } } diff --git a/api-ref/source/samples/share-network-reset-state-request.json b/api-ref/source/samples/share-network-reset-state-request.json new file mode 100644 index 0000000000..b364293db6 --- /dev/null +++ b/api-ref/source/samples/share-network-reset-state-request.json @@ -0,0 +1,5 @@ +{ + "reset_status": { + "status": "active" + } +} \ No newline at end of file diff --git a/api-ref/source/samples/share-network-show-response-with-subnets.json b/api-ref/source/samples/share-network-show-response-with-subnets.json index c1c05954af..494e321280 100644 --- a/api-ref/source/samples/share-network-show-response-with-subnets.json +++ b/api-ref/source/samples/share-network-show-response-with-subnets.json @@ -5,6 +5,8 @@ "project_id": "16e1ab15c35a457e9c2b2aa189f544e1", "created_at": "2019-10-02T17:49:43.000000", "description": null, + "security_service_update_support": true, + "status": "active", "share_network_subnets": [ { "id": "e4db03dc-6041-4c6a-a8f9-80bb4141a1eb", diff --git a/api-ref/source/samples/share-network-show-response.json b/api-ref/source/samples/share-network-show-response.json index c8a9e76693..51d987d749 100644 --- a/api-ref/source/samples/share-network-show-response.json +++ b/api-ref/source/samples/share-network-show-response.json @@ -13,6 +13,8 @@ "network_type": null, "description": "descr", "gateway": null, - "mtu": null + "mtu": null, + "security_service_update_support": true, + "status": "active" } } diff --git a/api-ref/source/samples/share-network-update-response-with-subnets.json b/api-ref/source/samples/share-network-update-response-with-subnets.json index b1a859029f..a5a93824ac 100644 --- a/api-ref/source/samples/share-network-update-response-with-subnets.json +++ b/api-ref/source/samples/share-network-update-response-with-subnets.json @@ -6,6 +6,8 @@ "created_at": "2019-11-12T17:18:10.000000", "updated_at": null, "description": "i'm adding a description", + "security_service_update_support": true, + "status": "active", "share_network_subnets": [ { "id": "687ab361-5c40-406e-945c-6326254782d4", diff --git a/api-ref/source/samples/share-network-update-response.json b/api-ref/source/samples/share-network-update-response.json index f5e11d6904..c2abec4f58 100644 --- a/api-ref/source/samples/share-network-update-response.json +++ b/api-ref/source/samples/share-network-update-response.json @@ -13,6 +13,8 @@ "network_type": null, "description": "i'm adding a description", "gateway": null, - "mtu": null + "mtu": null, + "security_service_update_support": true, + "status": "active" } } diff --git a/api-ref/source/samples/share-network-update-security-service-check-request.json b/api-ref/source/samples/share-network-update-security-service-check-request.json new file mode 100644 index 0000000000..f28c1c600e --- /dev/null +++ b/api-ref/source/samples/share-network-update-security-service-check-request.json @@ -0,0 +1,7 @@ +{ + "update_security_service_check": { + "current_service_id": "8971c5f6-52ec-4c53-bf6a-3fae38a9221e", + "new_service_id": "6cff8d33-f73b-483f-88af-e5429ad9daef", + "reset_operation": false + } +} \ No newline at end of file diff --git a/api-ref/source/samples/share-network-update-security-service-check-response.json b/api-ref/source/samples/share-network-update-security-service-check-response.json new file mode 100644 index 0000000000..8395d3647d --- /dev/null +++ b/api-ref/source/samples/share-network-update-security-service-check-response.json @@ -0,0 +1,11 @@ +{ + "compatible": null, + "requested_operation": { + "operation": "update_security_service", + "current_security_service": "8971c5f6-52ec-4c53-bf6a-3fae38a9221e", + "new_security_service": "6cff8d33-f73b-483f-88af-e5429ad9daef" + }, + "hosts_check_result": { + "ubuntu@dummy2": true + } +} \ No newline at end of file diff --git a/api-ref/source/samples/share-network-update-security-service-request.json b/api-ref/source/samples/share-network-update-security-service-request.json new file mode 100644 index 0000000000..f4ca8fef90 --- /dev/null +++ b/api-ref/source/samples/share-network-update-security-service-request.json @@ -0,0 +1,6 @@ +{ + "update_security_service": { + "current_service_id": "8971c5f6-52ec-4c53-bf6a-3fae38a9221e", + "new_service_id": "6cff8d33-f73b-483f-88af-e5429ad9daef" + } +} \ No newline at end of file diff --git a/api-ref/source/samples/share-network-update-security-service-response.json b/api-ref/source/samples/share-network-update-security-service-response.json new file mode 100644 index 0000000000..8e97ef20da --- /dev/null +++ b/api-ref/source/samples/share-network-update-security-service-response.json @@ -0,0 +1,28 @@ +{ + "share_network": { + "id": "1e3f43b2-2290-4fb8-bdc3-fb741c336c2a", + "name": "my_share_network", + "project_id": "838f27f65c1d43baa37743c6884958ce", + "created_at": "2021-03-25T17: 48: 51.925433", + "updated_at": "2021-03-29T15: 06: 19.464021", + "description": null, + "share_network_subnets": [ + { + "id": "14f7f4f6-b6b6-4b7e-a89c-1040700f3166", + "availability_zone": null, + "created_at": "2021-03-25T17: 48: 52.014525", + "updated_at": "2021-03-29T14: 50: 56.993391", + "segmentation_id": 1010, + "neutron_net_id": null, + "neutron_subnet_id": null, + "ip_version": 4, + "cidr": "10.0.0.0/24", + "network_type": "vlan", + "mtu": 1500, + "gateway": "10.0.0.1" + } + ], + "status": "network_change", + "security_service_update_support": true + } +} \ No newline at end of file diff --git a/api-ref/source/samples/share-server-manage-response.json b/api-ref/source/samples/share-server-manage-response.json index 4ada50654f..ac93bb99ca 100644 --- a/api-ref/source/samples/share-server-manage-response.json +++ b/api-ref/source/samples/share-server-manage-response.json @@ -11,6 +11,7 @@ "created_at": "2019-03-06T11:59:41.000000", "backend_details": {}, "is_auto_deletable": false, - "identifier": "4ef3507e-0513-4140-beda-f619ab30d424" + "identifier": "4ef3507e-0513-4140-beda-f619ab30d424", + "security_service_update_support": true } } \ No newline at end of file diff --git a/api-ref/source/samples/share-server-show-response.json b/api-ref/source/samples/share-server-show-response.json index c325f41dec..3815a4775f 100644 --- a/api-ref/source/samples/share-server-show-response.json +++ b/api-ref/source/samples/share-server-show-response.json @@ -18,6 +18,7 @@ "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c", "share_network_subnet_id": "f53252f0-c2a9-4d7c-af41-1c6f3cfb3af3", "project_id": "16e1ab15c35a457e9c2b2aa189f544e1", - "id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73" + "id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73", + "security_service_update_support": true } } diff --git a/api-ref/source/share-networks.inc b/api-ref/source/share-networks.inc index 54c8752101..2abb0728bb 100644 --- a/api-ref/source/share-networks.inc +++ b/api-ref/source/share-networks.inc @@ -137,6 +137,8 @@ Response parameters - gateway: share_network_gateway - mtu: share_network_mtu - share_network_subnets: share_network_share_network_subnets + - security_service_update_support: share_network_security_service_update_support + - status: share_network_status Response example ---------------- @@ -199,6 +201,8 @@ Response parameters - gateway: share_network_gateway - mtu: share_network_mtu - share_network_subnets: share_network_share_network_subnets + - security_service_update_support: share_network_security_service_update_support + - status: share_network_status Response example ---------------- @@ -283,6 +287,8 @@ Response parameters - gateway: share_network_gateway - mtu: share_network_mtu - share_network_subnets: share_network_share_network_subnets + - security_service_update_support: share_network_security_service_update_support + - status: share_network_status Response example ---------------- @@ -306,6 +312,12 @@ Add security service to share network Adds a security service to a share network. +.. note:: + As of API version 2.63, manila allows adding security services to share + networks that are being used if supported by the share backends. Before + requesting to add a security service to a share network that is in use, + make sure to call the API to check if the backends can hold such operation. + Response codes -------------- @@ -357,6 +369,8 @@ Response parameters - gateway: share_network_gateway - mtu: share_network_mtu - share_network_subnets: share_network_share_network_subnets + - security_service_update_support: share_network_security_service_update_support + - status: share_network_status Response example ---------------- @@ -427,6 +441,8 @@ Response parameters - updated_at: updated_at - gateway: share_network_gateway - mtu: share_network_mtu + - security_service_update_support: share_network_security_service_update_support + - status: share_network_status Response example ---------------- @@ -506,6 +522,8 @@ Response parameters - updated_at: updated_at - gateway: share_network_gateway - mtu: share_network_mtu + - security_service_update_support: share_network_security_service_update_support + - status: share_network_status Response example ---------------- @@ -557,3 +575,252 @@ Request - project_id: project_id_path - share_network_id: share_network_id_path + + +Update share network security service (since API v2.63) +======================================================= + +.. rest_method:: POST /v2/share-networks/{share_network_id}/action + +.. versionadded:: 2.63 + +Replaces a security service in a share network. Both current and the new +security service must have the same type. + +.. important:: + Before calling the update share network security service API, make sure + to check if the share backends within the share network can hold the + operation, through the check update API. + + +Response codes +-------------- + +.. rest_status_code:: success status.yaml + + - 202 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 404 + - 409 + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id_path + - share_network_id: share_network_id_path + - current_security_service: current_share_network_security_service_id + - new_security_service: new_share_network_security_service_id + +Request example +--------------- + +.. literalinclude:: samples/share-network-update-security-service-request.json + :language: javascript + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - id: share_network_id + - project_id: project_id + - neutron_net_id: neutron_net_id + - neutron_subnet_id: neutron_subnet_id + - network_type: network_type + - segmentation_id: segmentation_id + - cidr: cidr + - ip_version: ip_version + - name: name + - description: description + - created_at: created_at + - updated_at: updated_at + - gateway: share_network_gateway + - mtu: share_network_mtu + - share_network_subnets: share_network_share_network_subnets + - security_service_update_support: share_network_security_service_update_support + - status: share_network_status + +Response example +---------------- + +.. literalinclude:: samples/share-network-update-security-service-response.json + :language: javascript + + +Check share network security service update (since API v2.63) +============================================================= + +.. rest_method:: POST /v2/share-networks/{share_network_id}/action + +.. versionadded:: 2.63 + +Checks if all the share backends that at the moment are tied to the share +network can hold a update share network security service operation. This +operation must be triggered before an actual request to update a share network +security service is requested. + + +Response codes +-------------- + +.. rest_status_code:: success status.yaml + + - 202 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 409 + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id_path + - share_network_id: share_network_id_path + - current_service_id: current_share_network_security_service_id + - new_service_id: new_share_network_security_service_id + - reset_operation: reset_operation + +Request example +--------------- + +.. literalinclude:: samples/share-network-update-security-service-check-request.json + :language: javascript + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - operation: requested_operation_name + - current_security_service: current_share_network_security_service_id + - new_security_service: new_share_network_security_service_id + - compatible: operation_is_compatible + - requested_operation: requested_check_operation + - hosts_check_result: hosts_check_result + +Response example +---------------- + +.. literalinclude:: samples/share-network-update-security-service-check-response.json + :language: javascript + + +Check share network security service add (since API v2.63) +========================================================== + +.. rest_method:: POST /v2/share-networks/{share_network_id}/action + +.. versionadded:: 2.63 + +Checks if all the share backends that at the moment are tied to the share +network can hold adding a security service to an in use share network. This +operation must be triggered before an actual request to add a security service +to an in use share network. + + +Response codes +-------------- + +.. rest_status_code:: success status.yaml + + - 202 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 409 + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id_path + - share_network_id: share_network_id_path + - security_service_id: current_share_network_security_service_id + - reset_operation: reset_operation + +Request example +--------------- + +.. literalinclude:: samples/share-network-add-security-service-check-request.json + :language: javascript + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - operation: requested_operation_name + - current_security_service: current_share_network_security_service_id + - new_security_service: new_share_network_security_service_id + - compatible: operation_is_compatible + - requested_operation: requested_operation + - hosts_check_result: hosts_check_result + +Response example +---------------- + +.. literalinclude:: samples/share-network-add-security-service-check-response.json + :language: javascript + + +Reset status (since API v2.63) +============================== + +.. rest_method:: POST /v2/share-networks/{share_network_id}/action + +.. versionadded:: 2.63 + +Resets a share network status. + +Administrator only. Explicitly updates the state of a share network. + +Response codes +-------------- + +.. rest_status_code:: success status.yaml + + - 202 + +.. rest_status_code:: error status.yaml + + - 400 + - 403 + - 404 + +Request parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - project_id: project_id_path + - share_network_id: share_network_id_path + - status: share_network_status + +Request example +--------------- + +.. literalinclude:: samples/share-network-reset-state-request.json + :language: javascript + + +Response parameters +------------------- + +There is no body content for the response. diff --git a/api-ref/source/share-servers.inc b/api-ref/source/share-servers.inc index 6aa4b8e856..5b4ce7a531 100644 --- a/api-ref/source/share-servers.inc +++ b/api-ref/source/share-servers.inc @@ -134,6 +134,7 @@ Response parameters - identifier: share_server_show_identifier - is_auto_deletable: share_server_show_is_auto_deletable - share_network_subnet_id: share_network_subnet_id_share_server_body + - security_service_update_support: security_service_update_support Response example ---------------- @@ -279,6 +280,7 @@ Response parameters - is_auto_deletable: is_auto_deletable - identifier: identifier - share_network_subnet_id: share_network_subnet_id_manage_server_body + - security_service_update_support: security_service_update_support Response examples