New agent attribute: resources_synced

Agents supporting the guaranteed minimum bandwidth feature need to share
their resource view with neutron-server and in turn with Placement too.
The resource information is synchronized to neutron-server via the
periodic agent heartbeat therefore transient synchronization errors are
fixed by the next heartbeat. But synchronization to Placement is not
done periodically, but on a (mostly) on demand basis. Therefore to fix
transient errors of the synchronization to Placement we must remember
the success/failure of the last synchronization attempt.

This change introduces a new boolean agent attribute: resources_synced

This attribute is:
* admin-only (just like the whole agent extension)
* read-only (it is only updated by the internal synchronization process)

If this attribute is not set then no synchronization to Placement ever
happened (which is the natural state of agents not tracking their
resources via Placement).

If it is False, then another successful synchronization is needed before
the contents of Placement can be considered up to date.

If it is True, then this agent's resources are up to date in Placement.

Change-Id: Ia3dea82fabe5e068192fbe931db8d341d3d37149
Needed-By: https://review.openstack.org/630999
Partial-Bug: #1578989
See-Also: https://review.openstack.org/502306 (nova spec)
See-Also: https://review.openstack.org/508149 (neutron spec)

api-ref/source/v2/agents.inc

@@ -6,6 +6,12 @@ Agents
 
 Lists, shows details for, updates, and deletes agents.
 
+Agent Resources Synced Extension
+================================
+
+The ``agent-resources-synced`` extension adds the ``resources_synced`` attribute
+to agents.
+
 Availability Zone Extension
 ===========================
 
@@ -63,6 +69,7 @@ Response Parameters
    - heartbeat_timestamp: heartbeat_timestamp
    - host: host
    - id: id
+   - resources_synced: agent_resources_synced
    - started_at: started_at
    - topic: topic
 
@@ -109,6 +116,7 @@ Response Parameters
    - heartbeat_timestamp: heartbeat_timestamp
    - host: host
    - id: id
+   - resources_synced: agent_resources_synced
    - started_at: started_at
    - topic: topic
 
@@ -162,6 +170,7 @@ Response Parameters
    - heartbeat_timestamp: heartbeat_timestamp
    - host: host
    - id: id
+   - resources_synced: agent_resources_synced
    - started_at: started_at
    - topic: topic
 

api-ref/source/v2/parameters.yaml

@@ -1484,6 +1484,19 @@ agent:
   required: true
   type: object
   type: string
+agent_resources_synced:
+  description: |
+    The value ``null`` means no resource view synchronization to Placement
+    was attempted. ``true`` / ``false`` values signify the success of
+    the last synchronization attempt. Therefore the relevant resources
+    in Placement can only be considered up to date if this attribute is
+    ``true``. This attribute is read-only, it is only supposed to be
+    updated internally, but it is readable for debugging purposes. Not all
+    agent types track resources via Placement, therefore the value ``null``
+    does not necessarily means there is an error in the system.
+  in: body
+  required: false
+  type: boolean
 agent_type:
   description: |
     The type of agent such as ``Open vSwitch agent`` or ``DHCP agent``.

api-ref/source/v2/samples/agents/agent-show-response.json

@@ -12,6 +12,7 @@
         "agent_type": "Open vSwitch agent",
         "started_at": "2017-09-12 19:35:38",
         "created_at": "2017-09-12 19:35:38",
+        "resources_synced": true,
         "configurations": {
             "ovs_hybrid_plug": true,
             "in_distributed_mode": false,

api-ref/source/v2/samples/agents/agent-update-response.json

@@ -12,6 +12,7 @@
         "agent_type": "Open vSwitch agent",
         "started_at": "2017-09-12 19:35:38",
         "created_at": "2017-09-12 19:35:38",
+        "resources_synced": true,
         "configurations": {
             "ovs_hybrid_plug": true,
             "in_distributed_mode": false,

api-ref/source/v2/samples/agents/agents-list-response.json

@@ -13,6 +13,7 @@
             "agent_type": "Open vSwitch agent",
             "started_at": "2017-09-12 19:35:38",
             "created_at": "2017-09-12 19:35:38",
+            "resources_synced": true,
             "configurations": {
                 "ovs_hybrid_plug": true,
                 "in_distributed_mode": false,
@@ -66,6 +67,7 @@
             "agent_type" :"DHCP agent",
             "started_at": "2017-09-12 19:35:36",
             "created_at": "2017-09-12 19:35:36",
+            "resources_synced": null,
             "configurations": {
                 "subnets": 2,
                 "dhcp_lease_duration": 86400,
@@ -88,6 +90,7 @@
             "agent_type": "L3 agent",
             "started_at": "2017-09-12 19:35:38",
             "created_at": "2017-09-12 19:35:38",
+            "resources_synced": null,
             "configurations": {
                 "agent_mode": "legacy",
                 "gateway_external_network_id": "",
@@ -114,6 +117,7 @@
             "agent_type": "Metadata agent",
             "started_at": "2017-09-12 19:35:39",
             "created_at": "2017-09-12 19:35:39",
+            "resources_synced": null,
             "configurations": {
                 "log_agent_heartbeats": false,
                 "nova_metadata_host": "172.16.78.191",

neutron_lib/api/definitions/__init__.py

@@ -12,6 +12,7 @@
 
 from neutron_lib.api.definitions import address_scope
 from neutron_lib.api.definitions import agent
+from neutron_lib.api.definitions import agent_resources_synced
 from neutron_lib.api.definitions import allowedaddresspairs
 from neutron_lib.api.definitions import auto_allocated_topology
 from neutron_lib.api.definitions import availability_zone
@@ -108,6 +109,7 @@ from neutron_lib.api.definitions import vpn_flavors
 _ALL_API_DEFINITIONS = {
     address_scope,
     agent,
+    agent_resources_synced,
     allowedaddresspairs,
     auto_allocated_topology,
     availability_zone,

neutron_lib/api/definitions/agent_resources_synced.py

@@ -0,0 +1,44 @@
+# Copyright (c) 2018 Ericsson
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+from neutron_lib.api.definitions import agent
+from neutron_lib import constants
+
+
+ALIAS = 'agent-resources-synced'
+IS_SHIM_EXTENSION = False
+IS_STANDARD_ATTR_EXTENSION = False
+NAME = "Agent's Resource View Synced to Placement"
+DESCRIPTION = 'Stores success/failure of last sync to Placement'
+UPDATED_TIMESTAMP = '2018-12-19T00:00:00-00:00'
+RESOURCE_NAME = agent.RESOURCE_NAME
+COLLECTION_NAME = agent.COLLECTION_NAME
+RESOURCES_SYNCED = 'resources_synced'
+
+RESOURCE_ATTRIBUTE_MAP = {
+    COLLECTION_NAME: {
+        RESOURCES_SYNCED: {
+            'allow_post': False,
+            'allow_put': False,
+            'default': constants.ATTR_NOT_SPECIFIED,
+            'is_visible': True,
+        }
+    }
+}
+
+SUB_RESOURCE_ATTRIBUTE_MAP = None
+ACTION_MAP = {}
+ACTION_STATUS = {}
+REQUIRED_EXTENSIONS = [agent.ALIAS]
+OPTIONAL_EXTENSIONS = []

neutron_lib/api/definitions/base.py

@@ -77,6 +77,7 @@ KNOWN_ACTION_STATUSES = (
 KNOWN_EXTENSIONS = (
     'address-scope',
     'agent',
+    'agent-resources-synced',
     'allowed-address-pairs',
     'auto-allocated-topology',
     'availability_zone',

neutron_lib/tests/unit/api/definitions/test_agent_resources_synced.py

@@ -0,0 +1,21 @@
+# Copyright (c) 2018 Ericsson
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+from neutron_lib.api.definitions import agent_resources_synced
+from neutron_lib.tests.unit.api.definitions import test_agent as base
+
+
+class AgentResourcesSyncedDefinitionTestCase(base.AgentDefinitionTestCase):
+    extension_module = agent_resources_synced
+    extension_attributes = (agent_resources_synced.RESOURCES_SYNCED,)

releasenotes/notes/agent-resources-synced-e70828841faf7acd.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    The ``agent-resources-synced`` extension introduces a new agent
+    attribute named ``resources_synced`` that tracks the success of
+    the resource view synchronization to Placement.