docs: Added documentation for promtool configuration with http.config.file (#16522)

Includes an example.

Signed-off-by: RaphSku <rapsku.dev@gmail.com>

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("<filename>").ExistingFileVar(&httpConfigFilePath)
+	checkServerHealthCmd.Flag("http.config.file", httpConfigFileDescription).PlaceHolder("<filename>").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("<filename>").ExistingFileVar(&httpConfigFilePath)
+	checkServerReadyCmd.Flag("http.config.file", httpConfigFileDescription).PlaceHolder("<filename>").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("<filename>").ExistingFileVar(&httpConfigFilePath)
+	queryCmd.Flag("http.config.file", httpConfigFileDescription).PlaceHolder("<filename>").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("<filename>").ExistingFileVar(&httpConfigFilePath)
+	pushCmd.Flag("http.config.file", httpConfigFileDescription).PlaceHolder("<filename>").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("<filename>").ExistingFileVar(&httpConfigFilePath)
+	importRulesCmd.Flag("http.config.file", httpConfigFileDescription).PlaceHolder("<filename>").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()

docs/command-line/promtool.md

@@ -142,7 +142,7 @@ Check if the Prometheus server is healthy.
 
 | Flag | Description | Default |
 | --- | --- | --- |
-| <code class="text-nowrap">--http.config.file</code> | HTTP client configuration file for promtool to connect to Prometheus. |  |
+| <code class="text-nowrap">--http.config.file</code> | HTTP client configuration file, see details at https://prometheus.io/docs/prometheus/latest/configuration/promtool |  |
 | <code class="text-nowrap">--url</code> | The URL for the Prometheus server. | `http://localhost:9090` |
 
 
@@ -158,7 +158,7 @@ Check if the Prometheus server is ready.
 
 | Flag | Description | Default |
 | --- | --- | --- |
-| <code class="text-nowrap">--http.config.file</code> | HTTP client configuration file for promtool to connect to Prometheus. |  |
+| <code class="text-nowrap">--http.config.file</code> | HTTP client configuration file, see details at https://prometheus.io/docs/prometheus/latest/configuration/promtool |  |
 | <code class="text-nowrap">--url</code> | The URL for the Prometheus server. | `http://localhost:9090` |
 
 
@@ -213,7 +213,7 @@ Run query against a Prometheus server.
 | Flag | Description | Default |
 | --- | --- | --- |
 | <code class="text-nowrap">-o</code>, <code class="text-nowrap">--format</code> | Output format of the query. | `promql` |
-| <code class="text-nowrap">--http.config.file</code> | HTTP client configuration file for promtool to connect to Prometheus. |  |
+| <code class="text-nowrap">--http.config.file</code> | 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 |
 | --- | --- |
-| <code class="text-nowrap">--http.config.file</code> | HTTP client configuration file for promtool to connect to Prometheus. |
+| <code class="text-nowrap">--http.config.file</code> | 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 |
 | --- | --- | --- |
-| <code class="text-nowrap">--http.config.file</code> | HTTP client configuration file for promtool to connect to Prometheus. |  |
+| <code class="text-nowrap">--http.config.file</code> | HTTP client configuration file, see details at https://prometheus.io/docs/prometheus/latest/configuration/promtool |  |
 | <code class="text-nowrap">--url</code> | The URL for the Prometheus API with the data where the rule will be backfilled from. | `http://localhost:9090` |
 | <code class="text-nowrap">--start</code> | The time to start backfilling the new rule from. Must be a RFC3339 formatted date or Unix timestamp. Required. |  |
 | <code class="text-nowrap">--end</code> | 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. |  |

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:
+
+* `<bool>`: a boolean that can take the values `true` or `false`
+* `<filename>`: a valid path to a file
+* `<secret>`: a regular string that is a secret, such as a password
+* `<string>`: 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: <string> ]
+  [ username_file: <filename> ]
+  [ username_ref: <string> ]
+  [ password: <secret> ]
+  [ password_file: <string> ]
+  [ password_ref: <string> ]
+
+# Optional the `Authorization` header configuration.
+authorization:
+  # Sets the authentication type.
+  [ type: <string> | default: Bearer ]
+  # Sets the credentials. It is mutually exclusive with
+  # `credentials_file`.
+  [ credentials: <secret> ]
+  # Sets the credentials with the credentials read from the configured file.
+  # It is mutually exclusive with `credentials`.
+  [ credentials_file: <filename> ]
+  [ credentials_ref: <string> ]
+
+# Optional OAuth 2.0 configuration.
+# Cannot be used at the same time as basic_auth or authorization.
+oauth2:
+  [ <oauth2> ]
+
+tls_config:
+  [ <tls_config> ]
+
+[ follow_redirects: <bool> | default: true ]
+
+# Whether to enable HTTP2.
+[ enable_http2: <bool> | default: true ]
+
+# Optional proxy URL.
+[ proxy_url: <string> ]
+# 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: <string> ]
+[ proxy_from_environment: <bool> ]
+[ proxy_connect_header:
+  [ <string>: [ <secret>, ... ] ] ]
+
+# `http_headers` specifies a set of headers that will be injected into each request.
+http_headers:
+  [ <string>: <header> ]
+```
+
+## \<oauth2\>
+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: <string>
+[ client_secret: <secret> ]
+[ client_secret_file: <filename> ]
+[ client_secret_ref: <string> ]
+
+# `scopes` specify the reason for the resource access.
+scopes:
+  [ - <string> ...]
+
+# The URL to fetch the token from.
+token_url: <string>
+
+# Optional parameters to append to the token URL.
+[ endpoint_params:
+    <string>: <string> ... ]
+
+# Configures the token request's TLS settings.
+tls_config:
+  [ <tls_config> ]
+
+# Optional proxy URL.
+[ proxy_url: <string> ]
+# 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: <string> ]
+[ proxy_from_environment: <bool> ]
+[ proxy_connect_header:
+  [ <string>: [ <secret>, ... ] ] ]
+```
+
+## <tls_config>
+```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: <string> ]
+# CA certificate to validate the server certificate witth.
+[ ca_file: <filename> ]
+# `ca_ref` is the name of the secret within the secret manager to use as the CA cert.
+[ ca_ref: <string> ]
+
+# Text of the client cert file for the server.
+[ cert: <string> ]
+# Certficate file for client certificate authentication.
+[ cert_file: <filename> ]
+# `cert_ref` is the name of the secret within the secret manager to use as the client certificate.
+[ cert_ref: <string> ]
+
+# Text of the client key file for the server.
+[ key: <secret> ]
+# Key file for client certificate authentication.
+[ key_file: <filename> ]
+# `key_ref` is the name of the secret within the secret manager to use as the client key.
+[ key_ref: <string> ]
+
+# ServerName extension to indicate the name of the server.
+# http://tools.ietf.org/html/rfc4366#section-3.1
+[ server_name: <string> ]
+
+# Disable validation of the server certificate.
+[ insecure_skip_verify: <bool> ]
+
+# 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: <string> ]
+# 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: <string> ]
+```
+
+## \<header\>
+`header` represents the configuration for a single HTTP header.
+```yaml
+[ values:
+  [ - <string> ... ] ]
+
+[ secrets:
+  [ - <secret> ... ] ]
+
+[ files:
+  [ - <filename> ... ] ]
+```

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