From c7bb477d30943d15557b9bfa22dda474c30f0f39 Mon Sep 17 00:00:00 2001 From: Valentin Lab Date: Thu, 18 Jan 2024 10:43:22 +0100 Subject: [PATCH] new: doc: add notes about types of charms --- README.org | 104 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 65 insertions(+), 39 deletions(-) diff --git a/README.org b/README.org index 3a1c10b..da17537 100644 --- a/README.org +++ b/README.org @@ -81,61 +81,87 @@ defined, most tools will look in =/srv/charm-store= by default. ** charm type -Not all charm are intended to bring up services as having a container -always running and listening. +Not all charm are designed to set up a continuously running, listening +service. -In ~metadata.yml~, the root level ~type~ can be one of: +In a charm's ~metadata.yml~, the root-level key ~type~ can have one of +these values: -- ~service~ (default) +- ~daemon~ (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. + By default, a charm is of type ~daemon~. It's probably the most + expected way to run a service: it brings up a process that is + *always running*. Examples include charms like ~apache~, ~mysql~, + ~postgres~. - 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. + These charms bring up processes that typically open ports to provide + their functionality, perform background tasks like checking the time + and scheduling commands (as the ~cron~ charm), and may use files to + trigger or report on their activities. - 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. + In the final ~docker-compose.yml~, a ~daemon~ type charm will + ensure that an entry is created for the service they manage, + resulting in a container that stays in memory. As such they require + a docker image. They will ensure that these entries are managed with + ~restart: unless-stopped~ policy. -- ~run-once~ + The processes managed by these charms will be setup via + ~docker-compose up~ actions at the end, and they will run in the + background. - The entry is meant to describe *a command that run once*, - it will be called by a service and *will exit after execution*. + Once brought up, the processes from these charms will consume CPU and + memory resources indefinitely, until you manually bring them down. - For instance, ~logrotate~, ~rsync-backup~, or ~letsencrypt~ are - of type ~run-once~. + It makes sense to bring them ~up~ or ~down~. - 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... +- ~command~ - A command does not have an automatic ~restart~ policy as services - have. + This charm type is used to prepare *a process that run and exits + after execution*. These are more what could be expected of a + "command", and are typically invoked by an other service for + specific events. - They use CPU and memory ressources only when run and gives them back - once finished. + Example includes ~logrotate~, ~rsync-backup~, and ~letsencrypt~, + which are charms of type ~run-once~. + + These charms are meant to setup commands that are triggered by + services at specific moments or as a result of specific event. It is + through their ~relation~ hooks with other services that they will + ensure to be called when intended to. They are run through the + ~docker-compose run~ call. + + Like ~daemon~'s typed charm, these charm will ensure that an entry + is correctly added in the final ~docker-compose.yml~ with all the + necessary options so it is ready to be triggered. They require also + a docker image. + + But unlike ~daemon~'s typed charms, these charm will ensure that + the entry they managed in the final ~docker-compose.yml~ *DO NOT* + have an automatic restart policy. + + They consume CPU and memory resources only when running and release + resources 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, ...). + A ~stub~ charm is more of a placeholder that doesn't have anything + to run at all ! They don't need any docker image. These entities are + used to hold information in ~compose.yml~ and can often be used to + represent a real service managed externally (out of =compose=, on + another host or through a different management system, such as a + local installation, LXC, VirtualBox, etc.). + + For example, ~smtp-stub~ charm can be used to build an entity that + will stand for an external ~smtp~ service. Through relations, these + stubs offer interfaces similar to actual services in the setting up + stage. For instance, a ~smtp-stub~ acts as a ~smtp-server~ provider, + and can satisfy ~services~ that would require a ~smtp-server~ + provider. - For instance, ~stmp-stub~ can be used to stand for an external ~smtp~. + They generally implement relation hooks and act as providers. - 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. + No entry is created for them in the final ~docker-compose.yml~. - They usually implement relation hooks, and are providers. + They do not use any CPU or memory resources - 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