From cd06ece0b520b88a8f83d990bcad5675ccbd613a Mon Sep 17 00:00:00 2001 From: decentral1se Date: Fri, 3 Apr 2026 18:08:56 +0200 Subject: [PATCH] docs: more swarm considerations + layout --- docs/abra/swarm.md | 48 +++++++++++++++++++++++++++++++++------------- 1 file changed, 35 insertions(+), 13 deletions(-) diff --git a/docs/abra/swarm.md b/docs/abra/swarm.md index 252107c..09686ca 100644 --- a/docs/abra/swarm.md +++ b/docs/abra/swarm.md @@ -2,8 +2,28 @@ title: Swarm mode almanac --- -> !!! warning "This page is a Work In Progress :tm:" - A page to understand WTF is going on with [Swarm mode](https://docs.docker.com/engine/swarm/key-concepts/) and how we rely on it, how we might not rely on it and other related threads. Please add to this page as you see fit! If we can establish some shared understanding of what is going on under the hood, we can come up with a collective solution which meets everyones needs. +!!! warning "This page is a Work In Progress :tm:" + A page to understand WTF is going on with [Swarm + mode](https://docs.docker.com/engine/swarm/key-concepts/) and how we rely + on it, how we might not rely on it and other related threads. Please add to + this page as you see fit! If we can establish some shared understanding of + what is going on under the hood, we can come up with a collective solution + which meets everyones needs. + +!!! note "No Rug Pull Guarantee :tm:" + If we do decide to change, we need a solution that is backwards compatible + with our existing recipe configuration commons and the current deployments. + We can't re-invent the wheel because we all rely on this system. So, we + need to look towards incremental improvements or changes which are + backwards compatible. We can always agree to change the config commons or + some shared practices but then we need to establish a clear agreement with + decision making. This is the social part. + + No changes will happen without democratic decision making and a solution + which does not leave anyone behind. It might be that we keep using Swarm + for decades to come. There is no need to worry and no rugs will be pulled. + Please get involved in the discussion to provide your input. + ## Support matrix @@ -16,11 +36,15 @@ In practice, this is what we currently rely on Swarm mode for. | Stacks | Firstly, [a service](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/) is key concept here. A stack is then a shared namespace of services with networks, volumes, configs etc. The concept of a stack is a [unique](https://docs.docker.com/engine/swarm/stack-deploy/) to Swarm mode. Any replacement for Swarm mode would have to implement this kind of namespacing feature for backwards compatibility purposes. See [`psviderski/uncloud#94`](https://github.com/psviderski/uncloud/discussions/94) for more. | | Orchestration | When you run `abra app deploy`, we're running a slightly customised `docker stack deploy` under the hood. Swarm mode is supposed to automagically handle zero downtime updates and rollbacks if things fail. However, we're seeing [the limitations of this approach](/abra/swarm/#limitations). | -## Unsupport matrix +## *Maybe* unsupport matrix + +In practice, we don't see people in our community using Swarm mode for this. +Please report in on `#coop-cloud-tech-future-brain:autonomic.zone` if you do +use it! We could really use your input. | Feature | Explanation | | ----------- | ----------- | -| Multi-node | It is possible but it doesn't seem like anyone in our community is really doing this. We believe the majority of Co-op Cloud installs are single node. There is also a lack of [CSI](https://github.com/olljanat/csi-plugins-for-docker-swarm?tab=readme-ov-file) support for coordinating storage across multiple hosts when using Swarm mode. This means we kind of throw out [the majority](https://docs.docker.com/engine/swarm/#feature-highlights) of the features of Swarm mode. | +| Multi-node | It is possible but it doesn't seem like anyone in our community is really doing this? Please report in to `#coop-cloud-tech-future-brain:autonomic.zone` to discuss your usage if you are using multi-node swarm! We believe the majority of Co-op Cloud installs are single node. There is also a lack of [CSI](https://github.com/olljanat/csi-plugins-for-docker-swarm?tab=readme-ov-file) support for coordinating storage across multiple hosts when using Swarm mode. This means we kind of throw out [a bunch](https://docs.docker.com/engine/swarm/#feature-highlights) of the features of Swarm mode. | ## Limitations @@ -36,15 +60,7 @@ In practice, this is what we currently rely on Swarm mode for. * The orchestration features of Swarm mode are opaque, causing failed deployments to be difficult to understand. This can cause a litany of a issues. For example, in the case where your database has been migrated and a rollback of your failing app doesn't support the new schema. This is being discussed extensively on [`organising#682`](https://git.coopcloud.tech/toolshed/organising/issues/682). -## Potential alternatives - -* [`uncloud.run`](https://github.com/psviderski/uncloud): The Uncloud folks are creating a very different system. Something beyond compose but not k8s and not Swarm. This means they have to implement a lot of features of the orchestration from scratch. However, they're going for a nice approach: a straight-forward imperative deployment model (supports `depends_on` for predictable ordering during deployments). They're choosing which parts of the Compose Spec they implement and it's noteworthy that they [don't implement secrets yet](https://github.com/psviderski/uncloud/issues/75). See the [Compose support matrix](https://uncloud.run/docs/compose-file-reference/support-matrix) for more. They are however very focused on multi-node functionality. It's a system to [keep an eye on](https://github.com/psviderski/uncloud/milestone/1) with the hope that we can use some part of it in the future. Lines of communication [have been opened](https://github.com/psviderski/uncloud/discussions/255). - -* [`docker compose`](https://github.com/docker/compose): Plain old `docker compose`. A more elegant weapon for a more civilised age. It is however missing features we need such as encrypted secrets and `template_driver` support. There may be [more things missing](https://github.com/docker/compose/issues/11867). They are developing a promising [SDK](https://docs.docker.com/compose/compose-sdk/) exposes a public API for handling various operations. This would need some serious investigation and most likely some custom solutions for the features we're missing. - -## What we need - -* Something that is backwards compatible with our existing recipe configuration commons and the current deployments. We can't re-invent the wheel because we all rely on this system. So, we need to look towards incremental improvements or changes which are backwards compatible. We can always agree to change the config commons or some shared practices but then we need to establish a clear agreement with decision making. This is the social part. +## What we seem to need * Some way of conveniently using secrets when deploying services. This method should easily support working in a team which doesn't stray too far from our established Git Ops workflow of sharing `$ABRA_DIR`. They don't need to be encrypted and stored on the server (removing the need for Swarm mode handling) as long as they're mounted as secrets in the usual `/run/secret/` manner at runtime. @@ -53,3 +69,9 @@ In practice, this is what we currently rely on Swarm mode for. * A way to namespace services into a deployment, aka a "Docker Stack". This would appear to be a minor implementation detail after all is said and done. It's services all the way down and they have some linked networks/configs/volumes/etc. and a shared naming convention. * Some way to achieve [Fearless YunoHost-esque Upgrades](https://git.coopcloud.tech/toolshed/organising/issues/682#issuecomment-29302). In other words, some predictable way to deploy / upgrade / rollback and some way to intervene when things go wrong. This means we have a "one by one" deployment model which would respect `depends_on` and have explicit way to configure rollbacks (instead of it happening whenever Swarm feels like it). It should be easy to understand for everyone and would enable real stability for operators. I think we want some sort of anti-orchestration implementation which is super simple. + +## Potential alternatives + +* [`uncloud.run`](https://github.com/psviderski/uncloud): The Uncloud folks are creating a very different system. Something beyond compose but not k8s and not Swarm. This means they have to implement a lot of features of the orchestration from scratch. However, they're going for a nice approach: a straight-forward imperative deployment model (supports `depends_on` for predictable ordering during deployments). They're choosing which parts of the Compose Spec they implement and it's noteworthy that they [don't implement secrets yet](https://github.com/psviderski/uncloud/issues/75). See the [Compose support matrix](https://uncloud.run/docs/compose-file-reference/support-matrix) for more. They are however very focused on multi-node functionality. It's a system to [keep an eye on](https://github.com/psviderski/uncloud/milestone/1) with the hope that we can use some part of it in the future. Lines of communication [have been opened](https://github.com/psviderski/uncloud/discussions/255). + +* [`docker compose`](https://github.com/docker/compose): Plain old `docker compose`. A more elegant weapon for a more civilised age. It is however missing features we need such as encrypted secrets and `template_driver` support. There may be [more things missing](https://github.com/docker/compose/issues/11867). They are developing a promising [SDK](https://docs.docker.com/compose/compose-sdk/) exposes a public API for handling various operations. This would need some serious investigation and most likely some custom solutions for the features we're missing.