From 793382dcd0dd1018c405d2b92c6feb3d409c0bf8 Mon Sep 17 00:00:00 2001 From: Tortue Torche <126358-tortuetorche@users.noreply.gitlab.com> Date: Wed, 28 Aug 2019 16:34:51 +0200 Subject: [PATCH] Update docs for Job stuff, again... --- docs/README.md | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/README.md b/docs/README.md index e5fdd09..85964b2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -34,8 +34,9 @@ - [Debug mode](#debug-mode) - [Strict mode](#strict-mode) - [Quiet mode](#quiet-mode) - - [Job definition](#job-definition) - [`detect-job` option](#detect-job-option) +- [Glossary](#glossary) + - [Job](#job) @@ -291,7 +292,7 @@ mythirdstack ### `status` Check if the stack is running/deployed correctly -If your stack has some services who acts as [jobs](#job-definition), see the [`--detect-job`](#detect-job-option) option for more details. +If your stack has some services who acts as [jobs](#job), see the [`--detect-job`](#detect-job-option) option for more details. #### Usage: `psu status [options]` @@ -347,7 +348,7 @@ List services already deployed in the current stack. ### `tasks` List tasks in the current stack. -If your stack has some services who acts as [jobs](#job-definition), see the [`--detect-job`](#detect-job-option) option for more details. +If your stack has some services who acts as [jobs](#job), see the [`--detect-job`](#detect-job-option) option for more details. #### Usage: `psu tasks [options]` @@ -382,7 +383,7 @@ If your stack has some services who acts as [jobs](#job-definition), see the [`- List tasks who are running correctly in the current stack. -If your stack has some services who acts as [jobs](#job-definition), see the [`--detect-job`](#detect-job-option) option for more details. +If your stack has some services who acts as [jobs](#job), see the [`--detect-job`](#detect-job-option) option for more details. #### Usage: `psu tasks:healthy [options]` @@ -446,7 +447,6 @@ Log in to a Portainer instance. #### Usage: `psu login [options]` - #### Aliased action: `auth` @@ -671,22 +671,26 @@ It's inspired by the `--quiet` option of [`docker images`](https://docs.docker.c Quiet mode can be enabled through `QUIET_MODE` envvar or `--quiet` option or `-q` flag. -### Job definition +### `detect-job` option + +The `--detect-job` option (`true` by default) detects if a service has a restart policy set to `none` and considered this service as a [Job](#job). +If set to `false`, to considering a service as a [Job](#job), you need to set a container's [label](https://docs.docker.com/compose/compose-file/#labels-1) named `job-name` with the value you want (e.g. `my-job-service-name`) in the Docker compose/stack file. + +_See the [Job definition](#job) section for more details._ + +## Glossary + +### Job Docker (or Portainer) doesn't have a true [Job](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) mechanism like [Kubernetes](https://kubernetes.io). But `psu` use an equivalent Docker behavior, based on filtering tasks status with a specific container's [label](https://docs.docker.com/compose/compose-file/#labels-1) (`job-name`). Or when, in your Docker compose/stack file, a service [`deploy.restart_policy.condition`](https://docs.docker.com/compose/compose-file/#restart_policy) option is set to `none`. -The `psu` definition of a [Job](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) is a Swarm [service](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/) who ensures that all it specified [task(s)](https://docs.docker.com/engine/swarm/how-swarm-mode-works/swarm-task-states/) successfully terminate. +The `psu` definition of a job is a Swarm [service](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/) who ensures that all its specified [task(s)](https://docs.docker.com/engine/swarm/how-swarm-mode-works/swarm-task-states/) successfully terminate. -Jobs are useful when you have a service who wants to run a script (e.g. database migration). +Using a job is useful when you want to have a service who run a script (e.g. database migration). And shutdown this service when its script is successfully executed. -See the `job` service in the [`docker-stack-web-app.yml`](https://gitlab.com/psuapp/psu/tree/v1.0.0/tests/dockerfiles/docker-stack-web-app.yml) file for a real use case. +See the service named `job` in the [`docker-stack-web-app.yml`](https://gitlab.com/psuapp/psu/tree/v1.0.0/tests/dockerfiles/docker-stack-web-app.yml) file, for a real use case. It has both a container's label `job-name` and a restart policy set to `none`. - -### `detect-job` option - -The `--detect-job` option (`true` by default) detects if a service has a restart policy set to `none` and considered this service as a job. -If set to `false`, to considering a service as a job, you need to set a container's [label](https://docs.docker.com/compose/compose-file/#labels-1) named `job-name` with the value you want (e.g. `my-job-service-name`) in the Docker compose/stack file.