From c9f1f82c0d9fe5c2d430234bc1eee1ab13b4ddfa Mon Sep 17 00:00:00 2001 From: Valentin Lab Date: Sat, 9 Dec 2023 12:03:12 +0100 Subject: [PATCH] new: doc: add doc on root level ``type`` key of ``metadata.yml`` --- README.org | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/README.org b/README.org index 1a1a94a..3a1c10b 100644 --- a/README.org +++ b/README.org @@ -76,3 +76,66 @@ TBD Most tools should check the =CHARM_STORE= bash environment variable that should be the path to reach the root of this repository. If not defined, most tools will look in =/srv/charm-store= by default. + +* Specs + +** charm type + +Not all charm are intended to bring up services as having a container +always running and listening. + +In ~metadata.yml~, the root level ~type~ can be one of: + +- ~service~ (default) + + If not specified, this is the default. A charm brings up a service. + It is meant to be *always running*. For instance, ~apache~, ~mysql~, + ~postgres~ are services. + + They usually open ports and are listening to provide their service, + or carry background listening of other ressources (like checking + time and sending scheduling command for the ~cron~ services), and or + use files to trigger or report on their activity. + + It will have an entry in the final ~docker-compose.yml~, and thus, a + container will run and stay in memory and have a ~restart: + unless-stopped~ policy. They use CPU and memory ressources. + +- ~run-once~ + + The entry is meant to describe *a command that run once*, + it will be called by a service and *will exit after execution*. + + For instance, ~logrotate~, ~rsync-backup~, or ~letsencrypt~ are + of type ~run-once~. + + They are meant to be run by service for specific events. They + usually will use relations to ensure they are called at specific + moment by service... + + A command does not have an automatic ~restart~ policy as services + have. + + They use CPU and memory ressources only when run and gives them back + once finished. + +- ~stub~ + + The entry describes an entity that will *not be run at all*. It is + used to hold information in the ~compose.yml~ and often to *stand + for* a real service managed outside of ~compose.yml~ (on an other + host or on a different managing system, like a local installation or + LXC, virtualbox, ...). + + For instance, ~stmp-stub~ can be used to stand for an external ~smtp~. + + It is through their relation that they shine as they can provide + similar interface than actual services would have + provided. ~smtp-stub~ is a ~smtp-server~ provider and other charm + can connect to it. + + They usually implement relation hooks, and are providers. + + No entry will be created in the final ~docker-compose.yml~. + + They use no CPU or memory ressources at all. \ No newline at end of file