YAML guide
This document explains how Nobl9 configurations are represented in the sloctl
API, and how you can express them in .yaml format.
Overall schema
apiVersion: n9/v1alpha
kind: Agent | Annotation | AlertMethod | AlertPolicy | AlertSilence |
DataExport | Project | RoleBinding | Service | SLO |
metadata:
name: string # Mandatory
displayName: string # Optional
project: string # Optional
labels: # Map, optional
"key_1": # Label's key
- "value_1" # Label's value
annotations:
key: value # String, optional
spec:
...
Notes on the overall schema:
Field | Type | Description |
---|---|---|
metadata.name mandatory | string | Field following DNS RFC1123 conventions. Constraints: • Max. 63 characters. • Only lowercase alphanumeric characters or hyphens. • Must start and end with an alphanumeric character. |
metadata.project mandatory | string | Field following DNS RFC1123 conventions. Constraints: • Max. 63 characters. • Only lowercase alphanumeric characters or hyphens. • Must start and end with an alphanumeric character. |
metadata.displayName optional | string | Can contain max 63 characters. There's no additional validation. |
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.• value can contain Unicode characters; maximum length 200 characters. |
metadata.annotations optional | string | Metadata annotations are non-identifiable key-value pairs that can be attached to SLOs, services, projects, and alert policies. Metadata annotations are used for descriptive purposes only. Constraints: • Metadata annotations must be in the key: value format.• 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.• value can contain Unicode characters; maximum length 1050 characters.See metadata annotations for more details. |
All names must be unique in the scope of one project.
It is not possible to have two objects of the same kind with exactly the same name in a given project.
When adding labels to a YAML definition, remember to put both key
and value
in parentheses (""
), for example:
labels:
"team":
- "green"
Otherwise, sloctl
may return the following error:
Error: malformed JSON payload - pass single list of valid JSON objects.
Overview of available YAML objects
The following sections describe the types of objects that are available in Nobl9 and how to configure them.
Agent
The agent is middleware between the Nobl9 app and an external data source. It gathers metrics data and sends it to Nobl9. Agents need to be installed on the customer's server.
Refer to Sources for details about configuring the agent for each data source via sloctl
.
apiVersion: n9/v1alpha # Mandatory
kind: Agent # Mandatory
metadata:
name: string # Mandatory
displayName: string # Optional
project: string # Mandatory
spec:
description: string # Optional
sourceOf:
- Metrics
- Services
releaseChannel: beta # Mandatory, enum
queryDelay:
unit: Second | Minute # Mandatory, enum
value: numeric # Mandatory
datadog:
...
# historicalDataRetrieval is an optional structure related to Replay
# Use only with sources that support it
# Otherwise, sloctl will return a validation error
historicalDataRetrieval:
maxDuration:
value: 0 # Optional, numeric
unit: Minute | Hour | Day # Optional, enum
defaultDuration:
value: 0 # Optional, numeric
unit: Minute | Hour | Day # Optional, enum
Notes on fields specific to Agent
Field | Type | Description |
---|---|---|
queryDelay.unit mandatory | enum | Specifies the unit for the query delay. Possible values: Second | Minute . • Check query delay documentation for default unit of query delay for each source. |
queryDelay.value mandatory | numeric | Specifies the value for the query delay. • Must be a number less than 1440 minutes (24 hours). • Check query delay documentation for default unit of query delay for each source. |
releaseChannel mandatory | enum | Specifies the release channel. Accepted values: beta | stable . |
Replay-related fields | ||
historicalDataRetrieval optional | n/a | Optional structure related to configuration related to Replay. ❗ Use only with supported sources. • If omitted, Nobl9 uses the default values of value: 0 and unit: Day for maxDuration and defaultDuration . |
maxDuration.value optional | numeric | Specifies the maximum duration for historical data retrieval. Must be integer ≥ 0 . See Replay documentation for values of max duration per data source. |
maxDuration.unit optional | enum | Specifies the unit for the maximum duration of historical data retrieval. Accepted values: Minute | Hour | Day . |
defaultDuration.value optional | numeric | Specifies the default duration for historical data retrieval. Must be integer ≥ 0 and ≤ maxDuration . |
defaultDuration.unit optional | enum | Specifies the unit for the default duration of historical data retrieval. Accepted values: Minute | Hour | Day . |
If you describe infrastructure as code, you might also consider creating agents via Terraform. You can find more details in our Terraform documentation.
AlertMethod
When an alert is triggered, you can send a notification to an external tool or a REST endpoint (a web service). Alert methods can be associated with all available integrations.
- General YAML
- Working sample
apiVersion: n9/v1alpha # Mandatory
kind: AlertMethod # Mandatory
metadata:
name: string # Mandatory
displayName: string # Optional
spec:
description: string # Optional
# Only one of the following is possible per one AlertMethod definition
# Refer to alert methods documentation to see detailed specifications
discord:
...
# Or
email:
...
# Or
jira:
...
# Or
msteams:
...
# Or
opsgenie:
...
# Or
pagerDuty:
...
# Or
servicenow:
...
# Or
slack:
...
# Or
webhook:
...
apiVersion: n9/v1alpha
kind: AlertMethod
metadata:
name: discord-notification
displayName: Discord notification
spec:
description: Sends message to Discord channel through webhook
discord:
# Nobl9 general Discord channel
url: <https://discord.com/api/webhooks/809803263775211571/D4-5q51DehrBpOAFND6naV8MgCQwmu1vpAwXrO8vPVflFt1bo6J0wMXzvFAttb_2CRjv>
If you describe infrastructure as code, you might also consider defining the alert methods with the same convention. You can find more details in our Terraform documentation.
AlertPolicy
Alert policies define when to trigger an alert via the configured alert method.
A Nobl9 AlertPolicy
accepts up to three conditions.
All defined conditions must be met to trigger an alert.
In Nobl9 release 1.66.2-3, the previous response from sloctl get alertpolicies
is deprecated, and will be phased out in the future.
In subsequent updates, the command will return only the metadata.name
and metadata.project
fields associated with the alert policy (instead of returning the entire block for the alertMethods
object):
apiVersion: n9/v1alpha
kind: AlertPolicy
metadata:
...
spec:
...
alertMethods:
- metadata:
name: my-alert-method
project: my-project
We'll inform you about the full phase-out in a separate announcement.
- General YAML
- Working sample
apiVersion: n9/v1alpha # Mandatory
kind: AlertPolicy # Mandatory
metadata:
name: string # Mandatory
displayName: string # Optional
project: string # Optional, if not defined, Nobl9 returns a default value for this field
spec:
description: string # Optional
severity: Low | Medium | High # Mandatory, enum
cooldown: "5m" # Mandatory, valid string duration, accepted units: s, m, h
conditions:
- measurement: timeToBurnBudget | timeToBurnEntireBudget | averageBurnRate | burnedBudget # Mandatory, enum
value: string or numeric # Mandatory
op: lt | gt | lte | gte # Mandatory, enum
lastsFor: "0m" # Optional, valid string duration. Default 0 (seconds | minutes | hours)
alertMethods: # You can append several alertMethods
- metadata:
name: string # Mandatory, name of the alert method
project: string # Optional, define if you want to use an AlertMethod from a different project than that defined for AlertPolicy
- metadata:
name: string # Mandatory, name of the alert method
project: string # Optional, define if you want to use an AlertMethod from a different project than that defined for AlertPolicy
apiVersion: n9/v1alpha
kind: AlertPolicy
metadata:
name: trigger-alert-policy-bad-delayed-multi
project: trigger-alert
annotations:
registry: docker.io
visibility: internal
spec:
severity: Medium
cooldown: "5m"
conditions:
- measurement: timeToBurnBudget
value: "18h"
op: lt
lastsFor: "30m"
- measurement: averageBurnRate
value: 1.9
op: gte
lastsFor: "30m"
- measurement: burnedBudget
value: 0.01
op: gte
lastsFor: "30m"
alertMethods:
- metadata:
name: webhook-global-notification
project: server-production
- metadata:
name: webhook-notification
Notes on fields specific to AlertPolicy
:
Field | Type | Description |
---|---|---|
metadata.annotations optional | string | Metadata annotations are key-value pairs that can be attached to SLOs, services, projects, and alert policies. Constraints: • Labels must be in the key: value format.• 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.• value can contain Unicode characters; maximum length 1050 characters. See metadata annotations for more details. |
spec.cooldown mandatory | string | Duration representing the time measured since the last time point when all conditions were satisfied. Constraints:• Default value: 5m .• Accepted units: Seconds | Minutes | Hours. Examples: 5m , 1h , 30s .• The minimum allowable value is 5m , with no upper limit.• Must adhere to a valid time string duration format, see parse duration for more details. |
conditions[n].measurement mandatory | string | Measurement options for the condition:•timeToBurnBudget When the remaining error budget will be exhausted. The expected value is a string in time duration format; for example, 72h (3 days).
timeToBurnEntireBudget When the entire error budget will be exhausted. The expected value is a string in time duration format; for example, 72h (3 days).
|