Use uuid for id in os-services API

This patch introduces a new microversion to identify services by uuid
instead of id, to ensure uniqueness across cells. GET /os-services
returns uuid in the id field, and uuid must be provided to delete a
service with DELETE /os-services/{service_uuid}.

The old PUT /os-services/* APIs are now capped and replaced
with a new PUT /os-services/{service_uuid} which takes a uuid path
parameter to uniquely identify the service to update. It also restricts
updates to nova-compute services only, since disabling or forcing-down
a non-compute service like nova-scheduler doesn't make sense as it
doesn't do anything.

The new update() method in this microversion also avoids trying to
re-use the existing private action methods like _enable and _disable
since those are predicated on looking up the service by host/binary,
are confusing to follow for code flow, and just don't really make sense
with a pure PUT resource update method.

Part of blueprint service-hyper-uuid-in-api

Co-Authored-By: Matt Riedemann <mriedem.os@gmail.com>

Change-Id: I45494a4df7ee4454edb3ef8e7c5817d8c4e9e5ad

api-ref/source/os-services.inc

@@ -40,15 +40,16 @@ Response
 .. rest_parameters:: parameters.yaml
 
   - services: services
-  - id: service_id_body
+  - id: service_id_body_2_52
+  - id: service_id_body_2_53
   - binary: binary
   - disabled_reason: disabled_reason_body
   - host: host_name_body
   - state: service_state
   - status: service_status
   - updated_at: updated
   - zone: OS-EXT-AZ:availability_zone
-  - forced_down: forced_down
+  - forced_down: forced_down_2_11
 
 **Example List Compute Services**
 
@@ -64,6 +65,9 @@ Disables scheduling for a Compute service.
 
 Specify the service by its host name and binary name.
 
+.. note:: Starting with microversion 2.53 this API is superseded by
+          ``PUT /os-services/{service_id}``.
+
 Normal response codes: 200
 
 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
@@ -105,6 +109,9 @@ Logs information to the Compute service table about why a Compute service was di
 
 Specify the service by its host name and binary name.
 
+.. note:: Starting with microversion 2.53 this API is superseded by
+          ``PUT /os-services/{service_id}``.
+
 Normal response codes: 200
 
 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
@@ -148,6 +155,9 @@ Enables scheduling for a Compute service.
 
 Specify the service by its host name and binary name.
 
+.. note:: Starting with microversion 2.53 this API is superseded by
+          ``PUT /os-services/{service_id}``.
+
 Normal response codes: 200
 
 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
@@ -191,6 +201,9 @@ Action ``force-down`` available as of microversion 2.11.
 
 Specify the service by its host name and binary name.
 
+.. note:: Starting with microversion 2.53 this API is superseded by
+          ``PUT /os-services/{service_id}``.
+
 Normal response codes: 200
 
 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
@@ -202,7 +215,7 @@ Request
 
   - host: host_name_body
   - binary: binary
-  - forced_down: forced_down
+  - forced_down: forced_down_2_11
 
 **Example Update Forced Down**
 
@@ -217,7 +230,7 @@ Response
   - service: service
   - binary: binary
   - host: host_name_body
-  - forced_down: forced_down
+  - forced_down: forced_down_2_11
 
 |
 
@@ -226,6 +239,77 @@ Response
 .. literalinclude:: ../../doc/api_samples/os-services/v2.11/service-force-down-put-resp.json
    :language: javascript
 
+Update Compute Service
+======================
+
+.. rest_method:: PUT /os-services/{service_id}
+
+Update a compute service to enable or disable scheduling, including recording a
+reason why a compute service was disabled from scheduling. Set or unset the
+``forced_down`` flag for the service.
+
+This API is available starting with microversion 2.53.
+
+Normal response codes: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - service_id: service_id_path_2_53_no_version
+  - status: service_status_2_53_in
+  - disabled_reason: disabled_reason_2_53_in
+  - forced_down: forced_down_2_53_in
+
+**Example Disable Scheduling For A Compute Service (v2.53)**
+
+.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-disable-log-put-req.json
+   :language: javascript
+
+**Example Enable Scheduling For A Compute Service (v2.53)**
+
+.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-enable-put-req.json
+   :language: javascript
+
+**Example Update Forced Down (v2.53)**
+
+.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-force-down-put-req.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - service: service
+  - id: service_id_body_2_53_no_version
+  - binary: binary
+  - disabled_reason: disabled_reason_body
+  - host: host_name_body
+  - state: service_state
+  - status: service_status
+  - updated_at: updated
+  - zone: OS-EXT-AZ:availability_zone
+  - forced_down: forced_down_2_53_out
+
+**Example Disable Scheduling For A Compute Service (v2.53)**
+
+.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-disable-log-put-resp.json
+   :language: javascript
+
+**Example Enable Scheduling For A Compute Service (v2.53)**
+
+.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-enable-put-resp.json
+   :language: javascript
+
+**Example Update Forced Down (v2.53)**
+
+.. literalinclude:: ../../doc/api_samples/os-services/v2.53/service-force-down-put-resp.json
+   :language: javascript
+
 Delete Compute Service
 ======================
 
@@ -243,7 +327,8 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-  - service_id: service_id_path
+  - service_id: service_id_path_2_52
+  - service_id: service_id_path_2_53
 
 Response
 --------

api-ref/source/parameters.yaml

@@ -125,6 +125,8 @@ console_token:
   in: path
   required: true
   type: string
+# Used in the request path for PUT /os-services/disable-log-reason before
+# microversion 2.53.
 disabled_reason:
   description: |
     The reason for disabling a service.
@@ -283,12 +285,31 @@ server_id_path:
   in: path
   required: true
   type: string
-service_id_path:
+service_id_path_2_52:
   description: |
     The id of the service.
+
+    .. note:: This may not uniquely identify a service in a multi-cell
+              deployment.
   in: path
   required: true
   type: integer
+  max_version: 2.52
+service_id_path_2_53:
+  description: |
+    The id of the service as a uuid. This uniquely identifies the service in a
+    multi-cell deployment.
+  in: path
+  required: true
+  type: string
+  min_version: 2.53
+service_id_path_2_53_no_version:
+  description: |
+    The id of the service as a uuid. This uniquely identifies the service in a
+    multi-cell deployment.
+  in: path
+  required: true
+  type: string
 snapshot_id_path:
   description: |
     The UUID of the snapshot.
@@ -1898,6 +1919,15 @@ device_tag_nic_attachment:
   required: false
   type: string
   min_version: 2.49
+# Optional input parameter in the body for PUT /os-services/{service_id} added
+# in microversion 2.53.
+disabled_reason_2_53_in:
+  description: |
+    The reason for disabling a service. The minimum length is 1 and the
+    maximum length is 255. This may only be requested with ``status=disabled``.
+  in: body
+  required: false
+  type: string
 disabled_reason_body:
   description: |
     The reason for disabling a service.
@@ -2633,7 +2663,9 @@ force_snapshot:
   in: body
   required: false
   type: boolean
-forced_down:
+# This is both the request and response parameter for
+# PUT /os-services/force-down which was added in 2.11.
+forced_down_2_11:
   description: |
     Whether or not this service was forced down manually by an
     administrator. This value is useful to know that some 3rd party has
@@ -2642,6 +2674,26 @@ forced_down:
   required: true
   type: boolean
   min_version: 2.11
+# This is the optional request input parameter for
+# PUT /os-services/{service_id} added in 2.53.
+forced_down_2_53_in:
+  description: |
+    Whether or not this service was forced down manually by an
+    administrator. This value is useful to know that some 3rd party has
+    verified the service should be marked down.
+  in: body
+  required: false
+  type: boolean
+# This is the response output parameter for
+# PUT /os-services/{service_id} added in 2.53.
+forced_down_2_53_out:
+  description: |
+    Whether or not this service was forced down manually by an
+    administrator. This value is useful to know that some 3rd party has
+    verified the service should be marked down.
+  in: body
+  required: true
+  type: boolean
 forceDelete:
   description: |
     The action.
@@ -5064,6 +5116,26 @@ service_id_body:
   in: body
   required: true
   type: integer
+service_id_body_2_52:
+  description: |
+    The id of the service.
+  in: body
+  required: true
+  type: integer
+  max_version: 2.52
+service_id_body_2_53:
+  description: |
+    The id of the service as a uuid.
+  in: body
+  required: true
+  type: string
+  min_version: 2.53
+service_id_body_2_53_no_version:
+  description: |
+    The id of the service as a uuid.
+  in: body
+  required: true
+  type: string
 service_state:
   description: |
     The state of the service. One of ``up`` or ``down``.
@@ -5076,6 +5148,14 @@ service_status:
   in: body
   required: true
   type: string
+# This is an optional input parameter to PUT /os-services/{service_id} added
+# in microversion 2.53.
+service_status_2_53_in:
+  description: |
+    The status of the service. One of ``enabled`` or ``disabled``.
+  in: body
+  required: false
+  type: string
 services:
   description: |
     A list of service objects.

doc/api_samples/os-services/v2.53/service-disable-log-put-req.json

@@ -0,0 +1,4 @@
+{
+    "status": "disabled",
+    "disabled_reason": "maintenance"
+}

doc/api_samples/os-services/v2.53/service-disable-log-put-resp.json

@@ -0,0 +1,13 @@
+{
+    "service": {
+        "id": "e81d66a4-ddd3-4aba-8a84-171d1cb4d339",
+        "binary": "nova-compute",
+        "disabled_reason": "maintenance",
+        "host": "host1",
+        "state": "up",
+        "status": "disabled",
+        "updated_at": "2012-10-29T13:42:05.000000",
+        "forced_down": false,
+        "zone": "nova"
+    }
+}

doc/api_samples/os-services/v2.53/service-disable-put-req.json

@@ -0,0 +1,3 @@
+{
+    "status": "disabled"
+}

doc/api_samples/os-services/v2.53/service-disable-put-resp.json

@@ -0,0 +1,13 @@
+{
+    "service": {
+        "id": "e81d66a4-ddd3-4aba-8a84-171d1cb4d339",
+        "binary": "nova-compute",
+        "disabled_reason": null,
+        "host": "host1",
+        "state": "up",
+        "status": "disabled",
+        "updated_at": "2012-10-29T13:42:05.000000",
+        "forced_down": false,
+        "zone": "nova"
+    }
+}

doc/api_samples/os-services/v2.53/service-enable-put-req.json

@@ -0,0 +1,3 @@
+{
+    "status": "enabled"
+}

doc/api_samples/os-services/v2.53/service-enable-put-resp.json

@@ -0,0 +1,13 @@
+{
+    "service": {
+        "id": "e81d66a4-ddd3-4aba-8a84-171d1cb4d339",
+        "binary": "nova-compute",
+        "disabled_reason": null,
+        "host": "host1",
+        "state": "up",
+        "status": "enabled",
+        "updated_at": "2012-10-29T13:42:05.000000",
+        "forced_down": false,
+        "zone": "nova"
+    }
+}

doc/api_samples/os-services/v2.53/service-force-down-put-req.json

@@ -0,0 +1,3 @@
+{
+    "forced_down": true
+}

doc/api_samples/os-services/v2.53/service-force-down-put-resp.json

@@ -0,0 +1,13 @@
+{
+    "service": {
+        "id": "e81d66a4-ddd3-4aba-8a84-171d1cb4d339",
+        "binary": "nova-compute",
+        "disabled_reason": "test2",
+        "host": "host1",
+        "state": "down",
+        "status": "disabled",
+        "updated_at": "2012-10-29T13:42:05.000000",
+        "forced_down": true,
+        "zone": "nova"
+    }
+}