Using with sloctl

Reading time: 0 minute(s) (0 words)

This article describes managing SLO annotations using sloctl.

Annotations API

You can also manage SLO annotations using Nobl9 API.

The following sloctl commands are available for handling SLO annotations:

Command	Description
`sloctl apply -f {yamlFile}`	Apply an annotation in the YAML or JSON format
`sloctl get annotations`	Display the list of all project annotations. You can change the project by using the `-p {projectName}` parameter
`sloctl get annotations {annotationName}`	Display a single annotation
`sloctl delete annotation {annotationName}` `sloctl delete -f {yamlFile}`	Delete a single annotation

sloctl response

sloctl does not return Alert or Data event annotations. When you apply the sloctl get annotation[s] command, it will return only those annotations that were manually created or automatically generated as a result of user actions.

Applying annotations

You can add or update annotations using the sloctl apply -f {yamlFile} command.

Sample annotation YAML
apiVersion: n9/v1alpha
kind: Annotation
metadata:
  name: maintenance-window
  project: default
  labels:
    category:
      - maintenance
    environment:
      - production
    team:
      - infrastructure
spec:
  slo: api-server-latency
  description: Scheduled maintenance window
  startTime: 2024-06-01T02:00:00Z
  endTime: 2024-06-01T04:00:00Z

Notes on fields specific to Annotations:

Field	Type	Description
`metadata.name` Mandatory	string	A unique annotation name, required for distinguishing annotations within a project.
`metadata.project` Mandatory	string	The name of the project containing the target SLO.
`metadata.labels` Optional	map	Labels are key-value pairs that can be attached to SLOs, services, projects, and alert policies. Labels are used to select Nobl9 objects and find collections of Nobl9 objects. Constraints: • Labels must be in the `"key": - "value"` format (`key=value` in `sloctl`). • `key` can contain only lowercase alphanumeric characters, underscores, and dashes; must start with a letter and end with an alphanumeric character; maximum length 63 characters. •Up to 100 labels per `kind` • `value` can contain Unicode characters; maximum length 200 characters. You can use annotation labels to create custom columns in the Events section.
`spec.slo` Mandatory	string	The name of the SLO the annotation applies to.
`spec.description` Mandatory	string	A string (plain text) describing the annotation. The maximum number of characters is 10000.
`spec.startTime` Mandatory	string	Defines the date-time point where the annotation will be placed in the graph. The value must be in the `YYYY-MM-DDThh:mm:ssZ` format that complies with ISO8601. If `startTime` == `endTime`, the annotation will be placed at a single time point.
`spec.endTime` Mandatory	string	Defines the date-time point where the annotation will be placed in the graph. The value must be in the `YYYY-MM-DDThh:mm:ssZ` format that complies with ISO8601. If `startTime` == `endTime`, the annotation will be placed at a single time point.
`spec.objectiveName` Optional	string	Optional field allowing you to add an annotation to a particular, already existing SLO objective. If not specified, the annotation is attached to the SLO.

Annotation names and Move SLO

Annotation names must be unique within a project. When you move an SLO to another project, the move is blocked if the SLO has annotations whose names already exist in the target project.

To retry the move, delete each duplicate annotation, or recreate it with a different name and delete the old one.

Time format

By default, sloctl always returns time in UTC. You can adjust this for your time zone by replacing the Z (for Zulu; a shorthand for UTC) with the offset from UTC, prefaced with either + or -. For instance, to have sloctl return times adjusted for Eastern Standard Time, use startTime: 2021-11-02T17:10:05-05:00.