A Pebble may be of service to a Rock

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.

2 Likes