Browse Source

new: doc: add notes about types of charms

rallly
Valentin Lab 10 months ago
parent
commit
c7bb477d30
  1. 104
      README.org

104
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.
Loading…
Cancel
Save