Skip to content

Commit bc86b4e

Browse files
stellarsqualltaoism4504yhyakunatalanknighttmessi
authored
Docs Changes for v0.8.0 (#2024)
* added new metrics doc * Minor format fixes * Use table to list metrics * Update website/content/docs/operations/index.mdx Co-authored-by: Robin Beck <[email protected]> * fixed sentence * added worker proxy http * Update website/content/docs/operations/metrics.mdx Co-authored-by: Todd <[email protected]> * Update based on the changes in draft * remove WIP note * Update website/content/docs/operations/metrics.mdx Co-authored-by: Todd <[email protected]> * Update website/content/docs/operations/metrics.mdx Co-authored-by: Todd <[email protected]> * Update website/content/docs/operations/index.mdx Co-authored-by: Todd <[email protected]> * Removed invalid metrics * Update header level * added code styling for "ops" listener and port 9203 description * added health endpoint document * resolved cherry-pick confict for 5edac3a * Incorporate review feedback * removed bad reference to metrics * added Other section for boundary_build_info * fixed typo * Update website/content/docs/operations/health.mdx Co-authored-by: Loann Le <[email protected]> * Update website/content/docs/operations/metrics.mdx Co-authored-by: Loann Le <[email protected]> * Update website/content/docs/operations/health.mdx Co-authored-by: Loann Le <[email protected]> * Update website/content/docs/operations/health.mdx Co-authored-by: Loann Le <[email protected]> * Update website/content/docs/operations/health.mdx Co-authored-by: Loann Le <[email protected]> * Update website/content/docs/operations/health.mdx Co-authored-by: Loann Le <[email protected]> * Changed release notes structure Removed the empty "Releases" folder and now it goes straight to "Release Notes" * Update website/content/docs/operations/health.mdx Co-authored-by: Loann Le <[email protected]> * Incorporate review feedback * Update website/content/docs/operations/index.mdx Co-authored-by: Loann Le <[email protected]> * added tutorial link * Update website/content/docs/operations/metrics.mdx Co-authored-by: Johan Brandhorst-Satzkorn <[email protected]> * Update website/content/docs/operations/metrics.mdx Co-authored-by: Johan Brandhorst-Satzkorn <[email protected]> * Update website/content/docs/operations/metrics.mdx Co-authored-by: Johan Brandhorst-Satzkorn <[email protected]> * Update website/content/docs/operations/metrics.mdx Co-authored-by: Johan Brandhorst-Satzkorn <[email protected]> * Update website/content/docs/operations/metrics.mdx Co-authored-by: Johan Brandhorst-Satzkorn <[email protected]> * Update website/content/docs/operations/metrics.mdx Co-authored-by: Johan Brandhorst-Satzkorn <[email protected]> * 0.8 Release Notes Added release notes page for 0.8 * corrected sensitive info redaction note * cleaned up visibility overview Co-authored-by: taoism4504 <[email protected]> Co-authored-by: Yoko Hyakuna <[email protected]> Co-authored-by: Loann Le <[email protected]> Co-authored-by: Todd <[email protected]> Co-authored-by: Timothy Messier <[email protected]> Co-authored-by: XingLu Wang <[email protected]> Co-authored-by: Johan Brandhorst-Satzkorn <[email protected]>
1 parent f39553a commit bc86b4e

File tree

17 files changed

+365
-64
lines changed

17 files changed

+365
-64
lines changed

‎website/content/docs/configuration/events/common.mdx

Lines changed: 54 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,7 @@ These parameters are shared across all sink types:
1414
- `description` - Specify a description for the sink.
1515

1616
- `event_types` - Specifies a list of event types that will be sent to the sink.
17-
Can be `*`, `error`, `system`, `observation` or `audit`.
18-
19-
Note: `audit` events are a WIP and will only be emitted if they are both enabled and the env var `BOUNDARY_DEVELOPER_ENABLE_EVENTS` equals true. We anticipate many changes for audit events before they are generally available including what data is included and different options for redacting/encrypting that data.
17+
Can be `*`, `error`, `system`, `observation` or `audit`.
2018

2119
- `event_source_url` - Specifies an optional event source URL for the sink. If
2220
not specified a default source will be composed of the
@@ -25,7 +23,7 @@ These parameters are shared across all sink types:
2523
- `allow_filters` - Specifies a set predicates for including an event in the
2624
sink. If any filter matches, the event will be included. For more information,
2725
on using filters see: [event filtering](/docs/concepts/filtering/events)
28-
26+
2927
- `deny-filters` - Specifies a set predicates for excluding an event in the
3028
sink. If any filter matches, the event will be excluded. For more information
3129
on using filters see: [event filtering](/docs/concepts/filtering/events)
@@ -34,3 +32,55 @@ These parameters are shared across all sink types:
3432
`cloudevents-text`, `hclog-json`, or `hclog-text`.
3533

3634
- `type` - Specifies the type of sink. Can be `stderr` or `file`.
35+
36+
- `audit_config` - Specifies configuration for the processing of audit events
37+
for the sink. This is ignored if the sink is not configured to receive
38+
`audit` events.
39+
40+
## `audit_config` parameters
41+
42+
- `audit_filter_overrides` - Specifies overrides for the filter operations that
43+
are applied to audit events.
44+
45+
### `audit_filter_overrides` parameters
46+
47+
- `sensitive` `(string: "", "encrypt", "hmac-sha256", "redact")` - Specifies
48+
the filter operation to apply to fields that are classified as sensitive.
49+
50+
- `secret` `(string: "", "encrypt", "hmac-sha256", "redact")` - Specifies
51+
the filter operation to apply to fields that are classified as secret.
52+
53+
## `audit_config` Examples
54+
55+
This example is equivalent to the default settings if no `audit_config` stanza
56+
is provided.
57+
58+
```hcl
59+
audit_config {
60+
audit_filter_overrides {
61+
sensitive = "redact"
62+
secret = "redact"
63+
}
64+
}
65+
```
66+
67+
This example will HMAC sensitive fields, and encrypt secrets.
68+
69+
```hcl
70+
audit_config {
71+
audit_filter_overrides {
72+
sensitive = "hmac-sha256"
73+
secret = "encrypt"
74+
}
75+
}
76+
```
77+
78+
This example will not apply a filter to sensitive fields.
79+
80+
```hcl
81+
audit_config {
82+
audit_filter_overrides {
83+
sensitive = ""
84+
}
85+
}
86+
```

‎website/content/docs/configuration/events/overview.mdx

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,6 @@ events {
3434
```
3535

3636
- `audit_enabled` - Specifies if audit events should be emitted.
37-
Note: audit events are a WIP and will only be emitted if they are both enabled and the env var `BOUNDARY_DEVELOPER_ENABLE_EVENTS` equals true. We anticipate many changes for audit events before they are generally available including what data is included and different options for redacting/encrypting that data.
3837

3938
- `observations_enabled` - Specifies if observation events should be emitted.
4039

‎website/content/docs/operations/health.mdx

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
layout: docs
3+
page_title: Boundary Health Endpoints
4+
description: |-
5+
Verify the Boundary controller server is up and able to receive requests
6+
---
7+
8+
## Boundary Health Endpoints
9+
10+
Boundary provides health monitoring through the `/health` path using a listener
11+
with the `"ops"` purpose. By default, a listener with that purpose runs on port
12+
`9203`. See the [example configuration](#example-configuration) section for an
13+
example listener stanza in a `config.hcl` file.
14+
15+
### Requirements
16+
17+
To enable the controller health endpoint, any Boundary instance must be
18+
started with a controller. That is, a `controller` block and a `purpose = "api"`
19+
listener must be defined in Boundary's configuration file. Additionally, a
20+
`purpose = "ops"` listener must also be defined in Boundary's configuration
21+
file. Under these conditions, the `ops` server (which hosts the controller health
22+
api) will be exposed.
23+
24+
### Shutdown Grace Period
25+
26+
Optionally, when the controller health endpoint is enabled, Boundary can be
27+
configured to change the controller health response to `503 Service Unavailable`
28+
upon receiving a shutdown signal, and wait a configurable amount of time before
29+
starting the shutdown process.
30+
31+
This feature is designed to integrate with load balancers to reduce the risk of
32+
an outgoing Boundary instance causing disruption to incoming requests.
33+
34+
In this state, Boundary is still capable of processing requests as normal, but
35+
will report as unhealthy through the controller health endpoint. In
36+
load-balanced environments, this would cause this "unhealthy" instance to be
37+
removed from the pool of instances eligible to handle requests, and thereby, reducing the
38+
likelihood that it will receive a request to handle during shutdown.
39+
40+
This feature is disabled by default, even if the controller health endpoint is
41+
enabled. You can set it up by defining `graceful_shutdown_wait_duration` in the
42+
`controller` block of Boundary's configuration file. The value should be set to
43+
a string that is parseable by
44+
[ParseDuration](https://pkg.go.dev/time#ParseDuration).
45+
46+
### API
47+
48+
The new controller health service introduces a single read-only endpoint:
49+
50+
| Status | Description |
51+
|--------------|----------------------------------------------------------------|
52+
| `200` | `GET /health` returns HTTP status 200 OK if the controller's api gRPC Server is up |
53+
| `5xx` | `GET /health` returns HTTP status `5XX` or request timeout if unhealthy |
54+
| `503` | `GET /health` returns HTTP status `503 Service Unavailable` status if the controller is shutting down |
55+
56+
All responses return empty bodies. `GET /health` does not support any input.
57+
58+
## Example configuration
59+
60+
Health checks are available for a controller defined with a `purpose = "ops"`
61+
listener stanza. For details on what fields are allowed in this stanza, refer to
62+
the documentation about [TCP Listener](/docs/configuration/listener/tcp).
63+
64+
An example listener stanza:
65+
66+
```hcl
67+
controller {
68+
name = "boundary-controller"
69+
database {
70+
url = "postgresql://<username>:<password>@10.0.0.1:5432/<database_name>"
71+
}
72+
}
73+
74+
listener "tcp" {
75+
purpose = "api"
76+
tls_disable = true
77+
}
78+
79+
listener "tcp" {
80+
purpose = "ops"
81+
tls_disable = true
82+
}
83+
```
84+
85+
To enable a shutdown grace period, update the `controller` block with a defined
86+
wait duration:
87+
88+
```hcl
89+
controller {
90+
name = "boundary-controller"
91+
database {
92+
url = "env://BOUNDARY_PG_URL"
93+
}
94+
graceful_shutdown_wait_duration = "10s"
95+
}
96+
```
97+
98+
A complete example can be viewed under the [Controller
99+
configuration](/docs/configuration/controller#complete-configuration-example)
100+
docs.

‎website/content/docs/operations/index.mdx

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
layout: docs
3+
page_title: Operating Boundary
4+
description: |-
5+
Operational tasks in Boundary.
6+
---
7+
8+
# Maintaining and Operating Boundary
9+
10+
Visibility into various components of Boundary plays an important role in ensuring the health of its controllers and workers. While additional monitoring components are planned for subsequent Boundary releases, metrics for controllers and workers can now be exported and then collected by Prometheus. Metrics provide insight into the current state of a Boundary deployment by enabling the diagnosis of deployed controllers and workers. Enabling metrics assists in the detection and mitigation of anomalies in a deployment.
11+
12+
These docs describe the available metrics and the naming and labeling standards used. Additionally, the health of controllers can be monitored using the `/health` endpoint. The health endpoint is enabled by defining a listener in Boundary's configuration file, and a health response may be configured to add a shutdown grace period process.
13+
14+
* Refer to the [Metrics](/docs/operations/metrics) documentation to learn more about Boundary metrics.
15+
* Refer to the [Health Endpoint](/docs/operations/health) documentation to learn more about Boundary health endpoints.

‎website/content/docs/operations/metrics.mdx

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
layout: docs
3+
page_title: Boundary Metrics
4+
description: |-
5+
Obtain visibility of various components of a running Boundary
6+
---
7+
8+
## Boundary Metrics
9+
10+
Boundary provides metrics through the `/metrics` path using a listener with the
11+
`"ops"` purpose. By default, a listener with that purpose runs on port `9203`.
12+
See the [example configuration](#example-configuration) section for an example
13+
listener stanza in a `config.hcl` file.
14+
15+
Metrics are important for understanding what is happening in a Boundary
16+
deployment, enabling diagnoses of deployed controllers and workers. The exported
17+
metrics grant greater visibility into the various components of a running
18+
Boundary deployment through Prometheus.
19+
20+
The metrics uses the [OpenMetric
21+
exposition](https://prometheus.io/docs/instrumenting/exposition_formats/#openmetrics-text-format)
22+
format which can be read by
23+
[Prometheus](https://prometheus.io/docs/introduction/overview/).
24+
25+
### Controller
26+
27+
The following table lists the current names and descriptions of metrics provided
28+
by controllers.
29+
30+
| Name | Description |
31+
|---------------------------------------------------------------|-----------------------------------------------|
32+
| `boundary_controller_api_http_request_duration_seconds` | Histogram of latencies for HTTP requests. |
33+
| `boundary_controller_api_http_request_size_bytes` | Histogram of request sizes for HTTP requests. |
34+
| `boundary_controller_api_http_response_size_bytes` | Histogram of response sizes for HTTP requests. |
35+
| `boundary_controller_cluster_grpc_request_duration_seconds` | Histogram of latencies for requests made to the gRPC service running on the cluster listener. |
36+
37+
### Worker
38+
39+
The following table lists the current names and descriptions of metrics provided
40+
by workers.
41+
42+
| Name | Description |
43+
|---------------------------------------------------------------|-----------------------------------------------|
44+
| `boundary_worker_proxy_http_write_header_duration_seconds` | Histogram of time elapsed after the TLS connection is established to when the first http header is written back from the server. |
45+
| `boundary_worker_proxy_websocket_active_connections` | A gauge of the current count of open proxy connections on the worker. |
46+
| `boundary_worker_proxy_websocket_received_bytes_total` | Count of received bytes sent over all proxy connections handled by the worker. |
47+
| `boundary_worker_proxy_websocket_sent_bytes_total` | Count of sent bytes sent over all proxy connections handled by the worker. |
48+
49+
### Other
50+
51+
The following table lists the current miscellaneous metrics provided by Boundary.
52+
53+
| Name | Description |
54+
|---------------------------------------------------------------|-----------------------------------------------|
55+
| `boundary_build_info` | A gauge set to 1 with label values detailing the current Go version, git revision, and Boundary version. |
56+
57+
### Metric Labels
58+
59+
Each metric uses labels to help organize and narrow its scope so that users can
60+
filter for different characteristics, allowing more flexible analysis of the
61+
measurements collected.
62+
63+
#### Metrics for HTTP requests include the following labels:
64+
65+
| Label | Description |
66+
|--------------|----------------------------------------------------------------|
67+
| `code` | The HTTP status code of the request (e.g., “200”, “400”, etc.). |
68+
| `path` | The path, excluding query parameters, associated with the request. The value for this label replaces resource IDs with "{id}" (for example, `/v1/groups/{id}` is a possible value for this label). Any unexpected paths receive the value "unknown." |
69+
| `method` | The name of the method on the HTTP request. For example "GET", “POST”, “DELETE”. |
70+
71+
72+
#### Metrics for gRPC requests include the following labels:
73+
74+
| Label | Description |
75+
|-----------------|-----------------------------------------------------------------|
76+
| `grpc_method` | The name of the method on the grpc service (e.g., `GetGroup`). |
77+
| `grpc_service` | The proto service name including the package (e.g., `controller.api.services.v1.GroupService`). |
78+
| `grpc_code` | The grpc [status code](https://github.com/grpc/grpc-go/blob/master/codes/codes.go) in human-readable format. For example, `OK`, `IllegalArgument`, `Unknown`. |
79+
80+
81+
## Example configuration
82+
83+
Defining a listener stanza in the config file is sufficient for enabling metrics
84+
reporting in Boundary. For details on what fields are allowed in this stanza,
85+
refer to the documentation about [TCP
86+
Listener](/docs/configuration/listener/tcp).
87+
88+
An example listener stanza:
89+
90+
```hcl
91+
listener "tcp" {
92+
purpose = "ops"
93+
tls_disable = true
94+
}
95+
```
96+
97+
## Tutorial
98+
99+
Refer to [Prometheus
100+
Metrics](https://learn.hashicorp.com/tutorials/boundary/prometheus-metrics)
101+
tutorial for a step-by-step introduction to metrics.

‎website/content/docs/release-notes/index.mdx

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
layout: docs
3+
page_title: Release Notes
4+
description: |-
5+
Boundary release notes
6+
---
7+
8+
# Release Notes
9+
10+
The side bar to the left has release notes for all major and minor releases of Boundary.
11+
12+
Downloads of Boundary can be found on the [Boundary Release Page](https://github.com/hashicorp/boundary/releases/)
13+
and the documentation is available on the [Boundary Changelog Page](https://github.com/hashicorp/boundary/blob/main/CHANGELOG.md).

‎website/content/docs/releases/release-notes/v0_1_0.mdx renamed to ‎website/content/docs/release-notes/v0_1_0.mdx

File renamed without changes.

‎website/content/docs/releases/release-notes/v0_2_0.mdx renamed to ‎website/content/docs/release-notes/v0_2_0.mdx

File renamed without changes.

‎website/content/docs/releases/release-notes/v0_3_0.mdx renamed to ‎website/content/docs/release-notes/v0_3_0.mdx

File renamed without changes.

‎website/content/docs/releases/release-notes/v0_4_0.mdx renamed to ‎website/content/docs/release-notes/v0_4_0.mdx

File renamed without changes.

0 commit comments

Comments
 (0)