diff --git a/cmd/promtool/main.go b/cmd/promtool/main.go index c6a5801d28..7b5b6a603a 100644 --- a/cmd/promtool/main.go +++ b/cmd/promtool/main.go @@ -89,6 +89,8 @@ var ( lintConfigOptions = append(append([]string{}, lintRulesOptions...), lintOptionTooLongScrapeInterval) ) +const httpConfigFileDescription = "HTTP client configuration file, see details at https://prometheus.io/docs/prometheus/latest/configuration/promtool" + func main() { var ( httpRoundTripper = api.DefaultRoundTripper @@ -138,11 +140,11 @@ func main() { ).Required().ExistingFiles() checkServerHealthCmd := checkCmd.Command("healthy", "Check if the Prometheus server is healthy.") - checkServerHealthCmd.Flag("http.config.file", "HTTP client configuration file for promtool to connect to Prometheus.").PlaceHolder("").ExistingFileVar(&httpConfigFilePath) + checkServerHealthCmd.Flag("http.config.file", httpConfigFileDescription).PlaceHolder("").ExistingFileVar(&httpConfigFilePath) checkServerHealthCmd.Flag("url", "The URL for the Prometheus server.").Default("http://localhost:9090").URLVar(&serverURL) checkServerReadyCmd := checkCmd.Command("ready", "Check if the Prometheus server is ready.") - checkServerReadyCmd.Flag("http.config.file", "HTTP client configuration file for promtool to connect to Prometheus.").PlaceHolder("").ExistingFileVar(&httpConfigFilePath) + checkServerReadyCmd.Flag("http.config.file", httpConfigFileDescription).PlaceHolder("").ExistingFileVar(&httpConfigFilePath) checkServerReadyCmd.Flag("url", "The URL for the Prometheus server.").Default("http://localhost:9090").URLVar(&serverURL) checkRulesCmd := checkCmd.Command("rules", "Check if the rule files are valid or not.") @@ -165,7 +167,7 @@ func main() { queryCmd := app.Command("query", "Run query against a Prometheus server.") queryCmdFmt := queryCmd.Flag("format", "Output format of the query.").Short('o').Default("promql").Enum("promql", "json") - queryCmd.Flag("http.config.file", "HTTP client configuration file for promtool to connect to Prometheus.").PlaceHolder("").ExistingFileVar(&httpConfigFilePath) + queryCmd.Flag("http.config.file", httpConfigFileDescription).PlaceHolder("").ExistingFileVar(&httpConfigFilePath) queryInstantCmd := queryCmd.Command("instant", "Run instant query.") queryInstantCmd.Arg("server", "Prometheus server to query.").Required().URLVar(&serverURL) @@ -210,7 +212,7 @@ func main() { queryAnalyzeCmd.Flag("match", "Series selector. Can be specified multiple times.").Required().StringsVar(&queryAnalyzeCfg.matchers) pushCmd := app.Command("push", "Push to a Prometheus server.") - pushCmd.Flag("http.config.file", "HTTP client configuration file for promtool to connect to Prometheus.").PlaceHolder("").ExistingFileVar(&httpConfigFilePath) + pushCmd.Flag("http.config.file", httpConfigFileDescription).PlaceHolder("").ExistingFileVar(&httpConfigFilePath) pushMetricsCmd := pushCmd.Command("metrics", "Push metrics to a prometheus remote write (for testing purpose only).") pushMetricsCmd.Arg("remote-write-url", "Prometheus remote write url to push metrics.").Required().URLVar(&remoteWriteURL) metricFiles := pushMetricsCmd.Arg( @@ -277,7 +279,7 @@ func main() { importFilePath := openMetricsImportCmd.Arg("input file", "OpenMetrics file to read samples from.").Required().String() importDBPath := openMetricsImportCmd.Arg("output directory", "Output directory for generated blocks.").Default(defaultDBPath).String() importRulesCmd := importCmd.Command("rules", "Create blocks of data for new recording rules.") - importRulesCmd.Flag("http.config.file", "HTTP client configuration file for promtool to connect to Prometheus.").PlaceHolder("").ExistingFileVar(&httpConfigFilePath) + importRulesCmd.Flag("http.config.file", httpConfigFileDescription).PlaceHolder("").ExistingFileVar(&httpConfigFilePath) importRulesCmd.Flag("url", "The URL for the Prometheus API with the data where the rule will be backfilled from.").Default("http://localhost:9090").URLVar(&serverURL) importRulesStart := importRulesCmd.Flag("start", "The time to start backfilling the new rule from. Must be a RFC3339 formatted date or Unix timestamp. Required."). Required().String() diff --git a/docs/command-line/promtool.md b/docs/command-line/promtool.md index 92e0ac0030..ec9e5d62af 100644 --- a/docs/command-line/promtool.md +++ b/docs/command-line/promtool.md @@ -142,7 +142,7 @@ Check if the Prometheus server is healthy. | Flag | Description | Default | | --- | --- | --- | -| --http.config.file | HTTP client configuration file for promtool to connect to Prometheus. | | +| --http.config.file | HTTP client configuration file, see details at https://prometheus.io/docs/prometheus/latest/configuration/promtool | | | --url | The URL for the Prometheus server. | `http://localhost:9090` | @@ -158,7 +158,7 @@ Check if the Prometheus server is ready. | Flag | Description | Default | | --- | --- | --- | -| --http.config.file | HTTP client configuration file for promtool to connect to Prometheus. | | +| --http.config.file | HTTP client configuration file, see details at https://prometheus.io/docs/prometheus/latest/configuration/promtool | | | --url | The URL for the Prometheus server. | `http://localhost:9090` | @@ -213,7 +213,7 @@ Run query against a Prometheus server. | Flag | Description | Default | | --- | --- | --- | | -o, --format | Output format of the query. | `promql` | -| --http.config.file | HTTP client configuration file for promtool to connect to Prometheus. | | +| --http.config.file | HTTP client configuration file, see details at https://prometheus.io/docs/prometheus/latest/configuration/promtool | | @@ -404,7 +404,7 @@ Push to a Prometheus server. | Flag | Description | | --- | --- | -| --http.config.file | HTTP client configuration file for promtool to connect to Prometheus. | +| --http.config.file | HTTP client configuration file, see details at https://prometheus.io/docs/prometheus/latest/configuration/promtool | @@ -672,7 +672,7 @@ Create blocks of data for new recording rules. | Flag | Description | Default | | --- | --- | --- | -| --http.config.file | HTTP client configuration file for promtool to connect to Prometheus. | | +| --http.config.file | HTTP client configuration file, see details at https://prometheus.io/docs/prometheus/latest/configuration/promtool | | | --url | The URL for the Prometheus API with the data where the rule will be backfilled from. | `http://localhost:9090` | | --start | The time to start backfilling the new rule from. Must be a RFC3339 formatted date or Unix timestamp. Required. | | | --end | If an end time is provided, all recording rules in the rule files provided will be backfilled to the end time. Default will backfill up to 3 hours ago. Must be a RFC3339 formatted date or Unix timestamp. | | diff --git a/docs/configuration/promtool.md b/docs/configuration/promtool.md new file mode 100644 index 0000000000..7578ef90b3 --- /dev/null +++ b/docs/configuration/promtool.md @@ -0,0 +1,175 @@ +--- +title: HTTP configuration for promtool +sort_rank: 6 +--- + +Promtool is a versatile CLI tool for Prometheus that supports validation, debugging, querying, unit testing, tsdb management, pushing data, and experimental PromQL editing. + +Prometheus supports basic authentication and TLS. Since promtool needs to connect to Prometheus, we need to provide the authentication details. To specify those authentication details, use the `--http.config.file` for all requests that need to communicate with Prometheus. +For instance, if you would like to check whether your local Prometheus server is healthy, you would use: +```bash +promtool check healthy --url=http://localhost:9090 --http.config.file=http-config-file.yml +``` + +The file is written in [YAML format](https://en.wikipedia.org/wiki/YAML), defined by the schema described below. +Brackets indicate that a parameter is optional. For non-list parameters the value is set to the specified default. + +The file is read upon every http request, such as any change in the +configuration and the certificates is picked up immediately. + +Generic placeholders are defined as follows: + +* ``: a boolean that can take the values `true` or `false` +* ``: a valid path to a file +* ``: a regular string that is a secret, such as a password +* ``: a regular string + +A valid example file can be found [here](/documentation/examples/promtool-http-config-file.yml). + +```yaml +# Note that `basic_auth` and `authorization` options are mutually exclusive. + +# Sets the `Authorization` header with the configured username and password. +# `username_ref` and `password_ref`refer to the name of the secret within the secret manager. +# `password`, `password_file` and `password_ref` are mutually exclusive. +basic_auth: + [ username: ] + [ username_file: ] + [ username_ref: ] + [ password: ] + [ password_file: ] + [ password_ref: ] + +# Optional the `Authorization` header configuration. +authorization: + # Sets the authentication type. + [ type: | default: Bearer ] + # Sets the credentials. It is mutually exclusive with + # `credentials_file`. + [ credentials: ] + # Sets the credentials with the credentials read from the configured file. + # It is mutually exclusive with `credentials`. + [ credentials_file: ] + [ credentials_ref: ] + +# Optional OAuth 2.0 configuration. +# Cannot be used at the same time as basic_auth or authorization. +oauth2: + [ ] + +tls_config: + [ ] + +[ follow_redirects: | default: true ] + +# Whether to enable HTTP2. +[ enable_http2: | default: true ] + +# Optional proxy URL. +[ proxy_url: ] +# Comma-separated string that can contain IPs, CIDR notation, domain names +# that should be excluded from proxying. IP and domain names can +# contain port numbers. +[ no_proxy: ] +[ proxy_from_environment: ] +[ proxy_connect_header: + [ : [ , ... ] ] ] + +# `http_headers` specifies a set of headers that will be injected into each request. +http_headers: + [ :
] +``` + +## \ +OAuth 2.0 authentication using the client credentials grant type. +```yaml +# `client_id` and `client_secret` are used to authenticate your +# application with the authorization server in order to get +# an access token. +# `client_secret`, `client_secret_file` and `client_secret_ref` are mutually exclusive. +client_id: +[ client_secret: ] +[ client_secret_file: ] +[ client_secret_ref: ] + +# `scopes` specify the reason for the resource access. +scopes: + [ - ...] + +# The URL to fetch the token from. +token_url: + +# Optional parameters to append to the token URL. +[ endpoint_params: + : ... ] + +# Configures the token request's TLS settings. +tls_config: + [ ] + +# Optional proxy URL. +[ proxy_url: ] +# Comma-separated string that can contain IPs, CIDR notation, domain names +# that should be excluded from proxying. IP and domain names can +# contain port numbers. +[ no_proxy: ] +[ proxy_from_environment: ] +[ proxy_connect_header: + [ : [ , ... ] ] ] +``` + +## +```yaml +# For the following configurations, use either `ca`, `cert` and `key` or `ca_file`, `cert_file` and `key_file` or use `ca_ref`, `cert_ref` or `key_ref`. +# Text of the CA certificate to use for the server. +[ ca: ] +# CA certificate to validate the server certificate witth. +[ ca_file: ] +# `ca_ref` is the name of the secret within the secret manager to use as the CA cert. +[ ca_ref: ] + +# Text of the client cert file for the server. +[ cert: ] +# Certficate file for client certificate authentication. +[ cert_file: ] +# `cert_ref` is the name of the secret within the secret manager to use as the client certificate. +[ cert_ref: ] + +# Text of the client key file for the server. +[ key: ] +# Key file for client certificate authentication. +[ key_file: ] +# `key_ref` is the name of the secret within the secret manager to use as the client key. +[ key_ref: ] + +# ServerName extension to indicate the name of the server. +# http://tools.ietf.org/html/rfc4366#section-3.1 +[ server_name: ] + +# Disable validation of the server certificate. +[ insecure_skip_verify: ] + +# Minimum acceptable TLS version. Accepted values: TLS10 (TLS 1.0), TLS11 (TLS +# 1.1), TLS12 (TLS 1.2), TLS13 (TLS 1.3). +# If unset, promtool will use Go default minimum version, which is TLS 1.2. +# See MinVersion in https://pkg.go.dev/crypto/tls#Config. +[ min_version: ] +# Maximum acceptable TLS version. Accepted values: TLS10 (TLS 1.0), TLS11 (TLS +# 1.1), TLS12 (TLS 1.2), TLS13 (TLS 1.3). +# If unset, promtool will use Go default maximum version, which is TLS 1.3. +# See MaxVersion in https://pkg.go.dev/crypto/tls#Config. +[ max_version: ] +``` + +## \ +`header` represents the configuration for a single HTTP header. +```yaml +[ values: + [ - ... ] ] + +[ secrets: + [ - ... ] ] + +[ files: + [ - ... ] ] +``` diff --git a/documentation/examples/promtool-http-config-file.yml b/documentation/examples/promtool-http-config-file.yml new file mode 100644 index 0000000000..ef07ab8250 --- /dev/null +++ b/documentation/examples/promtool-http-config-file.yml @@ -0,0 +1,12 @@ +# TLS and basic authentication configuration example. + +# For `basic_auth`, use the Prometheus credentials configured earlier in the `web-config.yml` file. +# The password must be provided in plaintext. +# To avoid including plaintext passwords directly in this file, consider using `password_file` or `password_ref` instead. +basic_auth: + username: alice + password: verylongpassword + +tls_config: + cert_file: server.crt + key_file: server.key