System Metadata Proposal

System Metadata

Authors: @beyhan

Reviewers: @stephanme

Feature goals

System metadata will allow CF admin users to set metadata from type label or annotations to CF resources. The system metadata will be updatable only by CF admin users. This feature can be used by CF itself or CF operators to add extra metadata to CF resources which can be used later for resource selection or resource statistics.

How to Use It

CF admin users will update a CF resource metadata via the existing CF V3 APIs for resource patching. E.g. a CF organization could be updated via the existing organization update API PATCH /v3/organizations/:org-guid with the following body content:

{
  "metadata": {
    "systemLabels": {  "systemLabel": “true” },
    "systemAnnotations": {  "systemAnnotation": "true" },
    "labels": {},
    "annotations": {}
  }
}

None CF admin users having authorizations to list a CF resource will be able to view the system metadata with read-only permissions. E.g. a CF user who has the org manager role will be able to see the system metadata assigned to a org via organization list APIs GET /v3/organizations/:org-guid. Example response:

HTTP/1.1 200 OK
Content-Type: application/json
 
{
  ... 
  "metadata": {
    "systemLabels": {  "systemLabel": “true” },
    "systemAnnotations": {  "systemAnnotation": "true" },
    "labels": {},
    "annotations": {}
  }
}

Technical Details

This feature suggests extending the metadata object with system metadata for labels and annotations. This suggestion is backwards compatible because it does not suggest changing existing metadata types. The system metadata will have the same constraints as the none system ones documented in the CF APIs. When a none admin user tries to update system metadata the request should fail and not change anything. In CF APIs we have already today APIs which can require multiple roles e.g. create domain.

Possible Future Enhancements

CF CLI can be extended to support system metadata. The scope of the current proposal is to extend the CF APIs only but, in the future, this can be supported via the CLI also. E.g. a new command cf set-system-label could be implemented.

Start by reviewing the existing CF V3 resource patching APIs and the documented labels and annotations constraints linked in the proposal. The work is done when system labels and annotations are supported across the intended resource APIs, admin-only updates are enforced without partial changes, and authorized non-admin users can read them.