Add docs

Signed-off-by: Saswata Mukherjee <saswataminsta@yahoo.com>
thanos-io · May 14, 2021 · ffa2c74 · ffa2c74
1 parent 88caf63
commit ffa2c74
Show file tree

Hide file tree

Showing 12 changed files with 124 additions and 23 deletions.
diff --git a/cmd/thanos/config.go b/cmd/thanos/config.go
@@ -57,7 +57,7 @@ func (hc *httpConfig) registerFlag(cmd extkingpin.FlagClause) *httpConfig {
 		Default("2m").SetValue(&hc.gracePeriod)
 	cmd.Flag(
 		"http-tls-config",
-		"[EXPERIMENTAL] Path to configuration file that can enable TLS or authentication.",
+		"[EXPERIMENTAL] Path to the configuration file that can enable TLS or authentication for all HTTP endpoints.",
 	).Default("").StringVar(&hc.tlsConfig)
 	return hc
 }

diff --git a/docs/components/compact.md b/docs/components/compact.md
@@ -377,8 +377,9 @@ Flags:
                                 Listen host:port for HTTP endpoints.
       --http-grace-period=2m    Time to wait after an interrupt received for
                                 HTTP Server.
-      --http-tls-config=""      [EXPERIMENTAL] Path to configuration file that
-                                can enable TLS or authentication.
+      --http-tls-config=""      [EXPERIMENTAL] Path to the configuration file
+                                that can enable TLS or authentication for all
+                                HTTP endpoints.
       --log.format=logfmt       Log format to use. Possible options: logfmt or
                                 json.
       --log.level=info          Log filtering level.

diff --git a/docs/components/query-frontend.md b/docs/components/query-frontend.md
@@ -136,8 +136,9 @@ Flags:
                                  Listen host:port for HTTP endpoints.
       --http-grace-period=2m     Time to wait after an interrupt received for
                                  HTTP Server.
-      --http-tls-config=""       [EXPERIMENTAL] Path to configuration file that
-                                 can enable TLS or authentication.
+      --http-tls-config=""       [EXPERIMENTAL] Path to the configuration file
+                                 that can enable TLS or authentication for all
+                                 HTTP endpoints.
       --labels.default-time-range=24h
                                  The default metadata time range duration for
                                  retrieving labels through Labels and Series API

diff --git a/docs/components/query.md b/docs/components/query.md
@@ -323,8 +323,9 @@ Flags:
                                  Listen host:port for HTTP endpoints.
       --http-grace-period=2m     Time to wait after an interrupt received for
                                  HTTP Server.
-      --http-tls-config=""       [EXPERIMENTAL] Path to configuration file that
-                                 can enable TLS or authentication.
+      --http-tls-config=""       [EXPERIMENTAL] Path to the configuration file
+                                 that can enable TLS or authentication for all
+                                 HTTP endpoints.
       --log.format=logfmt        Log format to use. Possible options: logfmt or
                                  json.
       --log.level=info           Log filtering level.

diff --git a/docs/components/receive.md b/docs/components/receive.md
@@ -101,8 +101,9 @@ Flags:
                                  Listen host:port for HTTP endpoints.
       --http-grace-period=2m     Time to wait after an interrupt received for
                                  HTTP Server.
-      --http-tls-config=""       [EXPERIMENTAL] Path to configuration file that
-                                 can enable TLS or authentication.
+      --http-tls-config=""       [EXPERIMENTAL] Path to the configuration file
+                                 that can enable TLS or authentication for all
+                                 HTTP endpoints.
       --label=key="value" ...    External labels to announce. This flag will be
                                  removed in the future when handling multiple
                                  tsdb instances is added.

diff --git a/docs/components/rule.md b/docs/components/rule.md
@@ -311,8 +311,9 @@ Flags:
                                  Listen host:port for HTTP endpoints.
       --http-grace-period=2m     Time to wait after an interrupt received for
                                  HTTP Server.
-      --http-tls-config=""       [EXPERIMENTAL] Path to configuration file that
-                                 can enable TLS or authentication.
+      --http-tls-config=""       [EXPERIMENTAL] Path to the configuration file
+                                 that can enable TLS or authentication for all
+                                 HTTP endpoints.
       --label=<name>="<value>" ...
                                  Labels to be applied to all generated metrics
                                  (repeated). Similar to external labels for

diff --git a/docs/components/sidecar.md b/docs/components/sidecar.md
@@ -108,8 +108,9 @@ Flags:
                                  Listen host:port for HTTP endpoints.
       --http-grace-period=2m     Time to wait after an interrupt received for
                                  HTTP Server.
-      --http-tls-config=""       [EXPERIMENTAL] Path to configuration file that
-                                 can enable TLS or authentication.
+      --http-tls-config=""       [EXPERIMENTAL] Path to the configuration file
+                                 that can enable TLS or authentication for all
+                                 HTTP endpoints.
       --log.format=logfmt        Log format to use. Possible options: logfmt or
                                  json.
       --log.level=info           Log filtering level.

diff --git a/docs/components/store.md b/docs/components/store.md
@@ -75,8 +75,9 @@ Flags:
                                  Listen host:port for HTTP endpoints.
       --http-grace-period=2m     Time to wait after an interrupt received for
                                  HTTP Server.
-      --http-tls-config=""       [EXPERIMENTAL] Path to configuration file that
-                                 can enable TLS or authentication.
+      --http-tls-config=""       [EXPERIMENTAL] Path to the configuration file
+                                 that can enable TLS or authentication for all
+                                 HTTP endpoints.
       --ignore-deletion-marks-delay=24h
                                  Duration after which the blocks marked for
                                  deletion will be filtered out while fetching

diff --git a/docs/components/tools.md b/docs/components/tools.md
@@ -218,8 +218,9 @@ Flags:
                                 Listen host:port for HTTP endpoints.
       --http-grace-period=2m    Time to wait after an interrupt received for
                                 HTTP Server.
-      --http-tls-config=""      [EXPERIMENTAL] Path to configuration file that
-                                can enable TLS or authentication.
+      --http-tls-config=""      [EXPERIMENTAL] Path to the configuration file
+                                that can enable TLS or authentication for all
+                                HTTP endpoints.
       --label=LABEL             Prometheus label to use as timeline title
       --log.format=logfmt       Log format to use. Possible options: logfmt or
                                 json.
@@ -487,8 +488,9 @@ Flags:
                                  Listen host:port for HTTP endpoints.
       --http-grace-period=2m     Time to wait after an interrupt received for
                                  HTTP Server.
-      --http-tls-config=""       [EXPERIMENTAL] Path to configuration file that
-                                 can enable TLS or authentication.
+      --http-tls-config=""       [EXPERIMENTAL] Path to the configuration file
+                                 that can enable TLS or authentication for all
+                                 HTTP endpoints.
       --id=ID ...                Block to be replicated to the destination
                                  bucket. IDs will be used to match blocks and
                                  other matchers will be ignored. When specified,
@@ -593,8 +595,9 @@ Flags:
                               Listen host:port for HTTP endpoints.
       --http-grace-period=2m  Time to wait after an interrupt received for HTTP
                               Server.
-      --http-tls-config=""    [EXPERIMENTAL] Path to configuration file that can
-                              enable TLS or authentication.
+      --http-tls-config=""    [EXPERIMENTAL] Path to the configuration file that
+                              can enable TLS or authentication for all HTTP
+                              endpoints.
       --log.format=logfmt     Log format to use. Possible options: logfmt or
                               json.
       --log.level=info        Log filtering level.

diff --git a/docs/operating/https.md b/docs/operating/https.md
@@ -0,0 +1,92 @@
+---
+title: Running Thanos with HTTPS and basic auth
+type: docs
+menu: operating
+---
+
+# HTTPS and authentication
+
+Thanos supports basic authentication and TLS. This is **experimental** and might change in the future.
+
+To specify which HTTP TLS configuration file to load, use the `--http-tls-config` flag.
+The file is written in [YAML format](https://en.wikipedia.org/wiki/YAML), defined by the scheme described below.
+
+## Scheme
+
+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:
+
+- `<boolean>`: a boolean that can take the values `true` or `false`
+- `<filename>`: a valid path in the current working directory
+- `<secret>`: a regular string that is a secret, such as a password
+- `<string>`: a regular string
+
+```yaml
+tls_server_config:
+  # Certificate and key files for server to use to authenticate to client.
+  cert_file: <filename>
+  key_file: <filename>
+
+  # Server policy for client authentication. Maps to ClientAuth Policies.
+  # For more detail on clientAuth options:
+  # https://golang.org/pkg/crypto/tls/#ClientAuthType
+  [ client_auth_type: <string> | default = "NoClientCert" ]
+
+  # CA certificate for client certificate authentication to the server.
+  [ client_ca_file: <filename> ]
+
+  # Minimum TLS version that is acceptable.
+  [ min_version: <string> | default = "TLS12" ]
+
+  # Maximum TLS version that is acceptable.
+  [ max_version: <string> | default = "TLS13" ]
+
+  # List of supported cipher suites for TLS versions up to TLS 1.2. If empty,
+  # Go default cipher suites are used. Available cipher suites are documented
+  # in the go documentation:
+  # https://golang.org/pkg/crypto/tls/#pkg-constants
+  [ cipher_suites:
+    [ - <string> ] ]
+
+  # prefer_server_cipher_suites controls whether the server selects the
+  # client's most preferred ciphersuite, or the server's most preferred
+  # ciphersuite. If true then the server's preference, as expressed in
+  # the order of elements in cipher_suites, is used.
+  [ prefer_server_cipher_suites: <bool> | default = true ]
+
+  # Elliptic curves that will be used in an ECDHE handshake, in preference
+  # order. Available curves are documented in the go documentation:
+  # https://golang.org/pkg/crypto/tls/#CurveID
+  [ curve_preferences:
+    [ - <string> ] ]
+
+http_server_config:
+  # Enable HTTP/2 support. Note that HTTP/2 is only supported with TLS.
+  # This can not be changed on the fly.
+  [ http2: <boolean> | default = true ]
+
+# Usernames and hashed passwords that have full access to the web
+# server via basic authentication. If empty, no basic authentication is
+# required. Passwords are hashed with bcrypt.
+basic_auth_users:
+  [ <string>: <secret> ... ]
+```
+
+## Example
+
+An example configuration file is provided below,
+
+```yaml
+# A certificate and a key file are needed.
+tls_server_config:
+  cert_file: server.crt
+  key_file: server.key
+
+# Usernames and passwords required to connect to Thanos.
+# Passwords are hashed with bcrypt.
+basic_auth_users:
+  alice: $2y$10$mDwo.lAisC94iLAyP81MCesa29IzH37oigHC/42V2pdJlUprsJPze
+  bob: $2y$10$hLqFl9jSjoAAy95Z/zw8Ye8wkdMBM8c5Bn1ptYqP/AXyV0.oy0S8m
+```
diff --git a/pkg/extkingpin/flags.go b/pkg/extkingpin/flags.go
@@ -48,7 +48,7 @@ func RegisterHTTPFlags(cmd FlagClause) (httpBindAddr *string, httpGracePeriod *m
 	httpGracePeriod = ModelDuration(cmd.Flag("http-grace-period", "Time to wait after an interrupt received for HTTP Server.").Default("2m")) // by default it's the same as query.timeout.
 	httpTLSConfig = cmd.Flag(
 		"http-tls-config",
-		"[EXPERIMENTAL] Path to configuration file that can enable TLS or authentication.",
+		"[EXPERIMENTAL] Path to the configuration file that can enable TLS or authentication for all HTTP endpoints.",
 	).Default("").String()
 	return httpBindAddr, httpGracePeriod, httpTLSConfig
 }

diff --git a/pkg/server/http/http.go b/pkg/server/http/http.go
@@ -63,7 +63,6 @@ func (s *Server) ListenAndServe() error {
 	level.Info(s.logger).Log("msg", "listening for requests and metrics", "address", s.opts.listen)
 	err := toolkit_web.Validate(s.opts.tlsConfigPath)
 	if err != nil {
-		level.Error(s.logger).Log("msg", "server could not be started", "err", err)
 		return errors.Wrap(err, "server could not be started")
 	}
 	return errors.Wrap(toolkit_web.ListenAndServe(s.srv, s.opts.tlsConfigPath, s.logger), "serve HTTP and metrics")