docs. Renew modules/updates.md

docs/core/updates.md

@@ -7,40 +7,75 @@ parent: Core
 
 # Core updates
 
-* TOC
-{:toc}
+The core update changes both the core images and the core modules. In the
+first stage cluster nodes update the core components. In the second stage
+the leader node launches the update of individual core modules.
 
-## NS8 updates
+## First stage
 
-Core updates include enhancements and bug fixes for the `core` image. Such image contains: agents, UI and common actions.
+The first stage applies enhancements and bug fixes for the `core` image.
+Such image contains: agents, UI, additional core images and common
+actions.
 
 To execute the core update, use:
 
     api-cli run update-core --data '{"core_url":"ghcr.io/nethserver/core:latest","nodes":[1, 2]}'
 
-The cluster agent forwards the request to selected nodes.
-Each node agent downloads the new image and restart core services: agents, redis and api-server.
-The core services restart occurs only if the core version update has at least a minor release increment.
+The cluster agent running on the leader node forwards the core-update
+request to selected nodes.
 
-The following applications are part of the core but can be updated as normal modules:
+Each node agent compares the image tag of the `core_url` parameter with
+core image version installed on the node. One of the following cases
+applies:
 
-- ldapproxy
-- traefik
-- samba, openldap
-- loki
+- Both tags are valid Semver tags: the image is installed only if
+  `core_url` is greater than the installed one.
+
+- One or both tags are invalid Semver tags: `core_url` is pulled only
+  if not already present in Podman storage and the update continues
+
+- The `force:true` flag is passed: `core_url` is pulled and update runs
+  ignoring the Semver tag check.
+
+When `core_url` is downloaded, additional images listed in the `core`
+image label `org.nethserver.images` are downloaded as well.
 
-See [module updates]({{site.baseurl}}/modules/updates) for more info.
+After all downloads are successful, the `core` image is installed,
+replacing the previous one.
 
-## Distribution updates
+Then the node agent runs executable scripts under
+`/var/lib/nethserver/node/update-core.d/`. Execution order is
+alphabetical. If a script has non-zero exit code, a warning is printed and
+execution continues with the next script.
 
-Each distribution has its own life-cycle and should be kept updated to handle security fixes.
+If the update fails on some node, the whole process is aborted by the
+leader node at this point.
 
-Simple and dirty commands for Debian:
+## Second stage
 
-    apt-get update && apt-get upgrade
+If every node completes the first stage successfully, the leader node
+starts the second stage.
+
+The cluster agent on the leader node runs executable scripts under
+`/var/lib/nethserver/cluster/update-core-pre-modules.d/`, as described for
+the previous stage. Scripts are obtained from the newly installed core
+image.
+
+Then the cluster agent searches installed core modules. For example, it
+runs the update-module action for any instance of:
+
+- ldapproxy
+- traefik
+- samba, openldap (account providers)
+- loki
 
-Simple and dirty command for CentOS Stream:
+See [module updates]({{site.baseurl}}/modules/updates) for more info about
+module updates, which is applied also to core modules.
 
-    dnf update
+Finally, the cluster agent runs the scripts under
+`/var/lib/nethserver/cluster/update-core-post-modules.d/`, as described in
+the previous stage. Scripts are obtained from the newly installed core
+image.
 
-Please refer to [Debian](https://www.debian.org/doc/manuals/debian-faq/uptodate.en.html) and CentOS official documentation for more info.
+The exit code of the `update-core` action is non-zero if any core module
+has failed its update.

docs/modules/updates.md

@@ -7,30 +7,35 @@ parent: Modules
 
 ## Module updates
 
-Each module instance is responsible for updating itself.
-The core provides an extendable implementation of the `update-module` action for the module agent.
-The basic implementation 
+The core action `update-module` is the entry point of a module instance
+update. It can run the update on multiple instances of the same module at
+the same time.
+
+The core then invokes the module `update-module` action. Each module
+instance is responsible for updating itself. The core already provides an
+extendable implementation of the `update-module` action for the module
+agent. The base implementation
 
 - pulls the module image and additional service images
+- extracts and installs the module _imageroot_ under the `${AGENT_INSTALL_DIR}`
+- runs `systemctl --user daemon-reload`, to refresh Systemd with new unit definitions
 - updates the environment variables, keeping track of `PREV_*` values
-- extracts and installs the module _imageroot_ under the `AGENT_INSTALL_DIR`
-- performs `systemctl daemon-reload`
-- removes no longer required files
-
-After these steps, the module is running with the old version. To load the new version,
-the service should be restarted using a custom script.
-
-Modules can execute custom scripts upon update to handle upgrade paths like database schema migrations.
-Executable scripts should be placed inside `imageroot/update-module.d` which will be then extracted to `${AGENT_INSTALL_DIR}/update-module.d`.
-
-Scripts execution occurs in alphabetical order. Execution breaks when a script exits non-zero and the whole action is aborted.
-
-Example of a script to load the updated version `imageroot/update-module.d/20restart`:
+- runs update scripts installed with the new image, under
+  `${AGENT_INSTALL_DIR}/update-module.d/`
+- removes stale container images
+
+Modules can provide update scripts to handle upgrade paths like restarting
+services and database schema migrations. Executable scripts can be placed
+inside `imageroot/update-module.d` which will be then extracted to
+`${AGENT_INSTALL_DIR}/update-module.d`. Scripts execution occurs in
+alphabetical order. If a script aborts with an exit code, a warning is
+printed. Example of a script that restarts a Systemd service,
+`imageroot/update-module.d/20restart`:
 
     #!/bin/bash
-    systemctl --user restart mymodule
+    systemctl --user try-restart mymodule.service
 
-Make sure the `imageroot/update-module.d/20restart` is executable.
+Make sure the `20restart` is executable, otherwise it is ignored.
 
 To update an instance from command line, use: