From 7388a8205d33b0d5a4221f3864d63cd97196dbb0 Mon Sep 17 00:00:00 2001 From: Davide Principi Date: Fri, 26 Jan 2024 12:49:38 +0100 Subject: [PATCH] docs. Renew modules/updates.md --- docs/core/updates.md | 75 ++++++++++++++++++++++++++++++----------- docs/modules/updates.md | 41 ++++++++++++---------- 2 files changed, 78 insertions(+), 38 deletions(-) diff --git a/docs/core/updates.md b/docs/core/updates.md index 64bf08b6b2..410508b707 100644 --- a/docs/core/updates.md +++ b/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. diff --git a/docs/modules/updates.md b/docs/modules/updates.md index a0f898abbf..46fcf0660b 100644 --- a/docs/modules/updates.md +++ b/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: