cloudflare/pint
Publicmirrored from https://github.com/cloudflare/pintAvailable
docs/configuration.md
241lines · modecode
| 1 | --- |
| 2 | layout: default |
| 3 | title: Configuration |
| 4 | parent: Documentation |
| 5 | nav_order: 2 |
| 6 | --- |
| 7 | |
| 8 | # Configuration syntax |
| 9 | |
| 10 | ## Table of contents |
| 11 | {: .no_toc .text-delta } |
| 12 | |
| 13 | 1. TOC |
| 14 | {:toc} |
| 15 | |
| 16 | **NOTE**: all regex patterns are anchored. |
| 17 | |
| 18 | ## CI |
| 19 | |
| 20 | Configure continuous integration environments. |
| 21 | |
| 22 | Syntax: |
| 23 | |
| 24 | ```js |
| 25 | ci { |
| 26 | include = [ "(.*)", ... ] |
| 27 | maxCommits = 20 |
| 28 | baseBranch = "master" |
| 29 | } |
| 30 | ``` |
| 31 | |
| 32 | - `include` - list of file patterns to check when running checks. Only files |
| 33 | matching those regex rules will be checked, other modified files will be ignored. |
| 34 | - `maxCommits` - by default pint will try to find all commits on the current branch, |
| 35 | this requires full git history to be present, if we have a shallow clone this |
| 36 | might fail to find only current branch commits and give us a huge list. |
| 37 | If the number of commits returned by branch discovery is more than `maxCommits` |
| 38 | then pint will fail to run. |
| 39 | - `baseBranch` - base branch to compare `HEAD` commit with when calculating the list |
| 40 | of commits to check. |
| 41 | |
| 42 | ## Repository |
| 43 | |
| 44 | Configure supported code hosting repository, used for reporting PR checks from CI |
| 45 | back to the repository, to be displayed in the PR UI. |
| 46 | Currently it only supports [BitBucket](https://bitbucket.org/) and [GitHub](https://github.com/). |
| 47 | |
| 48 | **NOTE**: BitBucket integration requires `BITBUCKET_AUTH_TOKEN` environment variable |
| 49 | to be set. It should contain a personal access token used to authenticate with the API. |
| 50 | |
| 51 | **NOTE**: GitHub integration requires `GITHUB_AUTH_TOKEN` environment variable |
| 52 | to be set to a personal access key that can access your repository. Also, `GITHUB_PULL_REQUEST_NUMBER` |
| 53 | environment variable needs to point to the pull request number which will be used whilst |
| 54 | submitting comments. |
| 55 | |
| 56 | Syntax: |
| 57 | |
| 58 | ```js |
| 59 | repository { |
| 60 | bitbucket { |
| 61 | uri = "https://..." |
| 62 | timeout = "30s" |
| 63 | project = "..." |
| 64 | repository = "..." |
| 65 | } |
| 66 | } |
| 67 | ``` |
| 68 | |
| 69 | - `bitbucket:uri` - base URI of this repository, will be used for HTTP |
| 70 | requests to the BitBucket API. |
| 71 | - `bitbucket:timeout` - timeout to be used for API requests. |
| 72 | - `bitbucket:project` - name of the BitBucket project for this repository. |
| 73 | - `bitbucket:repository` - name of the BitBucket repository. |
| 74 | |
| 75 | ```js |
| 76 | repository { |
| 77 | github { |
| 78 | baseuri = "https://..." |
| 79 | uploaduri = "https://..." |
| 80 | timeout = "30s" |
| 81 | owner = "..." |
| 82 | repo = "..." |
| 83 | } |
| 84 | } |
| 85 | ``` |
| 86 | |
| 87 | - `github:baseuri` - base URI of GitHub or GitHub enterprise, will be used for HTTP requests to the GitHub API. |
| 88 | - `github:uploaduri` - upload URI of GitHub or GitHub enterprise, will be used for HTTP requests to the GitHub API. |
| 89 | |
| 90 | If `github:baseuri` _or_ `github:uploaduri` are not specified then [GitHub](https://github.com) will be used. |
| 91 | |
| 92 | - `github:timeout` - timeout to be used for API requests; |
| 93 | - `github:owner` - name of the GitHub owner i.e. the first part that comes before the repository's name in the URI; |
| 94 | - `github:repo` - name of the GitHub repository (e.g. `monitoring`). |
| 95 | |
| 96 | ## Prometheus servers |
| 97 | |
| 98 | Some checks work by querying a running Prometheus instance to verify if |
| 99 | metrics used in rules are present. If you want to use those checks then you |
| 100 | first need to define one or more Prometheus servers. |
| 101 | |
| 102 | Syntax: |
| 103 | |
| 104 | ```js |
| 105 | prometheus "$name" { |
| 106 | uri = "https://..." |
| 107 | failover = ["https://...", ...] |
| 108 | timeout = "60s" |
| 109 | required = true|false |
| 110 | paths = ["...", ...] |
| 111 | } |
| 112 | ``` |
| 113 | |
| 114 | - `$name` - each defined server should have a unique name that can be used in check |
| 115 | definitions. |
| 116 | - `uri` - base URI of this Prometheus server, used for API requests and queries. |
| 117 | - `failover` - list of URIs to try (in order they are specified) if `uri` doesn't respond |
| 118 | to requests or returns an error. This allows to configure failover Prometheus servers |
| 119 | to avoid CI failures in case main Prometheus server is unreachable. |
| 120 | Failover URIs are not used if Prometheus returns an error caused by the query, like |
| 121 | `many-to-many matching not allowed`. |
| 122 | It's highly recommended that all URIs point to Prometheus servers with identical |
| 123 | configuration, otherwise pint checks might return unreliable results and potential |
| 124 | false positives. |
| 125 | - `timeout` - timeout to be used for API requests. |
| 126 | - `required` - decides how pint will report errors if it's unable to get a valid response |
| 127 | from this Prometheus server. If `required` is `true` and all API calls to this Prometheus |
| 128 | fail pint will report those as `bug` level problem. If it's set to `false` pint will |
| 129 | report those with `warning` level. |
| 130 | Default value for `required` is `false`. Set it to `true` if you want to hard fail |
| 131 | in case of remote Prometheus issues. Note that setting it to `true` might block |
| 132 | PRs when running `pint ci` until pint is able to talk to Prometheus again. |
| 133 | - `paths` - optional path filter, if specified only paths matching one of listed regex |
| 134 | patterns will use this Prometheus server for checks. |
| 135 | |
| 136 | Example: |
| 137 | |
| 138 | ```js |
| 139 | prometheus "prod" { |
| 140 | uri = "https://prometheus-prod.example.com" |
| 141 | timeout = "60s" |
| 142 | } |
| 143 | |
| 144 | prometheus "dev" { |
| 145 | uri = "https://prometheus-dev.example.com" |
| 146 | timeout = "30s" |
| 147 | paths = [ "alerts/test/.*" ] |
| 148 | } |
| 149 | ``` |
| 150 | |
| 151 | ## Matching rules to checks |
| 152 | |
| 153 | Most checks, except basic syntax verification, requires some configuration to decide |
| 154 | which checks to run against which files and rules. |
| 155 | |
| 156 | Syntax: |
| 157 | |
| 158 | ```js |
| 159 | rule { |
| 160 | match { |
| 161 | path = "(.+)" |
| 162 | name = "(.+)" |
| 163 | kind = "alerting|recording" |
| 164 | command = "ci|lint|watch" |
| 165 | annotation "(.*)" { |
| 166 | value = "(.*)" |
| 167 | } |
| 168 | label "(.*)" { |
| 169 | value = "(.*)" |
| 170 | } |
| 171 | } |
| 172 | match { ... } |
| 173 | match { ... } |
| 174 | ignore { |
| 175 | path = "(.+)" |
| 176 | name = "(.+)" |
| 177 | kind = "alerting|recording" |
| 178 | command = "ci|lint|watch" |
| 179 | annotation "(.*)" { |
| 180 | value = "(.*)" |
| 181 | } |
| 182 | label "(.*)" { |
| 183 | value = "(.*)" |
| 184 | } |
| 185 | } |
| 186 | ignore { ... } |
| 187 | ignore { ... } |
| 188 | |
| 189 | [ check definition ] |
| 190 | ... |
| 191 | [ check definition ] |
| 192 | } |
| 193 | ``` |
| 194 | |
| 195 | - `match:path` - only files matching this pattern will be checked by this rule |
| 196 | - `match:name` - only rules with names (`record` for recording rules and `alert` for alerting |
| 197 | rules) matching this pattern will be checked rule |
| 198 | - `match:kind` - optional rule type filter, only rule of this type will be checked |
| 199 | - `match:command` - optional command type filter, this allows to include or ignore rules |
| 200 | based on the command pint is run with `pint ci`, `pint lint` or `pint watch`. |
| 201 | - `match:annotation` - optional annotation filter, only alert rules with at least one |
| 202 | annotation matching this pattern will be checked by this rule. |
| 203 | - `match:label` - optional annotation filter, only rules with at least one label |
| 204 | matching this pattern will be checked by this rule. For recording rules only static |
| 205 | labels set on the recording rule are considered. |
| 206 | - `ignore` - works exactly like `match` but does the opposite - any alerting or recording rule |
| 207 | matching all conditions defined on `ignore` will not be checked by this `rule` block. |
| 208 | |
| 209 | Note: both `match` and `ignore` require all defined filters to be satisfied to work. |
| 210 | If multiple `match` and/or `ignore` rules are present any of them needs to match for the rule to |
| 211 | be matched / ignored. |
| 212 | |
| 213 | Examples: |
| 214 | |
| 215 | ```js |
| 216 | rule { |
| 217 | match { |
| 218 | path = "rules/.*" |
| 219 | kind = "alerting" |
| 220 | label "severity" { |
| 221 | value = "(warning|critical)" |
| 222 | } |
| 223 | } |
| 224 | ignore { |
| 225 | command = "watch" |
| 226 | } |
| 227 | [ check applied only to severity="critical" and severity="warning" alerts in "ci" or "lint" command is run ] |
| 228 | } |
| 229 | ``` |
| 230 | |
| 231 | ```js |
| 232 | rule { |
| 233 | ignore { |
| 234 | command = "watch" |
| 235 | } |
| 236 | ignore { |
| 237 | command = "lint" |
| 238 | } |
| 239 | [ check applied unless "watch" or "lint" command is run ] |
| 240 | } |
| 241 | ``` |
| 242 | |