diff --git a/docs/how-to/index.md b/docs/how-to/index.md index c680e8cfa..10fcc197c 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -22,7 +22,7 @@ As your needs grow, you may want to use advanced Pebble features to run services :titlesonly: :maxdepth: 1 -Run services reliably +Configure health checks to run services reliably Manage service dependencies Use layers ``` diff --git a/docs/how-to/run-services-reliably.md b/docs/how-to/run-services-reliably.md index e021d1759..784c33bb7 100644 --- a/docs/how-to/run-services-reliably.md +++ b/docs/how-to/run-services-reliably.md @@ -1,4 +1,4 @@ -# How to run services reliably +# How to run services reliably with health checks Microservice architectures offer flexibility, but they can introduce reliability challenges such as network interruptions, resource exhaustion, problems with dependent services, cascading failures, and deployment issues. Health checks can address these issues by monitoring resource usage, checking the availability of dependencies, catching problems with new deployments, and preventing downtime by redirecting traffic away from failing services. diff --git a/docs/index.md b/docs/index.md index 62fc12e50..3b14a9364 100644 --- a/docs/index.md +++ b/docs/index.md @@ -28,6 +28,7 @@ Pebble is useful for developers who are building {external+operator:ref}`Juju ch ```{grid-item-card} [How-to guides](how-to/index) **Step-by-step guides** covering key operations and common tasks - [Install Pebble](how-to/install-pebble) +- [Configure health checks to run services reliably](how-to/run-services-reliably) - [Manage service dependencies](how-to/service-dependencies) - [Manage identities](how-to/manage-identities) ``` diff --git a/docs/reference/health-checks.md b/docs/reference/health-checks.md index 90a8b50fc..eb2c35285 100644 --- a/docs/reference/health-checks.md +++ b/docs/reference/health-checks.md @@ -3,6 +3,8 @@ Separate from the service manager, Pebble implements custom "health checks" that can be configured to restart services when they fail. ## Usage + +For a step-by-step guide on configuring checks and automatic service restarts, see [How to run services reliably with health checks](/how-to/run-services-reliably). Checks are configured in the layer configuration using the top-level field `checks`: @@ -115,8 +117,8 @@ checks: ``` See also: - -- [](/how-to/run-services-reliably) + +- [How to run services reliably with health checks](/how-to/run-services-reliably) - [](/how-to/check-health-based-on-logs) ## Checks command diff --git a/docs/reference/service-auto-restart.md b/docs/reference/service-auto-restart.md index 643d39bb4..8c5b7c69b 100644 --- a/docs/reference/service-auto-restart.md +++ b/docs/reference/service-auto-restart.md @@ -13,3 +13,8 @@ By default, this is done whether the exit code is zero or non-zero, but you can In `restart` mode, the first time a service exits, Pebble waits the `backoff-delay`, which defaults to half a second. If the service exits again, Pebble calculates the next backoff delay by multiplying the current delay by `backoff-factor`, which defaults to 2.0 (doubling). The increasing delay is capped at `backoff-limit`, which defaults to 30 seconds. The `backoff-limit` value is also used as a "backoff reset" time. If the service stays running after a restart for `backoff-limit` seconds, the backoff process is reset and the delay reverts to `backoff-delay`. + +## See more + +- [How to run services reliably with health checks](/how-to/run-services-reliably) +- [Health checks](health-checks) diff --git a/docs/tutorial/getting-started.md b/docs/tutorial/getting-started.md index 861a8cd26..9d03532d3 100644 --- a/docs/tutorial/getting-started.md +++ b/docs/tutorial/getting-started.md @@ -232,4 +232,5 @@ http-server-2 enabled active today at 11:40 UTC - To learn more about viewing, starting and stopping services, see [`pebble services`](#reference_pebble_services_command) command, [`pebble start`](#reference_pebble_start_command) command, and [`pebble stop`](reference_pebble_stop_command) command. - To learn more about updating and restarting services, see [`pebble replan`](reference_pebble_replan_command) command. - To learn more about configuring layers, see [How to use layers](../how-to/use-layers.md). +- To learn how to keep services running and monitor health, see [How to run services reliably with health checks](../how-to/run-services-reliably.md). - To learn more about layer configuration options, read the [Layer specification](../reference/layer-specification.md).