add-resource-timestamp

https://blueprints.launchpad.net/Neutron/+spec/add-port-timestamp

Resource models like network, subnet and port in Neutron should include timestamp fields “created_at” and “updated_at”. These two fields can facilitate the task of monitoring resource changes, which are time-consuming and inefficient currently.

Problem Description

End users may be interested in monitoring Neutron resources or collecting statistics on a group of resources in a specific time-frame, for instance, querying ports that have changed or refreshed in the last 5 seconds in a large scale application. In Neutron, we do not have timestamp fields associated with resources, so there is no way we can query them based on their operational time.

Proposed Change

We propose to add created_at and updated_at fields to resource models. In the sqlalchemy model definition, “default” argument is set to timeutils.utcnow() for created_at and updated_at, so when a resource is created, sqlalchemy will automatically fill these two fields with the timestamp the resource is created; “onupdate” argument is also set to timeutils.utcnow() for updated_at so when a resource is updated, updated_at will be refreshed. All the timestamp field operations are finished in the database side, so there is no extra work needed in the plugin side.

Based on these two fields, change_since filter is introduced for retrieving resources. It accepts a timestamp and Neutron will return resources with updated_at field later than this timestamp.

Data Model Impact

Two new attributes are added to resource model:

Attribute name

Type

Default Value

Required

CRUD

Description

created_at updated_at

DateTime DateTime

timeutils.utcnow() timeutils.utcnow()

Y Y

R R

Timestamp resource is created Timestamp resource is updated

As discussed above, these two fields are maintained by sqlalchemy in Neutron server. It’s not necessary for users to pass these two values when creating or updating resource, so only Read operation in CRUD is provided.

REST API Impact

Created_at and updated_at will be exposed to users via extension API. If plugin supports, they are returned when users issue resource retrieving requests. Also, resources list API accepts new query string parameter change_since. Users can pass timestamp of ISO 8601 format to the list API uri to retrieve resources operated since a specific time.

Take port as an example, the request uri looks like this:

GET /v2.0/ports?changed_since=2015-07-31T00:00:00

and response:

{
    "ports": [
        {
            "status": "ACTIVE",
            "name": "",
            "allowed_address_pairs": [],
            "admin_state_up": true,
            "network_id": "70c1db1f-b701-45bd-96e0-a313ee3430b3",
            "tenant_id": "",
            "extra_dhcp_opts": [],
            "device_owner": "network:router_gateway",
            "mac_address": "fa:16:3e:58:42:ed",
            "fixed_ips": [
                {
                    "subnet_id": "008ba151-0b8c-4a67-98b5-0d2b87666062",
                    "ip_address": "172.24.4.2"
                }
            ],
            "id": "d80b1a3b-4fc1-49f3-952e-1e2ab7081d8b",
            "security_groups": [],
            "device_id": "9ae135f4-b6e0-4dad-9e91-3c223e385824"
            "created_at": 2015-07-31T11:50:05
            "updated_at": 2015-07-31T11:51:12
        }
    ]
}

Security Impact

None

Notifications Impact

None

Other End User Impact

Neutron python client may add help to inform users the new filter. Neutron python client supports dynamic assigning search fields so it is easy for it to support this new filter. Also Neutron python client needs to add the two new fields when displaying resource information.

Take port as an example, the command looks like:

neutron port-list --changed-since 2015-07-31T00:00:00

Performance Impact

Performance of syncing resource status with other systems like a monitor system or a user interface can be improved. Instead of retrieving all the resources in every syncing period to update resource status, these systems can just retrieve resources updated during the syncing interval using change_since filter.

IPv6 Impact

None

Other Deployer Impact

NTP service needs to be configured and started to synchronize time among nodes, so the timestamps saved in created_at and updated_at are valid across nodes.

Developer Impact

None

Community Impact

This change will bring facility to monitor Neutron resources. Actually most projects in OpenStack like Nova [1], Cinder [2] have timestamp fields to track the operation time of resources.

One problem of absolute timestamp is that sudden system time change caused by attack or failure will make the previous cached timestamp invalid. Seeking a relative timestamp storing strategy may be a better choice, but it’s out of the extent of this blueprint.

Alternatives

None

Implementation

Assignee(s)

Primary assignee:

caizhiyuan1@huawei.com

Other contributors:

TBD

Work Items

  • Update database schema

  • Add API filter

  • Add related test

  • Update neutron client to support the new filter

Dependencies

None

Testing

Tempest Tests

None

Functional Tests

  • Test if created_at and updated_at can be correctly initiated.

  • Test if updated_at can be correctly written when resource updated.

  • Test if change_since filter can be correctly applied.

API Tests

Test if the new filter can be correctly parsed and validated.

Documentation Impact

User Documentation

Update Neutron API reference.

Developer Documentation

Update developer documentation to introduce the new filter.

References