From d142dc1dd961d8f7056b1f24e98021da3d11ab98 Mon Sep 17 00:00:00 2001 From: Samir Akarioh Date: Mon, 17 Jul 2023 11:28:52 +0200 Subject: [PATCH] docs: Rewrite the explanation section This PR add the explanation of Pebble and rewrite chisel,rocks and overlay-step explanation. Co-authored-by: Cristovao Cordeiro --- docs/.wordlist.txt | 67 +++-------------------------- docs/_static/rockcraft_diagram.jpg | Bin 0 -> 12969 bytes docs/explanation/chisel.rst | 10 +++++ docs/explanation/index.rst | 1 + docs/explanation/overlay-step.rst | 4 +- docs/explanation/pebble.rst | 36 ++++++++++++++++ docs/explanation/rocks.rst | 63 +++++++++++++++++++++------ 7 files changed, 108 insertions(+), 73 deletions(-) create mode 100644 docs/_static/rockcraft_diagram.jpg create mode 100644 docs/explanation/pebble.rst diff --git a/docs/.wordlist.txt b/docs/.wordlist.txt index c3abf626a..7ca54471f 100644 --- a/docs/.wordlist.txt +++ b/docs/.wordlist.txt @@ -1,11 +1,16 @@ +ACR Charmcraft cli CLI +CMD dev Diátaxis Dockerfile Dockerfiles +DockerHub +ECR entrypoint +entrypoints filesystem fs GID @@ -23,6 +28,7 @@ Lifecycle linuxcontainers literalinclude localhost +LTS lxd LXD Multipass @@ -36,66 +42,7 @@ OpenSSL OpenSSL's packageName Permalink -pyfiglet -PyPI -reStructuredText -rockcraft -Rockcraft -Rockcraft's -ROCK's -ROCKs -Runtime -skopeo -Skopeo -sliceName -snapcraft -Snapcraft -Snyk's -SPDX -SSL -ubuntu -UID -yaml -Znet -samir@samir-Laptop:~/Desktop/Github-Repo/rockcraft/docs$ sort .wordlist.txt -Charmcraft -cli -CLI -dev -Diátaxis -Dockerfile -Dockerfiles -entrypoint -filesystem -fs -GID -github -GPG -https -init -interoperable -io -Kubernetes -libc -libssl -lifecycle -Lifecycle -linuxcontainers -literalinclude -localhost -lxd -LXD -Multipass -nginx -NGINX -NGINX's -oci -OCI -openssl -OpenSSL -OpenSSL's -packageName -Permalink +Podman pyfiglet PyPI reStructuredText diff --git a/docs/_static/rockcraft_diagram.jpg b/docs/_static/rockcraft_diagram.jpg new file mode 100644 index 0000000000000000000000000000000000000000..dee36d8bd69b89b3fe30186da0b64cb802a09258 GIT binary patch literal 12969 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 literal 0 HcmV?d00001 diff --git a/docs/explanation/chisel.rst b/docs/explanation/chisel.rst index 4983c151a..91d984c4a 100644 --- a/docs/explanation/chisel.rst +++ b/docs/explanation/chisel.rst @@ -12,6 +12,16 @@ needed for the ROCK to function properly. See :ref:`how_to_use_chisel` for information about using the tool. +Slice definitions +----------------- + +A slice is a yaml file permitting chisel to slice the package, +`here `_ is +the slice definition reference. + +To find more examples or if you want to contribute, +check `chisel-releases `_. + Package slices -------------- diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst index 376af4f2b..3fce6d247 100644 --- a/docs/explanation/index.rst +++ b/docs/explanation/index.rst @@ -14,3 +14,4 @@ the motivations behind its development. chisel overlay-step rocks + pebble diff --git a/docs/explanation/overlay-step.rst b/docs/explanation/overlay-step.rst index 75ed36612..8d5cc9d7c 100644 --- a/docs/explanation/overlay-step.rst +++ b/docs/explanation/overlay-step.rst @@ -5,6 +5,8 @@ The component parts of a ROCK are built in a sequence of five separate steps: pull, overlay, build, stage and prime. The overlay step is specific to ROCKs and is configured with overlay parameters. +To learn more about pull,build,stage and prime see :doc:`/reference/parts` + .. Include a section about overlay parameters from the Craft Parts documentation. -.. .. include:: /common/craft-parts/overlay_parameters.rst +.. include:: /common/craft-parts/overlay_parameters.rst diff --git a/docs/explanation/pebble.rst b/docs/explanation/pebble.rst new file mode 100644 index 000000000..bd017612c --- /dev/null +++ b/docs/explanation/pebble.rst @@ -0,0 +1,36 @@ +.. _pebble_explanation_page: + +Pebble +====== + +Pebble is a service manager that helps to organise a set of local service +processes. + +When creating container images, several issues can be met. +For instance, if the entrypoint relies on the application mode +(such as nginx and nginx-debug), creating a bash script that parses all the +arguments provided during container deployment will be necessary. +Additionally, each image runs with specific application arguments, +making it challenging to perform an inspection inside the image consistently. + +Pebble solves these problems by providing a comprehensive set of commands +for starting, stopping, and viewing service status. It also includes features +like auto-restart for continuous operation and dependency management for +properly sequencing services. Pebble streamlines service management as a +single binary that operates as a background service and a client. + +In ROCKs, Pebble services are defined with properties such as name, command, +startup behaviour, dependencies,... Moreover, Pebble is the default entrypoint +(an executable that runs when the container is initiated) in ROCKs, ensuring +consistent container inspection and permit to have multiple entrypoint +without the need to create other files. + + +Create a service +---------------- + +See :doc:`/how-to/convert-to-pebble-layer` for information about converting +a Docker entrypoint to a pebble service. Also, check the top-level field +on :doc:`/reference/rockcraft.yaml` to understand the parameters and fields +needed to create a service. + diff --git a/docs/explanation/rocks.rst b/docs/explanation/rocks.rst index 9f7c2c052..5b6f7b95d 100644 --- a/docs/explanation/rocks.rst +++ b/docs/explanation/rocks.rst @@ -3,22 +3,61 @@ ROCKs ===== -ROCKs are container images that are compliant with the `Open Container -Initiative`_ (OCI) `image format specification `_. -This means that ROCKs are interoperable with other tools that work with -OCI-compliant images. +ROCKs are Ubuntu-based container images that are designed to meet +cloud-native software's security, stability, and reliability requirements. -A ROCK can be stored in an existing container registry, very much like any -Docker image, and run in the same way as any other container image. -For example, Docker can be used to run a ROCK with the usual command line -syntax: +ROCKs were created with a focus on those values: -.. code:: bash +* **Developers experience**: Rockcraft uses a declarative format to describe ROCKs, + aiming to simplify container image definition and provide the best user experience. +* **Ubuntu Experience**: Built on top of Ubuntu, ROCKs provide reliability + and stability to users. They offer access to the latest features, ensuring + users can meet their needs. With long-term support (LTS), ROCKs images + are regularly updated. +* **Consistency**: ROCKs are consistent by utilising Pebble as the entrypoint. + Learning Pebble allows you to interact smoothly with all the ROCKs. - docker run ... +ROCKs comply with the `Open Container +Initiative`_ (OCI) `image format specification `_. +ROCKs can be stored in container registries (e.g. DockerHub, ECR, ACR,..) +and used with any OCI-Compliant tools (e.g. Docker, Podman, Kubernetes,...). -Interoperability between ROCKs and other containers also extends to the way -that container images are built. This enables the use of ROCKs as bases for +Interoperability between ROCKs and other containers also extends to how +container images are built. This enables using ROCKs as bases for existing build recipes, such as Dockerfiles, for further customisation and development. +The ROCKs ecosystem comprises + +.. figure:: /_static/rockcraft_diagram.jpg + :width: 75% + :align: center + :alt: ROCKs ecosystem + + +Chisel +------ + +Chisel is a software tool for extracting well-defined portions +(also known as slices) of Debian packages into a filesystem. +To learn more about Chisel see: :ref:`chisel_explanation` + +Pebble +------ + +In ROCKS, Pebble is the default entrypoint (an executable that +runs when the container is initiated) in ROCKS, ensuring consistent +container inspection and permit to have multiple entrypoint +without the need to create other files.To learn more about +Pebble see: :ref:`pebble_explanation_page` + +Rockcraft +--------- + +Rockcraft is a tool designed to build ROCKs using a declarative syntax +(yaml). It leverages the logic of plugins, parts,and concepts that exist +in Snapcraft and Charmcraft. + +Developers familiar with the creation and publication of snaps and charms +will be able to utilise existing knowledge to create ROCKS. +To learn why you need to use Rockcraft see: :ref:`why_use_rockcraft`