fork 0k-charms
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

200 lines
7.4 KiB

  1. * 0k-charms
  2. This package provides charms, which are special system recipes, that are
  3. meant to be executable and mangled together to allow managing a wide set
  4. of services.
  5. Inspired by [[https://discourse.juju.is/t/introduction-to-juju-charms/1188][juju charms]], these are mostly bash scripts organized by
  6. service and meant to automate all administration tasks, from
  7. installation, to connection with other services, or any other task a
  8. service would need.
  9. Several tools are able to read the current state of this repository to
  10. effectively deploy full production grade services on different type of
  11. platform.
  12. The only real fully functional implementation is =0k-compose=. It will
  13. use these charms to drive, prepare, and build in =docker=, complete sets
  14. of services.
  15. Another old solution called =lxc-deploy= was used actively before to deploy
  16. services on LXC tool set until 2016 using these charms.
  17. Bare hosts can also replay some recipes to install services directly
  18. on them via the =0k-charm= project using the =charm apply=
  19. command. Note that actually, as most recipes are bash executable, it
  20. is still a viable option to copy-paste parts of source-code of these
  21. scripts. These last two options are still used very often to bootstrap
  22. installs of =docker-hosts= for instance.
  23. * Maturity
  24. Charms in these repository are in a wide set of maturity, from simple note
  25. taking of shell commands, not even executable, to full charm allowing to
  26. deploy services and manage the full life cycle of the service.
  27. The repository in a whole is thus NOT considered as mature at all, and will
  28. require some thorough cleaning and decisions to furthermore structure to reach
  29. a state where it'll make sense to go full public.
  30. * Usage
  31. ** TODO Through =compose= for full deployment of sets of services
  32. Requires =0k-compose= package that contains the =compose= command line tool.
  33. TBD
  34. ** TODO Through =lxc-deploy= for full install and deployment of services
  35. Requires =lxc-scripts= package that holds several tools for LXC
  36. management, amongst them is =lxc-deploy=.
  37. TBD
  38. ** TODO Through =docker-build-charm= for docker image creation
  39. Requires =0k-docker= package that holds several tools for docker
  40. management, amongst them is =docker-build-charm=.
  41. =docker-build-charm= will use the =install= recipes in a charm to
  42. basically mimic the =Dockerfile= purpose and create a docker image for
  43. a specific service.
  44. TBD
  45. ** TODO Through =0k-charm= for bare hosts installs
  46. Requires =0k-charm= package to get the =charm= command line util.
  47. TBD
  48. * Installation
  49. Most tools should check the =CHARM_STORE= bash environment variable
  50. that should be the path to reach the root of this repository. If not
  51. defined, most tools will look in =/srv/charm-store= by default.
  52. * Specs
  53. ** charm type
  54. Not all charm are designed to set up a continuously running, listening
  55. service.
  56. In a charm's ~metadata.yml~, the root-level key ~type~ can have one of
  57. these values:
  58. - ~daemon~ (default)
  59. By default, a charm is of type ~daemon~. It's probably the most
  60. expected way to run a service: it brings up a process that is
  61. *always running*. Examples include charms like ~apache~, ~mysql~,
  62. ~postgres~.
  63. These charms bring up processes that typically open ports to provide
  64. their functionality, perform background tasks like checking the time
  65. and scheduling commands (as the ~cron~ charm), and may use files to
  66. trigger or report on their activities.
  67. In the final ~docker-compose.yml~, a ~daemon~ type charm will
  68. ensure that an entry is created for the service they manage,
  69. resulting in a container that stays in memory. As such they require
  70. a docker image. They will ensure that these entries are managed with
  71. ~restart: unless-stopped~ policy.
  72. The processes managed by these charms will be setup via
  73. ~docker-compose up~ actions at the end, and they will run in the
  74. background.
  75. Once brought up, the processes from these charms will consume CPU and
  76. memory resources indefinitely, until you manually bring them down.
  77. It makes sense to bring them ~up~ or ~down~.
  78. - ~command~
  79. This charm type is used to prepare *a process that run and exits
  80. after execution*. These are more what could be expected of a
  81. "command", and are typically invoked by an other service for
  82. specific events.
  83. Example includes ~logrotate~, ~rsync-backup~, and ~letsencrypt~,
  84. which are charms of type ~run-once~.
  85. These charms are meant to setup commands that are triggered by
  86. services at specific moments or as a result of specific event. It is
  87. through their ~relation~ hooks with other services that they will
  88. ensure to be called when intended to. They are run through the
  89. ~docker-compose run~ call.
  90. Like ~daemon~'s typed charm, these charm will ensure that an entry
  91. is correctly added in the final ~docker-compose.yml~ with all the
  92. necessary options so it is ready to be triggered. They require also
  93. a docker image.
  94. But unlike ~daemon~'s typed charms, these charm will ensure that
  95. the entry they managed in the final ~docker-compose.yml~ *DO NOT*
  96. have an automatic restart policy.
  97. They consume CPU and memory resources only when running and release
  98. resources once finished.
  99. - ~stub~
  100. A ~stub~ charm is more of a placeholder that doesn't have anything
  101. to run at all ! They don't need any docker image. These entities are
  102. used to hold information in ~compose.yml~ and can often be used to
  103. represent a real service managed externally (out of =compose=, on
  104. another host or through a different management system, such as a
  105. local installation, LXC, VirtualBox, etc.).
  106. For example, ~smtp-stub~ charm can be used to build an entity that
  107. will stand for an external ~smtp~ service. Through relations, these
  108. stubs offer interfaces similar to actual services in the setting up
  109. stage. For instance, a ~smtp-stub~ acts as a ~smtp-server~ provider,
  110. and can satisfy ~services~ that would require a ~smtp-server~
  111. provider.
  112. They generally implement relation hooks and act as providers.
  113. No entry is created for them in the final ~docker-compose.yml~.
  114. They do not use any CPU or memory resources
  115. ** login and password policy
  116. A charm have to manage different set of password. The best would be
  117. that the charm:
  118. - don't require user to choose password (less configuration)
  119. - will promote reasonable security practice.
  120. There are 2 types of password:
  121. - inter-service passwords (ie: database access password), these are
  122. never used by human operator, and will be required to be known by
  123. the charms to set things up. These should be generated randomly
  124. (although they could be set also via configuration if mentionned).
  125. - they can only be changed by specific backend technical manipulation.
  126. - user service's admin password (ie: admin user of odoo, nextcloud)
  127. - they can be changed through the service interface.
  128. - this service interface is available to the public and the general users.
  129. - charm doesn't need the password to set things up around the service.
  130. *** Inter-service passwords
  131. - Login should be defaulted to name of the service when possible
  132. - Should be defaulted to random values if not provided in configuration.
  133. - Should not be advertised even in the command line interface.
  134. - Should be reset-able anytime.
  135. *** Interactive admin user service's password
  136. - Login should be defaulted to 'admin'
  137. - Should be defaulted to random values, and not be configurable in configuration.
  138. - Should be advertised at the end of ~compose up~ along with URL of services as long
  139. as the default value chosen by compose is still working.
  140. - Should not be advertised once it was changed by user.