diff --git a/website/content/docs/configuration/events/common.mdx b/website/content/docs/configuration/events/common.mdx index 9689f8e5ce..c62dbb0b57 100644 --- a/website/content/docs/configuration/events/common.mdx +++ b/website/content/docs/configuration/events/common.mdx @@ -14,9 +14,7 @@ These parameters are shared across all sink types: - `description` - Specify a description for the sink. - `event_types` - Specifies a list of event types that will be sent to the sink. - Can be `*`, `error`, `system`, `observation` or `audit`. - - 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. + Can be `*`, `error`, `system`, `observation` or `audit`. - `event_source_url` - Specifies an optional event source URL for the sink. If not specified a default source will be composed of the @@ -25,7 +23,7 @@ These parameters are shared across all sink types: - `allow_filters` - Specifies a set predicates for including an event in the sink. If any filter matches, the event will be included. For more information, on using filters see: [event filtering](/docs/concepts/filtering/events) - + - `deny-filters` - Specifies a set predicates for excluding an event in the sink. If any filter matches, the event will be excluded. For more information on using filters see: [event filtering](/docs/concepts/filtering/events) @@ -34,3 +32,55 @@ These parameters are shared across all sink types: `cloudevents-text`, `hclog-json`, or `hclog-text`. - `type` - Specifies the type of sink. Can be `stderr` or `file`. + +- `audit_config` - Specifies configuration for the processing of audit events + for the sink. This is ignored if the sink is not configured to receive + `audit` events. + +## `audit_config` parameters + +- `audit_filter_overrides` - Specifies overrides for the filter operations that + are applied to audit events. + +### `audit_filter_overrides` parameters + +- `sensitive` `(string: "", "encrypt", "hmac-sha256", "redact")` - Specifies + the filter operation to apply to fields that are classified as sensitive. + +- `secret` `(string: "", "encrypt", "hmac-sha256", "redact")` - Specifies + the filter operation to apply to fields that are classified as secret. + +## `audit_config` Examples + +This example is equivalent to the default settings if no `audit_config` stanza +is provided. + +```hcl +audit_config { + audit_filter_overrides { + sensitive = "redact" + secret = "redact" + } +} +``` + +This example will HMAC sensitive fields, and encrypt secrets. + +```hcl +audit_config { + audit_filter_overrides { + sensitive = "hmac-sha256" + secret = "encrypt" + } +} +``` + +This example will not apply a filter to sensitive fields. + +```hcl +audit_config { + audit_filter_overrides { + sensitive = "" + } +} +``` diff --git a/website/content/docs/configuration/events/overview.mdx b/website/content/docs/configuration/events/overview.mdx index 750cb44cb8..fb71822170 100644 --- a/website/content/docs/configuration/events/overview.mdx +++ b/website/content/docs/configuration/events/overview.mdx @@ -34,7 +34,6 @@ events { ``` - `audit_enabled` - Specifies if audit events should be emitted. - 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. - `observations_enabled` - Specifies if observation events should be emitted. diff --git a/website/content/docs/operations/health.mdx b/website/content/docs/operations/health.mdx new file mode 100644 index 0000000000..128ff6b196 --- /dev/null +++ b/website/content/docs/operations/health.mdx @@ -0,0 +1,100 @@ +--- +layout: docs +page_title: Boundary Health Endpoints +description: |- + Verify the Boundary controller server is up and able to receive requests +--- + +## Boundary Health Endpoints + +Boundary provides health monitoring through the `/health` path using a listener +with the `"ops"` purpose. By default, a listener with that purpose runs on port +`9203`. See the [example configuration](#example-configuration) section for an +example listener stanza in a `config.hcl` file. + +### Requirements + +To enable the controller health endpoint, any Boundary instance must be +started with a controller. That is, a `controller` block and a `purpose = "api"` +listener must be defined in Boundary's configuration file. Additionally, a +`purpose = "ops"` listener must also be defined in Boundary's configuration +file. Under these conditions, the `ops` server (which hosts the controller health +api) will be exposed. + +### Shutdown Grace Period + +Optionally, when the controller health endpoint is enabled, Boundary can be +configured to change the controller health response to `503 Service Unavailable` +upon receiving a shutdown signal, and wait a configurable amount of time before +starting the shutdown process. + +This feature is designed to integrate with load balancers to reduce the risk of +an outgoing Boundary instance causing disruption to incoming requests. + +In this state, Boundary is still capable of processing requests as normal, but +will report as unhealthy through the controller health endpoint. In +load-balanced environments, this would cause this "unhealthy" instance to be +removed from the pool of instances eligible to handle requests, and thereby, reducing the +likelihood that it will receive a request to handle during shutdown. + +This feature is disabled by default, even if the controller health endpoint is +enabled. You can set it up by defining `graceful_shutdown_wait_duration` in the +`controller` block of Boundary's configuration file. The value should be set to +a string that is parseable by +[ParseDuration](https://pkg.go.dev/time#ParseDuration). + +### API + +The new controller health service introduces a single read-only endpoint: + +| Status | Description | +|--------------|----------------------------------------------------------------| +| `200` | `GET /health` returns HTTP status 200 OK if the controller's api gRPC Server is up | +| `5xx` | `GET /health` returns HTTP status `5XX` or request timeout if unhealthy | +| `503` | `GET /health` returns HTTP status `503 Service Unavailable` status if the controller is shutting down | + +All responses return empty bodies. `GET /health` does not support any input. + +## Example configuration + +Health checks are available for a controller defined with a `purpose = "ops"` +listener stanza. For details on what fields are allowed in this stanza, refer to +the documentation about [TCP Listener](/docs/configuration/listener/tcp). + +An example listener stanza: + +```hcl +controller { + name = "boundary-controller" + database { + url = "postgresql://:@10.0.0.1:5432/" + } +} + +listener "tcp" { + purpose = "api" + tls_disable = true +} + +listener "tcp" { + purpose = "ops" + tls_disable = true +} +``` + +To enable a shutdown grace period, update the `controller` block with a defined +wait duration: + +```hcl +controller { + name = "boundary-controller" + database { + url = "env://BOUNDARY_PG_URL" + } + graceful_shutdown_wait_duration = "10s" +} +``` + +A complete example can be viewed under the [Controller +configuration](/docs/configuration/controller#complete-configuration-example) +docs. \ No newline at end of file diff --git a/website/content/docs/operations/index.mdx b/website/content/docs/operations/index.mdx new file mode 100644 index 0000000000..679f71f015 --- /dev/null +++ b/website/content/docs/operations/index.mdx @@ -0,0 +1,15 @@ +--- +layout: docs +page_title: Operating Boundary +description: |- + Operational tasks in Boundary. +--- + +# Maintaining and Operating Boundary + +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. + +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. + +* Refer to the [Metrics](/docs/operations/metrics) documentation to learn more about Boundary metrics. +* Refer to the [Health Endpoint](/docs/operations/health) documentation to learn more about Boundary health endpoints. diff --git a/website/content/docs/operations/metrics.mdx b/website/content/docs/operations/metrics.mdx new file mode 100644 index 0000000000..ff6d7b4f0a --- /dev/null +++ b/website/content/docs/operations/metrics.mdx @@ -0,0 +1,101 @@ +--- +layout: docs +page_title: Boundary Metrics +description: |- + Obtain visibility of various components of a running Boundary +--- + +## Boundary Metrics + +Boundary provides metrics through the `/metrics` path using a listener with the +`"ops"` purpose. By default, a listener with that purpose runs on port `9203`. +See the [example configuration](#example-configuration) section for an example +listener stanza in a `config.hcl` file. + +Metrics are important for understanding what is happening in a Boundary +deployment, enabling diagnoses of deployed controllers and workers. The exported +metrics grant greater visibility into the various components of a running +Boundary deployment through Prometheus. + +The metrics uses the [OpenMetric +exposition](https://prometheus.io/docs/instrumenting/exposition_formats/#openmetrics-text-format) +format which can be read by +[Prometheus](https://prometheus.io/docs/introduction/overview/). + +### Controller + +The following table lists the current names and descriptions of metrics provided +by controllers. + +| Name | Description | +|---------------------------------------------------------------|-----------------------------------------------| +| `boundary_controller_api_http_request_duration_seconds` | Histogram of latencies for HTTP requests. | +| `boundary_controller_api_http_request_size_bytes` | Histogram of request sizes for HTTP requests. | +| `boundary_controller_api_http_response_size_bytes` | Histogram of response sizes for HTTP requests. | +| `boundary_controller_cluster_grpc_request_duration_seconds` | Histogram of latencies for requests made to the gRPC service running on the cluster listener. | + +### Worker + +The following table lists the current names and descriptions of metrics provided +by workers. + +| Name | Description | +|---------------------------------------------------------------|-----------------------------------------------| +| `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. | +| `boundary_worker_proxy_websocket_active_connections` | A gauge of the current count of open proxy connections on the worker. | +| `boundary_worker_proxy_websocket_received_bytes_total` | Count of received bytes sent over all proxy connections handled by the worker. | +| `boundary_worker_proxy_websocket_sent_bytes_total` | Count of sent bytes sent over all proxy connections handled by the worker. | + +### Other + +The following table lists the current miscellaneous metrics provided by Boundary. + +| Name | Description | +|---------------------------------------------------------------|-----------------------------------------------| +| `boundary_build_info` | A gauge set to 1 with label values detailing the current Go version, git revision, and Boundary version. | + +### Metric Labels + +Each metric uses labels to help organize and narrow its scope so that users can +filter for different characteristics, allowing more flexible analysis of the +measurements collected. + +#### Metrics for HTTP requests include the following labels: + +| Label | Description | +|--------------|----------------------------------------------------------------| +| `code` | The HTTP status code of the request (e.g., “200”, “400”, etc.). | +| `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." | +| `method` | The name of the method on the HTTP request. For example "GET", “POST”, “DELETE”. | + + +#### Metrics for gRPC requests include the following labels: + +| Label | Description | +|-----------------|-----------------------------------------------------------------| +| `grpc_method` | The name of the method on the grpc service (e.g., `GetGroup`). | +| `grpc_service` | The proto service name including the package (e.g., `controller.api.services.v1.GroupService`). | +| `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`. | + + +## Example configuration + +Defining a listener stanza in the config file is sufficient for enabling metrics +reporting in Boundary. For details on what fields are allowed in this stanza, +refer to the documentation about [TCP +Listener](/docs/configuration/listener/tcp). + +An example listener stanza: + +```hcl +listener "tcp" { + purpose = "ops" + tls_disable = true +} +``` + +## Tutorial + +Refer to [Prometheus +Metrics](https://learn.hashicorp.com/tutorials/boundary/prometheus-metrics) +tutorial for a step-by-step introduction to metrics. diff --git a/website/content/docs/release-notes/index.mdx b/website/content/docs/release-notes/index.mdx new file mode 100644 index 0000000000..c94504ebbb --- /dev/null +++ b/website/content/docs/release-notes/index.mdx @@ -0,0 +1,13 @@ +--- +layout: docs +page_title: Release Notes +description: |- + Boundary release notes +--- + +# Release Notes + +The side bar to the left has release notes for all major and minor releases of Boundary. + +Downloads of Boundary can be found on the [Boundary Release Page](https://github.com/hashicorp/boundary/releases/) +and the documentation is available on the [Boundary Changelog Page](https://github.com/hashicorp/boundary/blob/main/CHANGELOG.md). diff --git a/website/content/docs/releases/release-notes/v0_1_0.mdx b/website/content/docs/release-notes/v0_1_0.mdx similarity index 100% rename from website/content/docs/releases/release-notes/v0_1_0.mdx rename to website/content/docs/release-notes/v0_1_0.mdx diff --git a/website/content/docs/releases/release-notes/v0_2_0.mdx b/website/content/docs/release-notes/v0_2_0.mdx similarity index 100% rename from website/content/docs/releases/release-notes/v0_2_0.mdx rename to website/content/docs/release-notes/v0_2_0.mdx diff --git a/website/content/docs/releases/release-notes/v0_3_0.mdx b/website/content/docs/release-notes/v0_3_0.mdx similarity index 100% rename from website/content/docs/releases/release-notes/v0_3_0.mdx rename to website/content/docs/release-notes/v0_3_0.mdx diff --git a/website/content/docs/releases/release-notes/v0_4_0.mdx b/website/content/docs/release-notes/v0_4_0.mdx similarity index 100% rename from website/content/docs/releases/release-notes/v0_4_0.mdx rename to website/content/docs/release-notes/v0_4_0.mdx diff --git a/website/content/docs/releases/release-notes/v0_5_0.mdx b/website/content/docs/release-notes/v0_5_0.mdx similarity index 100% rename from website/content/docs/releases/release-notes/v0_5_0.mdx rename to website/content/docs/release-notes/v0_5_0.mdx diff --git a/website/content/docs/releases/release-notes/v0_6_0.mdx b/website/content/docs/release-notes/v0_6_0.mdx similarity index 100% rename from website/content/docs/releases/release-notes/v0_6_0.mdx rename to website/content/docs/release-notes/v0_6_0.mdx diff --git a/website/content/docs/releases/release-notes/v0_7_0.mdx b/website/content/docs/release-notes/v0_7_0.mdx similarity index 100% rename from website/content/docs/releases/release-notes/v0_7_0.mdx rename to website/content/docs/release-notes/v0_7_0.mdx diff --git a/website/content/docs/release-notes/v0_8_0.mdx b/website/content/docs/release-notes/v0_8_0.mdx new file mode 100644 index 0000000000..697d3f475c --- /dev/null +++ b/website/content/docs/release-notes/v0_8_0.mdx @@ -0,0 +1,33 @@ +--- +layout: docs +page_title: v0.8.0 +description: |- + Boundary release notes for v0.8.0 +--- + +# [Boundary v0.8.0](https://www.boundaryproject.io/downloads) + +The release notes below contain information about new functionality available in the Boundary v0.8.0 release. +To see a granular record of when each item was merged into the Boundary project, please refer to the [Changelog](https://github.com/hashicorp/boundary/blob/main/CHANGELOG.md). +To learn about what Boundary consists of, we highly recommend you start at the [Getting Started Page](/docs/getting-started). + +Lastly, for instructions on how to upgrade an existing Boundary deployment to v0.8.0, please review Boundary’s [general upgrade guide](https://learn.hashicorp.com/tutorials/boundary/upgrade-version). + +## Boundary v0.8.0 Highlights + +**Metrics and Health Endpoint:** Boundary is adding [Prometheus metrics](https://www.boundaryproject.io/docs/operations/metrics) to monitor the operations of workers and controllers, +as well as a [health endpoint](https://www.boundaryproject.io/docs/operations/health) for controllers. + +**Audit Event Logs:** We are expanding the audit event logs by increasing the captured [audit events](https://www.boundaryproject.io/docs/configuration/events/overview), +with support for sanitizing sensitive information from audit events. All of the events are now classified and events contain more usable data, with sensitive information redacted by default. + +**UI Support for Worker Tags:** Users can now set and edit [worker tag](https://www.boundaryproject.io/docs/concepts/filtering/worker-tags) filters in the Boundary admin console. + +**Performance Improvements:** We have implemented changes to improve performance on larger deployments; such as adding a refresh button in the admin console and desktop client, +and improving response times listing sessions and targets. We plan to continue these efforts as Boundary users grow their deployments! + + +## What's Changed + +For more detailed information of all changes since 0.7.0, please refer to the [Changelog](https://github.com/hashicorp/boundary/blob/main/CHANGELOG.md) + diff --git a/website/content/docs/releases/index.mdx b/website/content/docs/releases/index.mdx deleted file mode 100644 index 402bd5ef64..0000000000 --- a/website/content/docs/releases/index.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: docs -page_title: Releases -description: |- - Boundary releases ---- - -# Downloads - -Downloads of Boundary can be found on the [HashiCorp Release Page](https://github.com/hashicorp/boundary/releases/). diff --git a/website/content/docs/releases/release-notes/index.mdx b/website/content/docs/releases/release-notes/index.mdx deleted file mode 100644 index 1adc3094fb..0000000000 --- a/website/content/docs/releases/release-notes/index.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -layout: docs -page_title: Release Notes -description: |- - Boundary release notes ---- - -# Release Notes - -The side bar to the left has release notes for all major releases of Boundary. - -Documentation for patch releases (0.1.x) is available at the [Boundary changelog](https://github.com/hashicorp/boundary/blob/main/CHANGELOG.md). diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 853ac1b92f..4f601a9b87 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -358,6 +358,23 @@ } ] }, + { + "title": "Operations", + "routes": [ + { + "title": "Overview", + "path": "operations" + }, + { + "title": "Metrics", + "path": "operations/metrics" + }, + { + "title": "Health Endpoint", + "path": "operations/health" + } + ] + }, { "title": "Common Workflows", "href": "https://learn.hashicorp.com/collections/boundary/basic-administration" @@ -404,48 +421,43 @@ "path": "roadmap" }, { - "title": "Releases", + "title": "Release Notes", "routes": [ { "title": "Overview", - "path": "releases" + "path": "release-notes" }, { - "title": "Release Notes", - "routes": [ - { - "title": "Overview", - "path": "releases/release-notes" - }, - { - "title": "v0.7.0", - "path": "releases/release-notes/v0_7_0" - }, - { - "title": "v0.6.0", - "path": "releases/release-notes/v0_6_0" - }, - { - "title": "v0.5.0", - "path": "releases/release-notes/v0_5_0" - }, - { - "title": "v0.4.0", - "path": "releases/release-notes/v0_4_0" - }, - { - "title": "v0.3.0", - "path": "releases/release-notes/v0_3_0" - }, - { - "title": "v0.2.0", - "path": "releases/release-notes/v0_2_0" - }, - { - "title": "v0.1.0", - "path": "releases/release-notes/v0_1_0" - } - ] + "title": "v0.8.0", + "path": "release-notes/v0_8_0" + }, + { + "title": "v0.7.0", + "path": "release-notes/v0_7_0" + }, + { + "title": "v0.6.0", + "path": "release-notes/v0_6_0" + }, + { + "title": "v0.5.0", + "path": "release-notes/v0_5_0" + }, + { + "title": "v0.4.0", + "path": "release-notes/v0_4_0" + }, + { + "title": "v0.3.0", + "path": "release-notes/v0_3_0" + }, + { + "title": "v0.2.0", + "path": "release-notes/v0_2_0" + }, + { + "title": "v0.1.0", + "path": "release-notes/v0_1_0" } ] }