jade/docs.coopcloud.tech
0
0
Fork 0
forked from toolshed/docs.coopcloud.tech
Code Pull Requests Activity

docs: wording

Browse Source
This commit is contained in:
decentral1se
2026-02-17 09:54:49 +01:00
parent db3706ccf6
commit 04160ecacf
1 changed files with 8 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/abra/swarm.md
View File

@ -3,7 +3,7 @@ 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 random 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.
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.
## Support matrix
@ -11,16 +11,16 @@ In practice, this is what we currently rely on Swarm mode for.
| Feature | Explanation |
| ----------- | ----------- |
| Encrypted secrets | When you run `abra secret generate`, it uses something like `printf foo | docker secret create foo -` under the hood. This feature only works if you have first run `docker swarm join`. Swarm mode is [securly transports and stores your secret encrypted on the server](https://docs.docker.com/engine/swarm/secrets/#how-docker-manages-secrets). `docker compose` does not support encrypting or storing secrets because it only runs client-side. |
| Template driver | If you use `template_driver: golang` in your `compose.yml` to insert secrets or environment variables into your configs, then you are using a template driver. This feature has almost 0 documentation and does not appear to be supported by [the actual Compose Spec](https://github.com/compose-spec/compose-spec/blob/main/08-configs.md) and is actually completely blocked by `docker compose` ([source](https://github.com/docker/compose/blob/f9828dfab909e9dd0dd489a49088c8619ec2ca7e/pkg/compose/create.go#L1095)). Several recipes use this feature and it seems quite critical for our usage. |
| Stacks | Firstly, [a service](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/) is key concept here. A stack is 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 compatibility. 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 handle zero downtime updates and rollbacks if things fail automagically. However, we're seeing the limitations of this approach (see below). |
| Encrypted secrets | When you run `abra secret generate`, it uses something like `printf foo | docker secret create foo -` under the hood. This feature only works if you have first run `docker swarm join`. Swarm mode [securely transports and stores your secret encrypted on the server](https://docs.docker.com/engine/swarm/secrets/#how-docker-manages-secrets). `docker compose` does not support encrypting or storing secrets because it only runs client-side. |
| Template driver | If you use `template_driver: golang` in your `compose.yml` to insert secrets or environment variables into your configs, then you are using a template driver. This feature has almost 0 documentation and does not appear to be supported by [the actual Compose Spec](https://github.com/compose-spec/compose-spec/blob/main/08-configs.md) and is actually completely blocked by `docker compose` ([source](https://github.com/docker/compose/blob/f9828dfab909e9dd0dd489a49088c8619ec2ca7e/pkg/compose/create.go#L1095)). Several recipes use this feature and it seems quite crucial for our usage. |
| 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
| 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 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 when it comes to running multi-node. |
| 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. |
## Limitations
@ -34,11 +34,11 @@ In practice, this is what we currently rely on Swarm mode for.
>
> Way back when (i guess in 2019? before my time!), docker sold off its enterprise platform which was called "swarm" to mirantis, so that's still a product that mirantis has and has developed in their way, but it's not the open-source swarm(kit) that's part of the docker cli. this is a good quick explanation: https://forums.docker.com/t/docker-swarmkit-and-the-mirantis-deal-not-docker-swarm/88886
* The orchestration features of Swarm mode are opaque, causing failed deployments to be very 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 has been discussed extensively on [`organising#682`](https://git.coopcloud.tech/toolshed/organising/issues/682).
* 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): As it turns out, 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` and upgrades stuff one at a time). 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.
* [`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. 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.