Introducing Pebble to Rocks
All the rocks produced by Rockcraft share the same OCI Entrypoint - Pebble.
The ultimate goal is to allow all rocks to have a standard deployment interface while also providing users with the ability to have much tighter control over the actual processes that are meant to be started alongside the container.
Therefore, Rockcraft will automatically enforce the OCI Entrypoint to be
"Entrypoint": [
"/bin/pebble",
"enter"
]
Design
The pebble enter command is designed to serve as an entrypoint for Pebble itself, initializing a Pebble server while still taking additional client-side arguments in one go.
The existence of a client command will have an impact on how the Pebble daemon is started. This is better detailed by the usage information (output from docker run <rock-name> --help):
Usage:
pebble enter [enter-OPTIONS] [<subcommand>...]
The enter command facilitates the use of Pebble as an entrypoint for containers.
When used without a subcommand it mimics the behaviour of the run command
alone, while if used with a subcommand it runs that subcommand in the most
appropriate environment taking into account its purpose.
These subcommands are currently supported:
help (1)(2)
version (1)(2)
plan (1)(2)
services (1)(2)
ls (1)(2)
exec (2)
start (3)
stop (3)
(1) Services are not started.
(2) No logs on stdout unless -v is used.
(3) Services continue running after the subcommand succeeds.
[enter command options]
--create-dirs Create pebble directory on startup if it doesn't exist
--hold Do not start default services automatically
--http= Start HTTP API listening on this address (e.g., ":4000")
-v, --verbose Log all output from services to stdout
--run Start default services before executing subcommand
The idea behind such a conditional behaviour is that some Pebble client commands (like start and stop) are naturally designed to manage the lifecycle of Pebble services, while others (like exec and ls) are typically meant to be executed as one-shot commands. The nature of the provided client command will then dictate if the Pebble server (and thus the container) keeps running once the client command has been completed.
Examples
The following examples showcase some of the most common ROCK deployment scenarios, detailing what the expected outcome should be:
docker run <rock>
The container will start and Pebble will immediately start the daemon and run whatever services are defined in the Pebble layers directory. The container will stay alive until the Pebble daemon is stopped.
docker run <rock> --help
The container will start, print the Pebble usage information (as shown above) and immediately exit.
docker run <rock> plan
Pebble will start the daemon with all services on hold, print out the Pebble plan and then shut down, consequently terminating the container as well.
docker run <rock> services
Pebble will start the daemon with all services on hold, print out the list of Pebble services and then shut down, consequently terminating the container as well.
docker run <rock> --run exec echo hello
Pebble will start the daemon as well as its default services, execute echo hello and then keep running the daemon with the default services.
docker run <rock> start my-svc
Pebble will start the daemon with all the default services while also starting the specific service my-svc, and then keep running. This is useful when one wants to start a container with a service that is disabled by default.
docker run <rock> stop my-svc
The opposite of the previous one - Pebble will start the daemon with all the default services, but stop my-svc, and then keep running.