The Jira issue associated with this design spec is CLOUDSTACK-9957
This is the functional specification for introducing the possibility for admins to annotate entities in Apache CloudStack. Initially hosts will be enabled but the work is intended to be extended to all kinds of entities, i.e. networks, storage (primary or secondary), instances, etc.
An admin may wish to be able to add a text field for a node if it is placed in Maintenance or Disabled - so that the next cloudstack admin knows as to why the action has been taken. this can be implemented so it can be extended to other entities like networks, pods, storages, etc, with the additional of an ‘annotation’ table. This table could be accessed either by the extension of individual APIs ie. listHosts, listVirtualMachines, listNetworks, listSnapshots, listFirewallRules or via a new API command – listAnnotations. Creating the new API command allows annotations to be created for all elements without the related list APIs being updated, while it does not block APIs from being updated for further convenience.
This functional specification proposes a method to add annotations to any/all elements for which CloudStack holds a UUID for in its database. This specification includes an implicit audit trail/history of the annotations placed against an entity.
The user and the time/date of the entry will be stored against the addition of any annotations. Annotations can be removed from view using the removeAnnotation API. This will mark an annotation as removed, but will not delete it from the CloudStack database.
Within the scope of this specification we will not show annotation history in the UI.
To meet the described use case (and not to increase scope) only a limited set of elements will be suported in the UI, or have their list* API extended. Only the listHosts API will be updated to return annotations. Not all entities that could be annotated in this feature will be supported.
The feature will require for the API for entities to be altered , so per entity type supported work needs to be done after initial implementation.
Annotations will be a convenience to users. It should not require extensive training.
No impact on operation should be expected. A slight increase of latency can be expected for affected listAPIs.
For each type of element for which the annotation field will exposed, the UI would need to be extended to indicate that annotations are set on the entity. The annotations will become visible by hovering or clicking the annotations indicator. This will then expose the annotations for this entity for editing.
An administrator wishes to be able to add a text field for an entity, most noticeably a node, when an action is taken on it, i.e. it is placed in Maintenance or Disabled, so that the next user or cloudstack admin that comes along knows as to why the action has been taken.
The addAnnotation API command will not, by nature, overwrite any existing annotation for the entity.
replaceAnnotation API command with the following parameters:
replaceAnnotation API command will add a new annotation to the entity found by the one the uuid is given for. It will mark the existing one as ‘removed’ now().
removeAnnotations API command with the following parameters:
removeAnnotations API command will mark any existing annotations as ‘removed’ now().
replaceAnnotations API command with the following parameters:
replaceAnnotations API command will mark any existing annotations as ‘removed’ now() and create a new one.
uuid: the uuid for the new anotation
The ‘annotation’ table will be added with the following fields to persist the data.
For those entities for which annotations are to be supported, the views by which the responses are filled will be extended to include a boolean field:
this field will reflect the result of a join on the expression ‘count() > 0’ on the annotation records that point back to the entity.
A host details view will contain extra fields for annotation, last annotation date and the annotator. Only the annotation will be editable:
Only root admins would be permitted to use the listAnnotations API. Users would access the annotations through the element specific 'list*' API (once implemented)
List views would be updated to support updated APIs.
A new table will be created to contain annotations. Strict constraints will be applied on that table in code to avoid orphaned annotations, by defining an enumeration of entity types for which annotations are permissible. For any type in this enumeration, the database records may only be marked removed and may not be deleted.
A table will be added with a logical key into all entity tables and a hard key into users.
Any view that will contain annotations will be recreated.