You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
memchr,https://github.com/BurntSushi/memchr,Unlicense OR MIT,"Andrew Gallant <jamslam@gmail.com>, bluss"
471
475
memmap2,https://github.com/RazrFalcon/memmap2-rs,MIT OR Apache-2.0,"Dan Burkert <dan@danburkert.com>, Yevhenii Reizner <razrfalcon@gmail.com>, The Contributors"
472
476
metrics,https://github.com/metrics-rs/metrics,MIT,Toby Lawrence <toby@nuclearfurnace.com>
473
-
metrics-exporter-otel,https://github.com/palindrom615/metrics,MIT,Whoemoon Jang <palindrom615@gmail.com>
474
477
metrics-exporter-prometheus,https://github.com/metrics-rs/metrics,MIT AND Apache-2.0,Toby Lawrence <toby@nuclearfurnace.com>
|`max_message_size`| The maximum size (in bytes) of messages exchanged by internal gRPC clients and services. ||`20 MiB`|
78
+
|`tls`| Enables TLS for gRPC services and clients. [Read more](#tls-configuration)|||
77
79
78
80
Example of a gRPC configuration:
79
81
@@ -87,6 +89,85 @@ We advise changing the default value of 20 MiB only if you encounter the followi
87
89
`Error, message length too large: found 24732228 bytes, the limit is: 20971520 bytes.` In that case, increase `max_message_size` by increments of 10 MiB until the issue disappears. This is a temporary fix: the next version of Quickwit will rely exclusively on gRPC streaming endpoints and handle messages of any length.
88
90
:::
89
91
92
+
## Health check configuration
93
+
94
+
This section configures an optional, **plaintext (no TLS)** HTTP server that exposes only the health endpoints `/health/livez` (liveness) and `/health/readyz` (readiness). Its purpose is to let liveness/readiness probes (for example from Kubernetes or a load balancer) reach the node even when the main REST API is put behind [TLS or mTLS](#tls-configuration), which a simple HTTP probe cannot negotiate.
95
+
96
+
The health server is **disabled by default**. It starts only when `listen_port` is set (or the `QW_HEALTH_LISTEN_PORT` environment variable is provided). The same `/health/*` endpoints always remain available on the main REST API as well.
| `listen_port` | The port on which the plaintext health server listens for HTTP traffic. When unset, the health server is disabled. | `QW_HEALTH_LISTEN_PORT` | _(disabled)_ |
101
+
102
+
Pick a free port that is not already used by the REST or gRPC servers.
103
+
104
+
Example of a health check configuration:
105
+
106
+
```yaml
107
+
health:
108
+
listen_port: 7282
109
+
```
110
+
111
+
:::warning
112
+
This server performs no TLS termination and no client authentication. Bind it to a cluster-internal interface (via `listen_address`) and do not expose it publicly.
113
+
:::
114
+
115
+
## TLS configuration
116
+
117
+
Both the REST API (`rest.tls`) and the internal gRPC services (`grpc.tls`) can be secured with TLS, optionally with mutual TLS (mTLS). The two sections share the same properties:
118
+
119
+
:::tip
120
+
When the REST API is behind mTLS, simple HTTP health probes can no longer reach it. Enable the plaintext [health check server](#health-check-configuration) to keep liveness/readiness probes working.
121
+
:::
122
+
123
+
| Property | Description | Default value |
124
+
| --- | --- | --- |
125
+
| `cert_path` | Path to the PEM-encoded X.509 certificate (or chain) presented by the server. Setting this enables TLS. | |
126
+
| `key_path` | Path to the PEM-encoded private key matching `cert_path`. | |
127
+
| `ca_path` | Path to a PEM file holding the trusted CA certificate(s). Used by the server to validate client certificates when `verify_client_cert` is enabled, and by the gRPC client to validate peer certificates. Multiple CA certificates may be concatenated in the same file: all of them are trusted (see [CA rotation](#ca-rotation)). | |
128
+
| `verify_client_cert` | If `true`, require clients (REST) or peers (gRPC) to present a certificate signed by `ca_path`, i.e. enforce mutual TLS. | `false` |
129
+
| `expected_name` | gRPC only. The hostname the gRPC client checks against the peer certificate's Subject Alternative Name (SAN). Defaults to the peer's address. | |
130
+
| `cert_reload_interval` | How often `cert_path` and `key_path` are polled for on-disk changes and hot-reloaded, without restarting the process. An immediate reload can also be triggered by sending `SIGHUP` to the process. | `5m` |
131
+
132
+
Certificates are hot-reloaded: when `cert_path`/`key_path` change on disk, new connections pick up the new certificate within `cert_reload_interval` (or immediately on `SIGHUP`), while in-flight connections keep the certificate they negotiated. A new certificate is only applied if it parses and matches its key; otherwise the previous certificate is kept. Note that the CA trust roots (`ca_path`) are **not** hot-reloaded — rotating them still requires a restart.
133
+
134
+
### CA rotation
135
+
136
+
Because `ca_path` accepts multiple CA certificates concatenated in a single PEM file, you can rotate the CA without downtime by temporarily trusting both the old and the new CA:
137
+
138
+
1. Append the **new** CA certificate to the `ca_path` file, so it contains both the old and the new CA.
139
+
2. Roll-restart every node. Each node now trusts certificates signed by either CA, while peers may still present certificates signed by the old CA.
140
+
3. Re-issue every node's `cert_path`/`key_path` with certificates signed by the new CA (these are hot-reloaded, no restart needed).
141
+
4. Remove the **old** CA certificate from the `ca_path` file, leaving only the new CA.
142
+
5. Roll-restart every node again to drop trust in the old CA.
143
+
144
+
Since the CA file is read once at startup, both restarts are required to pick up the changes to `ca_path`.
145
+
146
+
Example of a REST configuration with mTLS:
147
+
148
+
```yaml
149
+
rest:
150
+
tls:
151
+
cert_path: /path/to/server.crt
152
+
key_path: /path/to/server.key
153
+
ca_path: /path/to/ca.crt
154
+
verify_client_cert: true
155
+
cert_reload_interval: 5m
156
+
```
157
+
158
+
Example of a gRPC configuration with mTLS:
159
+
160
+
```yaml
161
+
grpc:
162
+
tls:
163
+
cert_path: /path/to/server.crt
164
+
key_path: /path/to/server.key
165
+
ca_path: /path/to/ca.crt
166
+
expected_name: quickwit.local
167
+
verify_client_cert: true
168
+
cert_reload_interval: 5m
169
+
```
170
+
90
171
## Storage configuration
91
172
92
173
Please refer to the dedicated [storage configuration](storage-config) page to learn more about configuring Quickwit for various storage providers.
Copy file name to clipboardExpand all lines: docs/configuration/ports-config.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,6 +19,8 @@ The ports used are computed relative to the `rest.listen_port` port, as follows.
19
19
20
20
It is not possible for the moment to configure these ports independently.
21
21
22
+
Optionally, an additional plaintext health check server can be enabled on its own port by setting `health.listen_port` (see the [health check configuration](node-config.md#health-check-configuration)). It is disabled by default. The port `${rest.listen_port} + 2` (7282 by default) is a natural choice, but any free port that does not collide with the three above works.
23
+
22
24
23
25
In order to form a cluster, you will also need to define a `peer_seeds` parameter.
24
26
The following addresses are valid peer seed addresses:
0 commit comments