System Metadata Proposal

[beyhan]

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.

[beyhan]

For reference k8s has reserved labels but in our case we want to set metadata during resource creation which is specified by the resource creator and the suggestion above fits better.

[stephanme]

There is another option system metadata: we could use the label or annotation key prefix to define a namespace for system metadata, e.g. org.cloudfoundry.system.

This way there is no change in the CF API needed. Rules would be similar as specified above: any change in a label or annotation within the org.cloudfoundry.system namespace requires admin permission.

Drawback: There might be already metadata with prefix org.cloudfoundry.system in existing foundations which suddenly become system metadata. Could be mitigated by putting system metadata behind a feature flag. Operators can then decide if and when they want to enable system metadata, e.g. only after checking and cleaning up.

[beyhan]

There is another option system metadata: we could use the label or annotation key prefix to define a namespace for system metadata, e.g. org.cloudfoundry.system.

I didn't go that way because of backwards compatibility but the prefix approach will be similar to the K8s approach which I see as advantage.