mirror of
https://github.com/prometheus/prometheus.git
synced 2025-08-05 13:47:10 +02:00
docs: Added documentation for promtool configuration with http.config.file (#16522)
Includes an example. Signed-off-by: RaphSku <rapsku.dev@gmail.com>
This commit is contained in:
RaphSku
GitHub
parent
21b1536b5a
commit
938e5cb62b
@ -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()
|
||||
|
||||
@ -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. | |
|
||||
|
||||
175
docs/configuration/promtool.md
Normal file
175
docs/configuration/promtool.md
Normal file
@ -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> ... ] ]
|
||||
```
|
||||
12
documentation/examples/promtool-http-config-file.yml
Normal file
12
documentation/examples/promtool-http-config-file.yml
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user