Annotation reference

Annotations provide information about a Conjur resource.

Overview

Annotations offer a way to assign metadata and descriptive information to a Conjur resource. Any Conjur resource can have annotations associated with it in policy.

Annotations are a type of mapping node in policy. The required mapping node name is annotations, followed by a colon. This node name is followed by one or more key-value pairs on separate lines, indented under the annotations: node name. The indentation is required.

The format of the key-value pair is key: value, requiring the colon followed by a space.

After you change an annotation in a policy, you need to reload your adjusted policy file using the --replace (PUT) option for the changes to take effect. For more information about policy load modes, see Policy load modes.

Here is an example annotation on a host. The annotation key in this example is description. The value is the phrase that appears after the colon.

- !host
  id: www-01.home.cern
  annotations:
    description: Hypertext web server

Conjur supports the following types of annotations:

Predefined annotations	Predefined annotations support Conjur features. For these annotations, the annotation key is predefined and the value may be predefined with expected values.
Custom annotations	Custom annotations are free-form, defined by you for your own use. For these, you define the key and the value.

Benefits of using annotations

Annotations provide the following benefits:

Annotations provide a way to add metadata and organization to your Conjur resources
Annotations can help to explain the purpose of each statement in the policy. Descriptive annotations can help users better understand the objects in the Conjur system
Annotations support following UI-specific features: Editable annotation on groups and layers and Host identifiers for integrations
Conjur uses annotations for some workflows , for example, variable rotation and expiration are based on annotations
Custom code and scripts can use annotation values to perform custom operations, such as scripted updates to a system

Permissions for annotations

The rights to create, modify, and read annotations are protected by RBAC.

Permission	Description
`update`	Required to create and modify annotations
`read`	Required to view annotations

After an annotation is loaded into Conjur as part of a policy, it is available through the API and the UI, subject to a read permission check.