From abf8af8a6f8bca8e320e0c4b278b02fc17e75486 Mon Sep 17 00:00:00 2001 From: Roger Luethi Date: Fri, 26 Jun 2026 08:22:07 +0200 Subject: [PATCH 1/3] upgrade-guide: fix vault note for manager update The step-3 note claimed the --ask-vault-pass argument is no longer necessary from OSISM >= 8.0.0. That relief applies to osism apply, which reads the vault password from the OSISM workers (set with osism set vault password, stored in Redis). It does not apply to osism update manager. osism update manager runs out-of-band: it recreates the manager containers and therefore cannot rely on the worker-side vault password. Whenever environments/manager/secrets.yml is encrypted, the password must be supplied directly to this command, via --ask-vault-pass or ANSIBLE_VAULT_PASSWORD_FILE, regardless of the OSISM release. Assisted-by: Claude:claude-opus-4-8 Signed-off-by: Roger Luethi --- docs/guides/upgrade-guide/manager.mdx | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/guides/upgrade-guide/manager.mdx b/docs/guides/upgrade-guide/manager.mdx index 4344c2c7ad..5b70fa7019 100644 --- a/docs/guides/upgrade-guide/manager.mdx +++ b/docs/guides/upgrade-guide/manager.mdx @@ -84,8 +84,13 @@ In the example, OSISM release 7.0.5 is used. osism update manager ``` - * If Ansible Vault was used to encrypt `environments/manager/secrets.yml`, the parameter - `--ask-vault-pass` is also appended. From OSISM >= 8.0.0 this is no longer necessary. + * If Ansible Vault was used to encrypt `environments/manager/secrets.yml`, append + `--ask-vault-pass` (or set `ANSIBLE_VAULT_PASSWORD_FILE` to the vault password file). + Unlike `osism apply`, `osism update manager` runs outside the OSISM workers — it + recreates the manager containers and therefore cannot use the worker-side vault + password set with `osism set vault password`. The password must be supplied directly + whenever `secrets.yml` is encrypted; the OSISM >= 8.0.0 relief from `--ask-vault-pass` + applies to `osism apply`, not to this command. * If `osism update manager` does not work yet, use `osism-update-manager` instead. From 93bccb0cc33eebd71a9be87b793013890cbb8a30 Mon Sep 17 00:00:00 2001 From: Roger Luethi Date: Fri, 26 Jun 2026 08:40:32 +0200 Subject: [PATCH 2/3] upgrade-guide: map manager update to deploy topology The seed container is now a documented deploy path, so a manager may have no local Ansible venv. The manager update step assumed the self-bootstrapped manager and gave no guidance for a cluster deployed from a separate seed node. Add an admonition that names the same osism.manager.manager playbook behind every update and selects the launcher by deployment topology: run osism update manager on a manager that has a local venv, or re-run ./run.sh manager from a still-available seed node. Steps 1, 2 and 4-6 are unchanged across topologies; only step 3 differs. Assisted-by: Claude:claude-opus-4-8 Signed-off-by: Roger Luethi --- docs/guides/upgrade-guide/manager.mdx | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/guides/upgrade-guide/manager.mdx b/docs/guides/upgrade-guide/manager.mdx index 5b70fa7019..a2ab7cabb5 100644 --- a/docs/guides/upgrade-guide/manager.mdx +++ b/docs/guides/upgrade-guide/manager.mdx @@ -17,6 +17,29 @@ adjustments are necessary. Read the release notes even if you are only updating The update of a manager service with a stable release of OSISM is described here. In the example, OSISM release 7.0.5 is used. +:::info Which update path applies to you + +Step 3 below drives the `osism.manager.manager` playbook against the manager over +SSH. The same playbook is used in every case; only how it is launched depends on +how you deployed the cluster. Steps 1, 2 and 4 to 6 are the same for all of them. + +* **Manager with a local Ansible venv** (a self-bootstrapped manager): run + `osism update manager` on the manager itself — this is the path described below. +* **Seed node still available** (a separate workstation or VM that holds the + configuration repository, as in the [Seed deploy guide](../deploy-guide/seed.md)): + update from the seed instead of the manager. After bumping `manager_version` + (step 1) and syncing the configuration repository on the manager (step 2), + re-run the manager playbook from the seed: + + ```bash + ./run.sh manager + ``` + + This reuses the same seed tooling as the initial bootstrap, so the manager + itself needs no local Ansible installation. + +::: + 1. Change the OSISM release in the configuration repository. 1. Set the new OSISM version in the configuration repository. From 7fd026460a3192629ac84a105f385ce91363bcda Mon Sep 17 00:00:00 2001 From: Roger Luethi Date: Fri, 26 Jun 2026 08:40:32 +0200 Subject: [PATCH 3/3] upgrade-guide: document seed-container manager update Add the remaining deploy topology to the manager update admonition: a manager deployed with the seed container and then separated from its seed has no local Ansible venv, yet the documented update runs osism update manager on the manager. Document that such a manager updates with run.sh from the configuration repository on the manager itself. run.sh ships in the repository and is refreshed by make sync, so it does not depend on the manager's installed tooling; with a container engine present and no local venv it runs the playbook inside the osism/seed container automatically (SEED_CONTAINER=auto). The vault password must be reachable (environments/.vault_pass or ANSIBLE_ASK_VAULT_PASS). Once the manager runs a release whose osism-update-manager wrapper reaches seed-container parity, osism update manager does the same and can be used instead; that wrapper change is a separate, non-blocking improvement in osism/ansible-collection-services. Assisted-by: Claude:claude-opus-4-8 Signed-off-by: Roger Luethi --- docs/guides/upgrade-guide/manager.mdx | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/guides/upgrade-guide/manager.mdx b/docs/guides/upgrade-guide/manager.mdx index a2ab7cabb5..5742afcffb 100644 --- a/docs/guides/upgrade-guide/manager.mdx +++ b/docs/guides/upgrade-guide/manager.mdx @@ -37,6 +37,23 @@ how you deployed the cluster. Steps 1, 2 and 4 to 6 are the same for all of them This reuses the same seed tooling as the initial bootstrap, so the manager itself needs no local Ansible installation. +* **Manager deployed with the seed container, seed discarded** (the manager has + no local Ansible venv and no seed node remains): run the update from the + configuration repository on the manager itself. `run.sh` ships in the repository + and is refreshed by `make sync` (step 1), so it does not depend on the manager's + installed tooling. With a container engine present and no local venv it runs the + playbook inside the `osism/seed` container automatically (`SEED_CONTAINER=auto`): + + ```bash + cd /opt/configuration/environments/manager + ./run.sh manager + ``` + + The vault password must be reachable — ship `environments/.vault_pass` in the + configuration repository or export `ANSIBLE_ASK_VAULT_PASS=true` (see the vault + note in step 3). Once the manager runs a release whose wrapper supports it, + `osism update manager` (`CONTAINER=auto`) does the same thing and can be used + instead. :::