diff --git a/_data/toc.yaml b/_data/toc.yaml index fc72ea9c34..eafcfd31d8 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1685,10 +1685,8 @@ manuals: section: - title: Deploy a single service path: /ee/ucp/swarm/ - - title: Deploy an app from the UI - path: /ee/ucp/swarm/deploy-from-ui/ - - title: Deploy an app from the CLI - path: /ee/ucp/swarm/deploy-from-cli/ + - title: Deploy a multi-service app + path: /ee/ucp/swarm/deploy-multi-service-app/ - title: Deploy application resources to a collection path: /ee/ucp/swarm/deploy-to-collection/ - title: Use secrets in your services diff --git a/ee/ucp/images/deploy-multi-service-app-1.png b/ee/ucp/images/deploy-multi-service-app-1.png new file mode 100644 index 0000000000..c3e79b02d3 Binary files /dev/null and b/ee/ucp/images/deploy-multi-service-app-1.png differ diff --git a/ee/ucp/images/deploy-multi-service-app-2.png b/ee/ucp/images/deploy-multi-service-app-2.png new file mode 100644 index 0000000000..ef6298e086 Binary files /dev/null and b/ee/ucp/images/deploy-multi-service-app-2.png differ diff --git a/ee/ucp/images/deploy-multi-service-app-3.png b/ee/ucp/images/deploy-multi-service-app-3.png new file mode 100644 index 0000000000..6cd2861668 Binary files /dev/null and b/ee/ucp/images/deploy-multi-service-app-3.png differ diff --git a/ee/ucp/images/deploy-multi-service-app-4.png b/ee/ucp/images/deploy-multi-service-app-4.png new file mode 100644 index 0000000000..bd5ff0b29e Binary files /dev/null and b/ee/ucp/images/deploy-multi-service-app-4.png differ diff --git a/ee/ucp/images/deploy-multi-service-app-5.png b/ee/ucp/images/deploy-multi-service-app-5.png new file mode 100644 index 0000000000..e2b5b332ee Binary files /dev/null and b/ee/ucp/images/deploy-multi-service-app-5.png differ diff --git a/ee/ucp/images/deployed_visualizer.png b/ee/ucp/images/deployed_visualizer.png deleted file mode 100644 index f8fd636ec8..0000000000 Binary files a/ee/ucp/images/deployed_visualizer.png and /dev/null differ diff --git a/ee/ucp/images/deployed_visualizer_detail.png b/ee/ucp/images/deployed_visualizer_detail.png deleted file mode 100644 index 3f7016b102..0000000000 Binary files a/ee/ucp/images/deployed_visualizer_detail.png and /dev/null differ diff --git a/ee/ucp/swarm/deploy-from-cli.md b/ee/ucp/swarm/deploy-from-cli.md deleted file mode 100644 index ebbfbd8501..0000000000 --- a/ee/ucp/swarm/deploy-from-cli.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: Deploy an app from the CLI -description: Learn how to deploy containerized applications on a cluster, with Docker Universal Control Plane. -keywords: ucp, deploy, application, stack, service, compose -redirect_from: - - /ee/ucp/user/services/deploy-app-cli/ -ui_tabs: -- version: ucp-3.0 - orlower: true ---- -{% if include.version=="ucp-3.0" %} - -With Docker Universal Control Plane you can deploy your apps from the CLI, -using `docker-compose.yml` files. In this example, we're going to deploy an -application that allows users to vote on whether they prefer cats or dogs. - -## Get a client certificate bundle - -Docker UCP secures your Docker cluster with -[role-based access control](../authorization/index.md), -so that only authorized users can deploy applications. To be able to run Docker -commands on a cluster managed by UCP, you need to configure your Docker CLI -client to authenticate to UCP using client certificates. -[Learn how to set your CLI to use client certificates](../user-access/cli.md). - -## Deploy the voting application - -The application we're going to deploy is composed of several services: - -* `vote`: The web application that presents the voting interface via port 5000 -* `result`: A web application that displays the voting results via port 5001 -* `visualizer`: A web application that shows a map of the deployment of the - various services across the available nodes via port 8080 -* `redis`: Collects raw voting data and stores it in a key/value queue -* `db`: A PostgreSQL service which provides permanent storage on a host volume -* `worker`: A background service that transfers votes from the queue to permanent storage - -After setting up your Docker CLI client to authenticate using client certificates, -create a file named `docker-compose.yml` with the following contents: - -```yaml -version: "3" -services: - - redis: - image: redis:alpine - ports: - - "6379" - networks: - - frontend - deploy: - replicas: 2 - update_config: - parallelism: 2 - delay: 10s - restart_policy: - condition: on-failure - db: - image: postgres:9.4 - volumes: - - db-data:/var/lib/postgresql/data - networks: - - backend - deploy: - placement: - constraints: [node.role == manager] - vote: - image: manomarks/examplevotingapp_vote - ports: - - 5000:80 - networks: - - frontend - depends_on: - - redis - deploy: - replicas: 6 - update_config: - parallelism: 2 - restart_policy: - condition: on-failure - result: - image: manomarks/examplevotingapp_result - ports: - - 5001:80 - networks: - - backend - deploy: - replicas: 2 - update_config: - parallelism: 2 - delay: 10s - restart_policy: - condition: on-failure - - worker: - image: manomarks/examplevotingapp_worker - networks: - - frontend - - backend - deploy: - mode: replicated - replicas: 2 - labels: [APP=VOTING] - restart_policy: - condition: on-failure - delay: 10s - max_attempts: 3 - window: 120s - placement: - constraints: [node.role == worker] - visualizer: - image: manomarks/visualizer - ports: - - "8080:8080" - stop_grace_period: 1m30s - volumes: - - "/var/run/docker.sock:/var/run/docker.sock" - -networks: - frontend: - backend: - -volumes: - db-data: -``` - -> You can define services in this YAML file that feature a `deploy:` key, which -> schedules the containers on certain nodes, defines their restart behavior, -> configures the number of replicas, and so on. These features are provided -> by the Compose V3 file format. -> [Learn about Compose files](/compose/compose-file/). - -In your command line, navigate to the place where you've created the -`docker-compose.yml` file and deploy the application to UCP by running `docker -stack deploy` and giving the application a name, like "VotingApp": - -```bash -docker stack deploy --compose-file docker-compose.yml VotingApp -``` - -Test that the voting app is up and running using `docker stack services`: - -```bash -docker stack services VotingApp - -ID NAME MODE REPLICAS IMAGE -df7uqiqyqi1n VotingApp_visualizer replicated 1/1 manomarks/visualizer:latest -f185w6xnjibe VotingApp_result replicated 2/2 manomarks/examplevotingapp_result:latest -hh8qzlrjsgyl VotingApp_redis replicated 2/2 redis:alpine -hyvo9xfbzoat VotingApp_db replicated 1/1 postgres:9.4 -op3z6z5ri4k3 VotingApp_worker replicated 1/2 manomarks/examplevotingapp_worker:latest -umoqinuwegzj VotingApp_vote replicated 6/6 manomarks/examplevotingapp_vote:latest -``` - -As you saw earlier, a service called `VotingApp_visualizer` was deployed and -published to port 8080. Visiting that port accesses the running instance of -the visualizer service in your browser, which shows a map of how this application -was deployed: - -![Screenshot of visualizer](../images/deployed_visualizer_detail.png){: .with-border} - -Here you can see some of the characteristics of the deployment specification -from the Compose file in play. For example, the manager node is running the -PostgreSQL container, as configured by setting `[node.role == manager]` as a -constraint in the `deploy` key for the `db` service. - -## Pull images with stack deploy - -Let `docker stack deploy` handle any image pulls for you, instead of using -`docker pull`. This way, your deployment won't try to pull from nodes that -are down. Also, when new nodes are added to the cluster, images are pulled -automatically. - -## Cleanup - -When you're all done, you can take down the entire stack by using `docker stack -rm`: - -```bash -docker stack rm VotingApp - -Removing service VotingApp_visualizer -Removing service VotingApp_result -Removing service VotingApp_redis -Removing service VotingApp_db -Removing service VotingApp_worker -Removing service VotingApp_vote -Removing network VotingApp_backend -Removing network VotingApp_frontend -Removing network VotingApp_default -``` - -{% endif %} diff --git a/ee/ucp/swarm/deploy-from-ui.md b/ee/ucp/swarm/deploy-from-ui.md deleted file mode 100644 index ee109186b6..0000000000 --- a/ee/ucp/swarm/deploy-from-ui.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: Deploy an app from the UI -description: Learn how to deploy containerized applications on a cluster, with Docker Universal Control Plane. -keywords: ucp, deploy, application, stack, service, compose -redirect_from: - - /ee/ucp/user/services/ -ui_tabs: -- version: ucp-3.0 - orlower: true -next_steps: -- path: deploy-from-cli/ - title: Deploy an app from the CLI ---- -{% if include.version=="ucp-3.0" %} - -With Docker Universal Control Plane you can deploy applications from the UI -using `docker-compose.yml` files. In this example, we're going to deploy an -application that allows users to vote on whether they prefer cats or dogs. 😺 🐶 - -## Deploy the voting application - -The application we're going to deploy is composed of several services: - -* `vote`: The web application that presents the voting interface via port 5000 -* `result`: A web application that displays the voting results via port 5001 -* `visualizer`: A web application that shows a map of the deployment of the - various services across the available nodes via port 8080 -* `redis`: Collects raw voting data and stores it in a key/value queue -* `db`: A PostgreSQL service which provides permanent storage on a host volume -* `worker`: A background service that transfers votes from the queue to permanent storage - -In your browser, log in to the UCP web UI, and navigate to the -**Stacks** page. Click **Create Stack** to deploy a new application. - -Give the application a name, like "VotingApp", and in the **Mode** field, -select **Services**. - -Paste the following YAML into the **COMPOSE.YML** editor: - -```yaml -version: "3" -services: - - redis: - image: redis:alpine - ports: - - "6379" - networks: - - frontend - deploy: - replicas: 2 - update_config: - parallelism: 2 - delay: 10s - restart_policy: - condition: on-failure - db: - image: postgres:9.4 - volumes: - - db-data:/var/lib/postgresql/data - networks: - - backend - deploy: - placement: - constraints: [node.role == manager] - vote: - image: manomarks/examplevotingapp_vote - ports: - - 5000:80 - networks: - - frontend - depends_on: - - redis - deploy: - replicas: 6 - update_config: - parallelism: 2 - restart_policy: - condition: on-failure - result: - image: manomarks/examplevotingapp_result - ports: - - 5001:80 - networks: - - backend - deploy: - replicas: 2 - update_config: - parallelism: 2 - delay: 10s - restart_policy: - condition: on-failure - - worker: - image: manomarks/examplevotingapp_worker - networks: - - frontend - - backend - deploy: - mode: replicated - replicas: 2 - labels: [APP=VOTING] - restart_policy: - condition: on-failure - delay: 10s - max_attempts: 3 - window: 120s - placement: - constraints: [node.role == worker] - visualizer: - image: manomarks/visualizer - ports: - - "8080:8080" - stop_grace_period: 1m30s - volumes: - - "/var/run/docker.sock:/var/run/docker.sock" - -networks: - frontend: - backend: - -volumes: - db-data: -``` - -![](../images/deploy-app-ui-1.png){: .with-border} - -> When "Services" is selected, you can define services in this YAML file that -have a `deploy:` key, which schedules the containers on certain nodes, defines -their restart behavior, configures the number of replicas, and so on. These -features are provided by the Compose V3 file format. -[Learn about Compose files](/compose/compose-file/). - -Click **Create** to build and deploy the application. When you see the -**Created successfully** message, click **Done**. - -In the left pane, click **Services** to see the details of the services that -you deployed across your nodes. Click the `VotingApp_vote` service and find -the **Published Endpoint** field in the details pane. Click the link to visit -the voting page, which is published on port `5000`. - -![Screenshot of deployed service](../images/deployed_visualizer.png){: .with-border} - -Click **Cats** and **Dogs** a few times to register some votes, and notice -that each click is processed by a different container. - -Go back to the **Services** page in the UCP web UI. Click the -`VotingApp_result` service and find the **Published Endpoint** field in -the details pane. It has the same URL as the other `VotingApp` services, -but it's published on port `5001`. Click the link to view the vote tally. - -Back in the **Services** page, click the -`VotingApp_visualizer` service and find the **Published Endpoint** field in -the details pane. You'll see a link to your UCP instance's URL that includes -the published port of the visualizer service, which is 8080 in this case. - -Visiting this URL accesses the running instance of the `VotingApp_visualizer` -service in your browser, which shows a map of how this application was deployed: - -![Screenshot of visualizer](../images/deployed_visualizer_detail.png){: .with-border} - -You can see some of the characteristics of the deployment specification -from the Compose file in play. For example, the manager node is running the -PostgreSQL container, as configured by setting `[node.role == manager]` as a -constraint in the `deploy` key for the `db` service. - -## Limitations - -There are some limitations when deploying docker-compose.yml applications from -the UI. You can't reference any external files, so the following Docker -Compose keywords are not supported: - -* build -* dockerfile -* env_file - -To overcome these limitations, you can -[deploy your apps from the CLI](deploy-from-cli.md). - -Also, UCP doesn't store the compose file used to deploy the application. You can -use your version control system to persist that file. - -{% endif %} diff --git a/ee/ucp/swarm/deploy-multi-service-app.md b/ee/ucp/swarm/deploy-multi-service-app.md new file mode 100644 index 0000000000..3d277daaec --- /dev/null +++ b/ee/ucp/swarm/deploy-multi-service-app.md @@ -0,0 +1,166 @@ +--- +title: Deploy a multi-service app +description: Learn how to deploy containerized applications on a cluster, with Docker Universal Control Plane. +keywords: ucp, deploy, application, stack, service, compose +redirect_from: + - /ee/ucp/user/services/ + - /ee/ucp/swarm/deploy-from-cli/ + - /ee/ucp/swarm/deploy-from-ui/ +ui_tabs: +- version: ucp-3.0 + orlower: true +--- + +{% if include.version=="ucp-3.0" %} + +Docker Universal Control Plane allows you to use the tools you already know, +like `docker stack deploy` to deploy multi-service applications. You can +also deploy your applications from the UCP web UI. + +In this example we'll deploy a multi-service application that allows users to +vote on whether they prefer cats or dogs. + +```yaml +version: "3" +services: + + # A Redis key-value store to serve as message queue + redis: + image: redis:alpine + ports: + - "6379" + networks: + - frontend + + # A PostgreSQL database for persistent storage + db: + image: postgres:9.4 + volumes: + - db-data:/var/lib/postgresql/data + networks: + - backend + + # Web UI for voting + vote: + image: dockersamples/examplevotingapp_vote:before + ports: + - 5000:80 + networks: + - frontend + depends_on: + - redis + + # Web UI to count voting results + result: + image: dockersamples/examplevotingapp_result:before + ports: + - 5001:80 + networks: + - backend + depends_on: + - db + + # Worker service to read from message queue + worker: + image: dockersamples/examplevotingapp_worker + networks: + - frontend + - backend + +networks: + frontend: + backend: + +volumes: + db-data: +``` + +## From the web UI + +To deploy your applications from the **UCP web UI**, on the left navigation bar +expand **Shared resources**, choose **Stacks**, and click **Create stack**. + +![Stack list](../images/deploy-multi-service-app-1.png){: .with-border} + +Choose the name you want for your stack, and choose **Swarm services** as the +deployment mode. + +When you choose this option, UCP deploys your app using the +Docker swarm built-in orchestrator. If you choose 'Basic containers' as the +deployment mode, UCP deploys your app using the classic Swarm orchestrator. + +Then copy-paste the application definition in docker-compose.yml format. + +![Deploy stack](../images/deploy-multi-service-app-2.png){: .with-border} + +Once you're done click **Create** to deploy the stack. + +## From the CLI + +To deploy the application from the CLI, start by configuring your Docker +CLI using a [UCP client bundle](../user-access/cli.md). + +Then, create a file named `docker-stack.yml` with the content of the yaml above, +and run: + + + +
+
+``` +docker stack deploy --compose-file voting_app +``` +
+
+``` +docker-compose --file docker-compose.yml --project-name voting_app up -d +``` +
+
+ + +## Check your app + +Once the multi-service application is deployed, it shows up in the UCP web UI. +The 'Stacks' page shows that you've deployed the voting app. + +![Stack deployed](../images/deploy-multi-service-app-3.png){: .with-border} + +You can also inspect the individual services of the app you deployed. For that, +click the **voting_app** to open the details pane, open **Inspect resources** and +choose **Services**, since this app was deployed with the built-in Docker swarm +orchestrator. + +![Service list](../images/deploy-multi-service-app-4.png){: .with-border} + +You can also use the Docker CLI to check the status of your app: + +``` +docker stack ps voting_app +``` + +Great! The app is deployed so we can cast votes by accessing the service that's +listening on port 5000. +You don't need to know the ports a service listens to. You can +**click the voting_app_vote** service and click on the **Published endpoints** +link. + +![Voting app](../images/deploy-multi-service-app-5.png){: .with-border} + +## Limitations + +When deploying applications from the web UI, you can't reference any external +files, no matter if you're using the built-in swarm orchestrator or classic +Swarm. For that reason, the following keywords are not supported: + +* build +* dockerfile +* env_file + +Also, UCP doesn't store the stack definition you've used to deploy the stack. +You can use a version control system for this. + +{% endif %} diff --git a/ee/ucp/swarm/index.md b/ee/ucp/swarm/index.md index e38d4b95f5..90050bceb1 100644 --- a/ee/ucp/swarm/index.md +++ b/ee/ucp/swarm/index.md @@ -1,5 +1,5 @@ --- -title: Deploy a service +title: Deploy a single service description: Learn how to deploy services to a cluster managed by Universal Control Plane. keywords: ucp, deploy, service redirect_from: @@ -65,7 +65,7 @@ You can also deploy the same service from the CLI. Once you've set up your ```bash docker service create --name nginx \ - --publish 8000:80 \ + --publish mode=ingress,target=80,published=8000 \ --label com.docker.ucp.access.owner= \ nginx ```