diff --git a/docs/explanation/index.md b/docs/explanation/index.md index 1b2e50fe..0731a8b4 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -4,6 +4,8 @@ :titlesonly: :maxdepth: 1 -General model API and clients +General model +Service dependencies +Service start order ``` diff --git a/docs/explanation/service-dependencies.md b/docs/explanation/service-dependencies.md new file mode 100644 index 00000000..34044b63 --- /dev/null +++ b/docs/explanation/service-dependencies.md @@ -0,0 +1,11 @@ +# Service dependencies + +Pebble can take service dependencies into account when managing services: this is done with the `requires` list in the [service definition](../reference/layer-specification.md). + +Simply put, you can configure a list of other services in the `requires` section to indicate this service requires those other services to start correctly. + +When Pebble starts a service, it also starts the services which that service depends on (configured with `requires`). Conversely, when stopping a service, Pebble also stops services which depend on that service. + +For the start order of the services, see [Service start order](./service-start-order.md). + +For example, if service `nginx` requires `logger`, `pebble start nginx` will start both `nginx` and `logger` (in an undefined order). Running `pebble stop logger` will stop both `nginx` and `logger`; however, running `pebble stop nginx` will only stop `nginx` (`nginx` depends on `logger`, not the other way around). diff --git a/docs/explanation/service-start-order.md b/docs/explanation/service-start-order.md new file mode 100644 index 00000000..0bfe3a60 --- /dev/null +++ b/docs/explanation/service-start-order.md @@ -0,0 +1,10 @@ +# Service start order + +When multiple services need to be started together, they're started in order according to the `before` and `after` in the [layer configuration](../reference/layer-specification.md). Pebble waits 1 second after starting each service to ensure the command doesn't exit too quickly. + +The `before` option is a list of services that this service must start before (it may or may not `requires` them, see [Service dependencies](./service-dependencies.md)). Or if it's easier to specify this ordering the other way around, `after` is a list of services that this service must start after. + +```{include} /reuse/service-start-order.md + :start-after: Start: Service start order note + :end-before: End: Service start order note +``` \ No newline at end of file diff --git a/docs/how-to/service-dependencies.md b/docs/how-to/service-dependencies.md index 5911ce64..8299f34c 100644 --- a/docs/how-to/service-dependencies.md +++ b/docs/how-to/service-dependencies.md @@ -153,6 +153,8 @@ In the layer configuration above, the `frontend` service is dependent on the `backend` service, and the `backend` service is dependent on the `database` service. +For more information on `requires`, see [Service dependencies](../explanation/service-dependencies.md). + ### Specify start order for dependent services To specify the order in which one or more dependent services must start @@ -188,13 +190,12 @@ In the updated layer above, the `frontend` service requires the `backend` service to be started before it, and the `backend` service requires the `database` service to be started before it. -```{note} -Currently, `before` and `after` are of limited usefulness, because Pebble only waits 1 second before moving on to start the next service, with no additional checks that the previous service is operating correctly. - -If the configuration of `before` and `after` for the services results in a cycle, an error will be returned when the Pebble daemon starts (and the plan is loaded) or when a layer that causes a cycle is added. +```{include} /reuse/service-start-order.md + :start-after: Start: Service start order note + :end-before: End: Service start order note ``` -% Does it only check that the status is "Active"? So what does `requires` do? +For more information on `before` and `after`, see [Service start order](../explanation/service-start-order.md). ## Verify service dependencies diff --git a/docs/reuse/service-start-order.md b/docs/reuse/service-start-order.md new file mode 100644 index 00000000..f00d84e8 --- /dev/null +++ b/docs/reuse/service-start-order.md @@ -0,0 +1,9 @@ +Start: Service start order note + +```{note} +Currently, `before` and `after` are of limited usefulness, because Pebble only waits 1 second before moving on to start the next service, with no additional checks that the previous service is operating correctly. + +If the configuration of `before` and `after` for the services results in a cycle, an error will be returned when the Pebble daemon starts (and the plan is loaded) or when a layer that causes a cycle is added. +``` + +End: Service start order note