Placement Minimum HTTP Cache Headers

https://blueprints.launchpad.net/nova/+spec/placement-cache-headers

RFC 7232 Section 2.2 says that a web service should send a last-modified header for any representation for a last-modified time can reasonable be deduced. The placement service does not currently do this. Including it will make it a better HTTP citizen and also provide useful metadata in the response. If a last-modified header is added then it is also necessary to add a cache-control header with a value of “no-cache” to insure that clients and proxies are not inclined to cache representations provided by the placement service.

Problem description

By not sending appropriate cache headers, placement is presenting two small problems:

  • It is not following accepted standards for HTTP services.

  • There is a chance that clients and proxies pasing requests to placement will cache responses from the service. Given that the majority of data provided by placement highly time dependent, this is problematic.

Use Cases

As a user of an HTTP API I expect it to follow standards and provide me with a last-modified header that reflects the last modified time of the resource.

Proposed change

In a new microversion, for any GET request handled by the placement service add two additional headers in the response:

  • last-modified with a meaningful time and data value (see below).

  • cache-control with a value of no-cache. See RFC 7234 Section 5.2.1.4 for additional detail on what this means.

The value of the last-modified header is chosen from three different options:

  • If the request is for a singular entity directly associated with a database row that has an updated_at or created_at field, then the value of one of those fields will be used, preferring updated_at if it is set (it won’t be if the resource has only been created but not yet updated).

  • If the request is for a collection of entities that are directly associated with the database, the value will be the max of the updated_at or created_at for all the entities in the collection.

  • If the request is for an entity or collection which is composed from multiple parts, then the value of the header will be the current time.

Alternatives

A viable alternative is to do nothing. If we don’t add the last-modified headers then the risk of caching is very small (as there is no conditional header present). But then we would be bad HTTP citizens.

Another alternatives is to start using ETags within the placement service. This would enable fairly complex and complete server-side and client-side caching of resources, saving bandwidth and database queries. It is, however, a fairly serious undertaking and would not remove the need for last-modified headers, so best to take smaller steps towards having the full suite of headers.

Data model impact

The database tables already have the desired updated_at and created_at fields but the OVO in nova/objects/resource_provider.py need to be updated to expose those fields. This can be done by using the NovaTimestampObject mixin.

REST API impact

As stated, every GET request will get two additional headers cache-control: no-cache and last-modified: <timestamp>. These will only be exposed in the newly created microversion.

Security impact

None.

Notifications impact

None.

Other end user impact

If we consider the scheduler report client to be the primary “end user” of placement, these headers will have no impact on it, especially as the client uses explicit microversions in its requests.

Performance Impact

A slight impact when requesting large collections. That collection is traversed to find the last-modified value. Most of this impact can be alleviated by combining that work in the existing traversal that creates the JSON response body.

Other deployer impact

None.

Developer impact

When developers add new handlers for GET requests to the placement service, they will need to add these headers.

Implementation

Assignee(s)

Primary assignee:

cdent

Other contributors:

None

Work Items

  • Create a new microversion for this functionality

  • Update the objects in nova/objects/resource_provider.py to expose the updated_at and created_at fields

  • For each handler for a GET request, add the headers

  • Updated gabbi tests to inspect the new headers and confirm their presence in the new microversion and lack of presence in older microversions

  • Update placement api-ref

Dependencies

None.

Testing

As stated in the work items, it’s important to confirm that the headers show up as expected in the new microversion. It’s equally important to confirm that they do _not_ in older microversions.

Documentation Impact

None

References

History

Revisions

Release Name

Description

Queens

Introduced