Merge pull request #17425 from dvdksn/engine/swarm-note

swarm: add notes about swarm usage, and relation to compose

_data/toc.yaml

@@ -1516,6 +1516,8 @@ manuals:
       title: Manage nodes in a swarm
     - path: /engine/swarm/services/
       title: Deploy services to a swarm
+    - path: /engine/swarm/stack-deploy/
+      title: Deploy a stack to a swarm
     - path: /engine/swarm/configs/
       title: Store service configuration data
     - path: /engine/swarm/secrets/

_includes/swarm-compose-compat.md

@@ -0,0 +1,10 @@
+> **Note**
+>
+> The `docker stack deploy` command uses the legacy
+> [Compose file version 3](/compose/compose-file/compose-file-v3/)
+> format, used by Compose V1. The latest format, defined by the
+> [Compose specification](/compose/compose-file/)
+> isn't compatible with the `docker stack deploy` command.
+>
+> For more information about the evolution of Compose, see
+> [History of Compose](/compose/history/).

_includes/swarm-mode.md

@@ -0,0 +1,10 @@
+> **Note**
+>
+> Swarm mode is an advanced feature for managing a cluster of Docker daemons.
+>
+> Use Swarm mode if you intend to use Swarm as a production runtime environment.
+> 
+> If you're not planning on deploying with Swarm, use
+> [Docker Compose](/compose/) instead.
+> If you're developing for a Kubernetes deployment, consider using the
+> [integrated Kubernetes feature](/desktop/kubernetes/) in Docker Desktop.

engine/swarm/index.md

@@ -45,6 +45,8 @@ redirect_from:
 - /swarm/swarm_at_scale/troubleshoot/
 ---
 
+{% include swarm-mode.md %}
+
 To use Docker in swarm mode, install Docker. See
 [installation instructions](../../get-docker.md) for all operating systems and platforms.
 

engine/swarm/stack-deploy.md

@@ -8,8 +8,10 @@ When running Docker Engine in swarm mode, you can use `docker stack deploy` to
 deploy a complete application stack to the swarm. The `deploy` command accepts
 a stack description in the form of a [Compose file](../../compose/compose-file/compose-file-v3.md).
 
-The `docker stack deploy` command supports any Compose file of version "3.0" or
+{% include swarm-compose-compat.md %}
-above. If you have an older version, see the [upgrade guide](../../compose/compose-file/compose-versioning.md#upgrading).
+
+The `docker stack deploy` command supports any Compose file of version "3.x".
+If you have an older version, see the [upgrade guide](../../compose/compose-file/compose-versioning.md#upgrading).
 
 To run through this tutorial, you need:
 

get-started/swarm-deploy.md

@@ -6,6 +6,8 @@ redirect_from:
 - /get-started/part4/
 ---
 
+{% include swarm-mode.md %}
+
 ## Prerequisites
 
 - Download and install Docker Desktop as described in [Get Docker](../get-docker.md).
@@ -26,6 +28,8 @@ Swarm never creates individual containers like we did in the previous step of th
 
 Let's write a simple stack file to run and manage our Todo app, the container `getting-started` image created in [Part 2](02_our_app.md) of the Quickstart tutorial. Place the following in a file called `bb-stack.yaml`:
 
+{% include swarm-compose-compat.md %}
+
 ```yaml
 version: '3.7'