API support for CRUD node.shard

- Basic support and testing for CRUD for node.shard.
- Policy checking for update node.shard.
- New API endpoint: GET /v1/shards
- Policy checking for GET /v1/shards
- Support for querying for nodes in a list of shards

Story: 2010378
Task: 46624
Change-Id: I385594339028c20cfc83fdcc4cbbec107efdacff

5 files changed, 115 insertions, 1 deletions

diff --git a/api-ref/source/baremetal-api-v1-nodes.inc b/api-ref/source/baremetal-api-v1-nodes.inc
index 2ebbd2c5d..4734c1b73 100644
--- a/api-ref/source/baremetal-api-v1-nodes.inc
+++ b/api-ref/source/baremetal-api-v1-nodes.inc
@@ -104,6 +104,9 @@ supplied when the Node is created, or the resource may be updated later.
 .. versionadded:: 1.65
   Introduced the ``lessee`` field.
 
+.. versionadded:: 1.82
+  Introduced the ``shard`` field.
+
 Normal response codes: 201
 
 Error codes: 400,403,406
@@ -135,6 +138,7 @@ Request
     - owner: owner
     - description: req_n_description
     - lessee: lessee
+    - shard: shard
     - automated_clean: req_automated_clean
     - bios_interface: req_bios_interface
     - chassis_uuid: req_chassis_uuid
@@ -161,7 +165,7 @@ and any defaults added for non-specified fields. Most fields default to "null"
 or "".
 
 The list and example below are representative of the response as of API
-microversion 1.48.
+microversion 1.81.
 
 .. rest_parameters:: parameters.yaml
 
@@ -213,6 +217,7 @@ microversion 1.48.
     - conductor: conductor
     - owner: owner
     - lessee: lessee
+    - shard: shard
     - description: n_description
     - allocation_uuid: allocation_uuid
     - automated_clean: automated_clean
@@ -280,6 +285,9 @@ provision state, and maintenance setting for each Node.
 .. versionadded:: 1.65
   Introduced the ``lessee`` field.
 
+.. versionadded:: 1.82
+  Introduced the ``shard`` field.
+
 Normal response codes: 200
 
 Error codes: 400,403,406
@@ -300,6 +308,7 @@ Request
    - fault: r_fault
    - owner: owner
    - lessee: lessee
+   - shard: req_shard
    - description_contains: r_description_contains
    - fields: fields
    - limit: limit
@@ -371,6 +380,9 @@ Nova instance, eg. with a request to ``v1/nodes/detail?instance_uuid={NOVA INSTA
 .. versionadded:: 1.65
   Introduced the ``lessee`` field.
 
+.. versionadded:: 1.82
+  Introduced the ``shard`` field.
+
 Normal response codes: 200
 
 Error codes: 400,403,406
@@ -391,6 +403,7 @@ Request
    - conductor: r_conductor
    - owner: owner
    - lessee: lessee
+   - shard: req_shard
    - description_contains: r_description_contains
    - limit: limit
    - marker: marker
@@ -450,6 +463,7 @@ Response
     - protected_reason: protected_reason
     - owner: owner
     - lessee: lessee
+    - shard: shard
     - description: n_description
     - conductor: conductor
     - allocation_uuid: allocation_uuid
@@ -508,6 +522,9 @@ only the specified set.
 .. versionadded:: 1.66
   Introduced the ``network_data`` field.
 
+.. versionadded:: 1.82
+  Introduced the ``shard`` field.
+
 Normal response codes: 200
 
 Error codes: 400,403,404,406
@@ -573,6 +590,7 @@ Response
     - protected_reason: protected_reason
     - owner: owner
     - lessee: lessee
+    - shard: shard
     - description: n_description
     - conductor: conductor
     - allocation_uuid: allocation_uuid
@@ -600,6 +618,9 @@ managed through sub-resources.
 .. versionadded:: 1.51
   Introduced the ability to set/unset a node's description.
 
+.. versionadded:: 1.82
+  Introduced the ability to set/unset a node's shard.
+
 Normal response codes: 200
 
 Error codes: 400,403,404,406,409
@@ -670,6 +691,7 @@ Response
     - protected_reason: protected_reason
     - owner: owner
     - lessee: lessee
+    - shard: shard
     - description: n_description
     - conductor: conductor
     - allocation_uuid: allocation_uuid
diff --git a/api-ref/source/baremetal-api-v1-shards.inc b/api-ref/source/baremetal-api-v1-shards.inc
new file mode 100644
index 000000000..c051e506e
--- /dev/null
+++ b/api-ref/source/baremetal-api-v1-shards.inc
@@ -0,0 +1,56 @@
+.. -*- rst -*-
+
+======
+Shards
+======
+
+This section describes an API endpoint returning the population of shards
+among nodes in the Bare Metal Service. Shards are a way to group nodes in the
+Bare Metal service. They are used by API clients to separate nodes into groups,
+allowing horizontal scaling.
+
+Shards are not directly added and removed from the Bare Metal service. Instead,
+operators can configure a node into a given shard by setting the ``shard`` key
+to any unique string value representing the shard.
+
+.. note::
+    The Bare Metal Service does not use shards directly. It instead relies on
+    API clients and external services to use shards to group nodes into smaller
+    areas of responsibility.
+
+
+Shards
+======
+
+.. rest_method:: GET /v1/shards
+
+.. versionadded:: 1.82
+
+The ``/v1/shards`` endpoint exists to allow querying the distribution of nodes
+between all defined shards.
+
+Normal response codes: 200
+
+Error response codes: 400 403 404
+
+Request
+-------
+
+No request parameters are accepted by this endpoint.
+
+Response
+--------
+
+Returns a list of shards and the count of nodes assigned to each. The
+list is sorted by descending count.
+
+.. rest_parameters:: parameters.yaml
+
+    - name: shard_name
+    - count: shard_count
+
+Response Example
+----------------
+
+.. literalinclude:: samples/shards-list-response.json
+   :language: javascript
diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index 50c6a6d14..bb41ba6fd 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -28,6 +28,7 @@
 .. include:: baremetal-api-v1-node-allocation.inc
 .. include:: baremetal-api-v1-deploy-templates.inc
 .. include:: baremetal-api-v1-nodes-history.inc
+.. include:: baremetal-api-v1-shards.inc
 .. NOTE(dtantsur): keep chassis close to the end since it's semi-deprecated
 .. include:: baremetal-api-v1-chassis.inc
 .. NOTE(dtantsur): keep misc last, since it covers internal API
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 361cca531..930d85f1e 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -1813,6 +1813,13 @@ req_resource_class_create:
   in: body
   required: false
   type: string
+req_shard:
+  description: |
+    Filter the list of returned Nodes, and only return the ones associated
+    with nodes in this specific shard(s), or an empty set if not found.
+  in: body
+  required: false
+  type: array
 req_standalone_ports_supported:
   description: |
     Indicates whether ports that are members of this portgroup can be
@@ -1938,6 +1945,22 @@ secure_boot:
     Indicates whether node is currently booted with secure_boot turned on.
   in: body
   type: boolean
+shard:
+  description: |
+    A string indicating the shard this node belongs to.
+  in: body
+  type: string
+shard_count:
+  description: |
+    The number of nodes with this current string as their assigned shard value.
+  in: body
+  type: integer
+shard_name:
+  description: |
+    The name of the shard. A value of "None" indicates the count of nodes with
+    an empty shard value.
+  in: body
+  type: string
 standalone_ports_supported:
   description: |
     Indicates whether ports that are members of this portgroup can be
diff --git a/api-ref/source/samples/shards-list-response.json b/api-ref/source/samples/shards-list-response.json
new file mode 100644
index 000000000..776dd324b
--- /dev/null
+++ b/api-ref/source/samples/shards-list-response.json
@@ -0,0 +1,12 @@
+{
+  "shards": [
+    {
+      "count": 47,
+      "name": "example_shard1",
+    },
+    {
+      "count": 46,
+      "name": "example_shard2"
+    }
+  ]
+}