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 system annotations. When applying the sloctl get annotation[s] command, sloctl will return only annotations created by the user.

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 30 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 1000.
`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.

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.