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

@@ -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,13 @@ host_share_server_migration:
   in: body
   required: true
   type: string
+hosts_check_result:
+  description: |
+    (Admin only). Result received from each host in a security service update
+    check operation.
+  in: body
+  required: true
+  type: object
 id_13:
   description: |
     The share instance ID.
@@ -1659,6 +1672,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 must 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 +1731,13 @@ nondisruptive_server_migration:
   in: body
   required: true
   type: boolean
+operation_is_compatible:
+  description: |
+    Indicates the result of a check operation. If ``True`` indicates that the
+    addition/update of security service is possible.
+  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, being
+    ``add_security_service`` or ``update_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 network should ignore previous check results, and check the
+    operation's compatibility again.
+  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 network or 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 the share network supports its security services being updated
+    when it is already being used.
+  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.
@@ -2805,6 +2882,14 @@ share_server_id:
   in: body
   required: true
   type: string
+share_server_security_service_update_support:
+  description: |
+    Whether the share server supports its security services being updated after
+    its creation.
+  in: body
+  required: true
+  type: boolean
+  min_version: 2.63
 share_server_show_identifier:
   description: |
     The identifier of the share server in the back-end storage system.

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
+    }
+}

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": true
+    }
+}

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

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",

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

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",

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

api-ref/source/samples/share-network-reset-state-request.json

@@ -0,0 +1,5 @@
+{
+    "reset_status": {
+        "status": "active"
+    }
+}

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",

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

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",

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

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
+    }
+}

api-ref/source/samples/share-network-update-security-service-check-response.json

@@ -0,0 +1,11 @@
+{
+    "compatible": true,
+    "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
+    }
+}

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

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
+    }
+}

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

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

api-ref/source/samples/share-servers-list-response.json

@@ -8,7 +8,8 @@
             "share_network_name": "net_my",
             "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
         }
     ]
 }

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,13 @@ 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 use the `check add API
+    <https://docs.openstack.org/api-ref/shared-file-system/#check-share-network-security-service-add-since-api-v2-63>`_.
+
 Response codes
 --------------
 
@@ -357,6 +370,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 +442,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 +523,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 +576,256 @@ 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 and must have the
+``security_service_update_support`` capability set to ``True``.
+
+.. 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
+    <https://docs.openstack.org/api-ref/shared-file-system/#check-share-network-security-service-update-since-api-v2-63>`_.
+
+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
+
+
+.. _share-net-sec-service-update-check:
+
+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 an existing security service can be replaced on a share network that
+is in use. 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
+   - 404
+   - 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 a new security service can be added to a share network that's already
+in use. 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
+   - 404
+   - 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
+    - 401
+    - 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.

api-ref/source/share-servers.inc

@@ -80,6 +80,7 @@ Response parameters
    - host: host_share_server_body
    - updated_at: updated_at
    - share_network_subnet_id: share_network_subnet_id_share_server_body
+   - security_service_update_support: share_server_security_service_update_support
 
 Response example
 ----------------
@@ -134,6 +135,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 +281,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