Bug Reference

The Jira issue associated with this design spec is CLOUDSTACK-9957

Branch

annotations

Introduction

Purpose

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.

References

  • JIRA ticket: Unable to render Jira issues macro, execution error.

Document History

Glossary

Feature Specifications

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.

Use cases

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.

Architecture and Design description

API changes

listAnnotations API will be created with the following parameters:
  • uuid: the id for this note or comment
  • entityType: type of CloudStack resource for which annotation is to be stored
  • entityUuid: UUID of the entity for which annotation will be stored
response an list of
  • uuid
  • entityType
  • entityUuid
  • annotation
  • user
  • created
  • removed

 

addAnnotations API command with the following parameters:

 

  • entityType: type of CloudStack resource for which annotation is to be stored
  • entityUuid: UUID of the entity for which annotation will be stored
  • annotation: the note or comment to be placed against the entity

The addAnnotation API command will not, by nature, overwrite any existing annotation for the entity.

response
  • uuid: the uuid for the new anotation
removeAnnotation API command with the following parameters:
  • uuid: the id of the remark or comment to mark as removed
OPTIONAL – replace an annotation actions to ‘improve’ it’s text.

replaceAnnotation API command with the following parameters:

  • uuid: the id of the remark or comment to replace
  • annotation: the changed/replacement note or comment placed against entity

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().

response
  • uuid: the uuid for the new annotation
OPTIONAL – bulk annotation action to ‘remove/hide’ annotation history.

removeAnnotations API command with the following parameters:

  • entityType: type of CloudStack resource for which annotation is to be stored
  • entityUuid: UUID of the entity for which annotation will be stored

removeAnnotations API command will mark any existing annotations as ‘removed’ now().

OPTIONAL – bulk annotation action to replace annotations by a single new one.

replaceAnnotations API command with the following parameters:

  • entityType: type of CloudStack resource for which annotation is to be stored
  • entityUuid: UUID of the entity for which annotation will be stored
  • annotation: the changed/replacement note or comment placed against entity

replaceAnnotations API command will mark any existing annotations as ‘removed’ now() and create a new one.

response

uuid: the uuid for the new anotation

listHosts and other API calls that result in a (list of) HostResponse, including updateHost below, will be extended to add the following to the response:
  • has_annotation: indication that notes or comments have been placed against an entity/host
updateHost API will be extended to allow the following parameter:
  • annotation (optional): note or comment to be added to the annotations placed against entity/host. The semantic of this will be to ‘addAnnotation’.

Schema changes

The ‘annotation’ table will be added with the following fields to persist the data.

  • 'uuid' varchar(40)
  • ‘annotation’ text
  • ‘entity_uuid’ varchar(40)
  • ‘entity_type’ varchar(32)
  • ‘user’ varchar(40)
  • ‘created’ datetime
  • ‘removed’ datetime

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:

  • has_annotation: boolean

this field will reflect the result of a join on the expression ‘count() > 0’ on the annotation records that point back to the entity.

UI

A host details view will contain extra fields for annotation, last annotation date and the annotator. Only the annotation will be editable:

Security

Only root admins would be permitted to use the listAnnotations API. Users would access the annotations through the element specific 'list*' API (once implemented)

DB access layer changes

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.

DB upgrade

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.

 

  • No labels