1 package v1 2 3 import ( 4 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" 5 "k8s.io/apimachinery/pkg/util/intstr" 6 ) 7 8 // AlertingRule represents a set of user-defined Prometheus rule groups containing 9 // alerting rules. This resource is the supported method for cluster admins to 10 // create alerts based on metrics recorded by the platform monitoring stack in 11 // OpenShift, i.e. the Prometheus instance deployed to the openshift-monitoring 12 // namespace. You might use this to create custom alerting rules not shipped with 13 // OpenShift based on metrics from components such as the node_exporter, which 14 // provides machine-level metrics such as CPU usage, or kube-state-metrics, which 15 // provides metrics on Kubernetes usage. 16 // 17 // The API is mostly compatible with the upstream PrometheusRule type from the 18 // prometheus-operator. The primary difference being that recording rules are not 19 // allowed here -- only alerting rules. For each AlertingRule resource created, a 20 // corresponding PrometheusRule will be created in the openshift-monitoring 21 // namespace. OpenShift requires admins to use the AlertingRule resource rather 22 // than the upstream type in order to allow better OpenShift specific defaulting 23 // and validation, while not modifying the upstream APIs directly. 24 // 25 // You can find upstream API documentation for PrometheusRule resources here: 26 // 27 // https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md 28 // 29 // Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). 30 // +openshift:compatibility-gen:level=1 31 // +genclient 32 // +k8s:openapi-gen=true 33 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 34 // +kubebuilder:subresource:status 35 type AlertingRule struct { 36 metav1.TypeMeta `json:",inline"` 37 // metadata is the standard object's metadata. 38 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 39 metav1.ObjectMeta `json:"metadata,omitempty"` 40 41 // spec describes the desired state of this AlertingRule object. 42 // +kubebuilder:validation:Required 43 Spec AlertingRuleSpec `json:"spec"` 44 45 // status describes the current state of this AlertOverrides object. 46 // 47 // +optional 48 Status AlertingRuleStatus `json:"status,omitempty"` 49 } 50 51 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 52 53 // AlertingRuleList is a list of AlertingRule objects. 54 // 55 // Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). 56 // +openshift:compatibility-gen:level=1 57 // +k8s:openapi-gen=true 58 type AlertingRuleList struct { 59 metav1.TypeMeta `json:",inline"` 60 // metadata is the standard object's metadata. 61 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 62 metav1.ListMeta `json:"metadata,omitempty"` 63 64 // items is a list of AlertingRule objects. 65 // +kubebuilder:validation:Required 66 Items []AlertingRule `json:"items"` 67 } 68 69 // AlertingRuleSpec is the desired state of an AlertingRule resource. 70 // 71 // +k8s:openapi-gen=true 72 type AlertingRuleSpec struct { 73 // groups is a list of grouped alerting rules. Rule groups are the unit at 74 // which Prometheus parallelizes rule processing. All rules in a single group 75 // share a configured evaluation interval. All rules in the group will be 76 // processed together on this interval, sequentially, and all rules will be 77 // processed. 78 // 79 // It's common to group related alerting rules into a single AlertingRule 80 // resources, and within that resource, closely related alerts, or simply 81 // alerts with the same interval, into individual groups. You are also free 82 // to create AlertingRule resources with only a single rule group, but be 83 // aware that this can have a performance impact on Prometheus if the group is 84 // extremely large or has very complex query expressions to evaluate. 85 // Spreading very complex rules across multiple groups to allow them to be 86 // processed in parallel is also a common use-case. 87 // 88 // +listType=map 89 // +listMapKey=name 90 // +kubebuilder:validation:MinItems:=1 91 // +kubebuilder:validation:Required 92 Groups []RuleGroup `json:"groups"` 93 } 94 95 // Duration is a valid prometheus time duration. 96 // Supported units: y, w, d, h, m, s, ms 97 // Examples: `30s`, `1m`, `1h20m15s`, `15d` 98 // +kubebuilder:validation:Pattern:="^(0|(([0-9]+)y)?(([0-9]+)w)?(([0-9]+)d)?(([0-9]+)h)?(([0-9]+)m)?(([0-9]+)s)?(([0-9]+)ms)?)$" 99 // +kubebuilder:validation:MaxLength=2048 100 type Duration string 101 102 // RuleGroup is a list of sequentially evaluated alerting rules. 103 // 104 // +k8s:openapi-gen=true 105 type RuleGroup struct { 106 // name is the name of the group. 107 // 108 // +kubebuilder:validation:Required 109 // +kubebuilder:validation:MinLength=1 110 // +kubebuilder:validation:MaxLength=2048 111 Name string `json:"name"` 112 113 // interval is how often rules in the group are evaluated. If not specified, 114 // it defaults to the global.evaluation_interval configured in Prometheus, 115 // which itself defaults to 30 seconds. You can check if this value has been 116 // modified from the default on your cluster by inspecting the platform 117 // Prometheus configuration: 118 // The relevant field in that resource is: spec.evaluationInterval 119 // 120 // +optional 121 Interval Duration `json:"interval,omitempty"` 122 123 // rules is a list of sequentially evaluated alerting rules. Prometheus may 124 // process rule groups in parallel, but rules within a single group are always 125 // processed sequentially, and all rules are processed. 126 // 127 // +kubebuilder:validation:MinItems:=1 128 // +kubebuilder:validation:Required 129 Rules []Rule `json:"rules"` 130 } 131 132 // Rule describes an alerting rule. 133 // See Prometheus documentation: 134 // - https://www.prometheus.io/docs/prometheus/latest/configuration/alerting_rules 135 // 136 // +k8s:openapi-gen=true 137 type Rule struct { 138 // alert is the name of the alert. Must be a valid label value, i.e. may 139 // contain any Unicode character. 140 // 141 // +kubebuilder:validation:Required 142 // +kubebuilder:validation:MinLength=1 143 // +kubebuilder:validation:MaxLength=2048 144 Alert string `json:"alert"` 145 146 // expr is the PromQL expression to evaluate. Every evaluation cycle this is 147 // evaluated at the current time, and all resultant time series become pending 148 // or firing alerts. This is most often a string representing a PromQL 149 // expression, e.g.: mapi_current_pending_csr > mapi_max_pending_csr 150 // In rare cases this could be a simple integer, e.g. a simple "1" if the 151 // intent is to create an alert that is always firing. This is sometimes used 152 // to create an always-firing "Watchdog" alert in order to ensure the alerting 153 // pipeline is functional. 154 // 155 // +kubebuilder:validation:Required 156 Expr intstr.IntOrString `json:"expr"` 157 158 // for is the time period after which alerts are considered firing after first 159 // returning results. Alerts which have not yet fired for long enough are 160 // considered pending. 161 // 162 // +optional 163 For Duration `json:"for,omitempty"` 164 165 // labels to add or overwrite for each alert. The results of the PromQL 166 // expression for the alert will result in an existing set of labels for the 167 // alert, after evaluating the expression, for any label specified here with 168 // the same name as a label in that set, the label here wins and overwrites 169 // the previous value. These should typically be short identifying values 170 // that may be useful to query against. A common example is the alert 171 // severity, where one sets `severity: warning` under the `labels` key: 172 // 173 // +optional 174 Labels map[string]string `json:"labels,omitempty"` 175 176 // annotations to add to each alert. These are values that can be used to 177 // store longer additional information that you won't query on, such as alert 178 // descriptions or runbook links. 179 // 180 // +optional 181 Annotations map[string]string `json:"annotations,omitempty"` 182 } 183 184 // AlertingRuleStatus is the status of an AlertingRule resource. 185 type AlertingRuleStatus struct { 186 // observedGeneration is the last generation change you've dealt with. 187 // 188 // +optional 189 ObservedGeneration int64 `json:"observedGeneration,omitempty"` 190 191 // prometheusRule is the generated PrometheusRule for this AlertingRule. Each 192 // AlertingRule instance results in a generated PrometheusRule object in the 193 // same namespace, which is always the openshift-monitoring namespace. 194 // 195 // +optional 196 PrometheusRule PrometheusRuleRef `json:"prometheusRule,omitempty"` 197 } 198 199 // PrometheusRuleRef is a reference to an existing PrometheusRule object. Each 200 // AlertingRule instance results in a generated PrometheusRule object in the same 201 // namespace, which is always the openshift-monitoring namespace. This is used to 202 // point to the generated PrometheusRule object in the AlertingRule status. 203 type PrometheusRuleRef struct { 204 // This is a struct so that we can support future expansion of fields within 205 // the reference should we ever need to. 206 207 // name of the referenced PrometheusRule. 208 // +kubebuilder:validation:Required 209 // +kubebuilder:validation:MinLength=1 210 // +kubebuilder:validation:MaxLength=2048 211 Name string `json:"name"` 212 } 213 214 // +genclient 215 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 216 // +kubebuilder:subresource:status 217 218 // AlertRelabelConfig defines a set of relabel configs for alerts. 219 // 220 // Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). 221 // +openshift:compatibility-gen:level=1 222 // +k8s:openapi-gen=true 223 type AlertRelabelConfig struct { 224 metav1.TypeMeta `json:",inline"` 225 // metadata is the standard object's metadata. 226 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 227 metav1.ObjectMeta `json:"metadata,omitempty"` 228 229 // spec describes the desired state of this AlertRelabelConfig object. 230 // +kubebuilder:validation:Required 231 Spec AlertRelabelConfigSpec `json:"spec"` 232 233 // status describes the current state of this AlertRelabelConfig object. 234 // 235 // +optional 236 Status AlertRelabelConfigStatus `json:"status,omitempty"` 237 } 238 239 // AlertRelabelConfigsSpec is the desired state of an AlertRelabelConfig resource. 240 // 241 // +k8s:openapi-gen=true 242 type AlertRelabelConfigSpec struct { 243 // configs is a list of sequentially evaluated alert relabel configs. 244 // 245 // +kubebuilder:validation:MinItems:=1 246 // +kubebuilder:validation:Required 247 Configs []RelabelConfig `json:"configs"` 248 } 249 250 // AlertRelabelConfigStatus is the status of an AlertRelabelConfig resource. 251 type AlertRelabelConfigStatus struct { 252 // conditions contains details on the state of the AlertRelabelConfig, may be 253 // empty. 254 // 255 // +optional 256 Conditions []metav1.Condition `json:"conditions,omitempty"` 257 } 258 259 const ( 260 // AlertRelabelConfigReady is the condition type indicating readiness. 261 AlertRelabelConfigReady string = "Ready" 262 ) 263 264 // AlertRelabelConfigList is a list of AlertRelabelConfigs. 265 // 266 // Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). 267 // +openshift:compatibility-gen:level=1 268 // +k8s:openapi-gen=true 269 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 270 type AlertRelabelConfigList struct { 271 metav1.TypeMeta `json:",inline"` 272 // metadata is the standard object's metadata. 273 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 274 metav1.ListMeta `json:"metadata,omitempty"` 275 276 // items is a list of AlertRelabelConfigs. 277 // +kubebuilder:validation:MinItems:=1 278 // +kubebuilder:validation:Required 279 Items []*AlertRelabelConfig `json:"items"` 280 } 281 282 // LabelName is a valid Prometheus label name which may only contain ASCII 283 // letters, numbers, and underscores. 284 // 285 // +kubebuilder:validation:Pattern:="^[a-zA-Z_][a-zA-Z0-9_]*$" 286 // +kubebuilder:validation:MaxLength=2048 287 type LabelName string 288 289 // RelabelConfig allows dynamic rewriting of label sets for alerts. 290 // See Prometheus documentation: 291 // - https://prometheus.io/docs/prometheus/latest/configuration/configuration/#alert_relabel_configs 292 // - https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config 293 // 294 // +kubebuilder:validation:XValidation:rule="self.action != 'HashMod' || self.modulus != 0",message="relabel action hashmod requires non-zero modulus" 295 // +kubebuilder:validation:XValidation:rule="(self.action != 'Replace' && self.action != 'HashMod') || has(self.targetLabel)",message="targetLabel is required when action is Replace or HashMod" 296 // +kubebuilder:validation:XValidation:rule="(self.action != 'LabelDrop' && self.action != 'LabelKeep') || !has(self.sourceLabels)",message="LabelKeep and LabelDrop actions require only 'regex', and no other fields (found sourceLabels)" 297 // +kubebuilder:validation:XValidation:rule="(self.action != 'LabelDrop' && self.action != 'LabelKeep') || !has(self.targetLabel)",message="LabelKeep and LabelDrop actions require only 'regex', and no other fields (found targetLabel)" 298 // +kubebuilder:validation:XValidation:rule="(self.action != 'LabelDrop' && self.action != 'LabelKeep') || !has(self.modulus)",message="LabelKeep and LabelDrop actions require only 'regex', and no other fields (found modulus)" 299 // +kubebuilder:validation:XValidation:rule="(self.action != 'LabelDrop' && self.action != 'LabelKeep') || !has(self.separator)",message="LabelKeep and LabelDrop actions require only 'regex', and no other fields (found separator)" 300 // +kubebuilder:validation:XValidation:rule="(self.action != 'LabelDrop' && self.action != 'LabelKeep') || !has(self.replacement)",message="LabelKeep and LabelDrop actions require only 'regex', and no other fields (found replacement)" 301 // +kubebuilder:validation:XValidation:rule="!has(self.modulus) || (has(self.modulus) && size(self.sourceLabels) > 0)",message="modulus requires sourceLabels to be present" 302 // +kubebuilder:validation:XValidation:rule="(self.action == 'LabelDrop' || self.action == 'LabelKeep') || has(self.sourceLabels)",message="sourceLabels is required for actions Replace, Keep, Drop, HashMod and LabelMap" 303 // +kubebuilder:validation:XValidation:rule="(self.action != 'Replace' && self.action != 'LabelMap') || has(self.replacement)",message="replacement is required for actions Replace and LabelMap" 304 // +k8s:openapi-gen=true 305 type RelabelConfig struct { 306 // sourceLabels select values from existing labels. Their content is 307 // concatenated using the configured separator and matched against the 308 // configured regular expression for the 'Replace', 'Keep', and 'Drop' actions. 309 // Not allowed for actions 'LabelKeep' and 'LabelDrop'. 310 // 311 // +optional 312 SourceLabels []LabelName `json:"sourceLabels,omitempty"` 313 314 // separator placed between concatenated source label values. When omitted, 315 // Prometheus will use its default value of ';'. 316 // 317 // +optional 318 // +kubebuilder:validation:MaxLength=2048 319 Separator string `json:"separator,omitempty"` 320 321 // targetLabel to which the resulting value is written in a 'Replace' action. 322 // It is required for 'Replace' and 'HashMod' actions and forbidden for 323 // actions 'LabelKeep' and 'LabelDrop'. Regex capture groups 324 // are available. 325 // 326 // +optional 327 // +kubebuilder:validation:MaxLength=2048 328 TargetLabel string `json:"targetLabel,omitempty"` 329 330 // regex against which the extracted value is matched. Default is: '(.*)' 331 // regex is required for all actions except 'HashMod' 332 // 333 // +optional 334 // +kubebuilder:default=(.*) 335 // +kubebuilder:validation:MaxLength=2048 336 Regex string `json:"regex,omitempty"` 337 338 // modulus to take of the hash of the source label values. This can be 339 // combined with the 'HashMod' action to set 'target_label' to the 'modulus' 340 // of a hash of the concatenated 'source_labels'. This is only valid if 341 // sourceLabels is not empty and action is not 'LabelKeep' or 'LabelDrop'. 342 // 343 // +optional 344 Modulus uint64 `json:"modulus,omitempty"` 345 346 // replacement value against which a regex replace is performed if the regular 347 // expression matches. This is required if the action is 'Replace' or 348 // 'LabelMap' and forbidden for actions 'LabelKeep' and 'LabelDrop'. 349 // Regex capture groups are available. Default is: '$1' 350 // 351 // +optional 352 // +kubebuilder:validation:MaxLength=2048 353 Replacement string `json:"replacement,omitempty"` 354 355 // action to perform based on regex matching. Must be one of: 'Replace', 'Keep', 356 // 'Drop', 'HashMod', 'LabelMap', 'LabelDrop', or 'LabelKeep'. Default is: 'Replace' 357 // 358 // +kubebuilder:validation:Enum=Replace;Keep;Drop;HashMod;LabelMap;LabelDrop;LabelKeep 359 // +kubebuilder:default=Replace 360 // +optional 361 Action string `json:"action,omitempty"` 362 } 363