diff --git a/docs/reference/commandline/service_create.md b/docs/reference/commandline/service_create.md index bce70248..e3249626 100644 --- a/docs/reference/commandline/service_create.md +++ b/docs/reference/commandline/service_create.md @@ -735,52 +735,76 @@ Containers on the same network can access each other using ### Publish service ports externally to the swarm (-p, --publish) You can publish service ports to make them available externally to the swarm -using the `--publish` flag: - -```bash -$ docker service create --publish : nginx -``` - -For example: +using the `--publish` flag. The `--publish` flag can take two different styles +of arguments. The short version is positional, and allows you to specify the +target port and container port separated by a colon. ```bash $ docker service create --name my_web --replicas 3 --publish 8080:80 nginx ``` -When you publish a service port, the swarm routing mesh makes the service -accessible at the target port on every node regardless if there is a task for -the service running on the node. For more information refer to +There is also a long format, which is easier to read and allows you to specify +more options. The long format is preferred. You cannot specify the service's +mode when using the short format. Here is an example of using the long format +for the same service as above: + +```bash +$ docker service create --name my_web --replicas 3 --publish target=8080,port=80 nginx +``` + +The options you can specify are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionShort syntaxLong syntaxDescription
target and container port
protocol--publish 8080:80--publish target=8080,port=80

+ The container port to publish and the target port to bind it to on the + routing mesh or directly on the node. +

modeNot possible to set using short syntax.--publish target=8080,port=80,mode=host

+ The mode to use for binding the port, either `ingress` or `host`. Defaults + to `ingress` to use the routing mesh. +

protocol--publish 8080:80/tcp--publish target=8080,port=80,protocol=tcp

+ The protocol to use, either `tcp` or `udp`. Defaults to `tcp`. To bind a + port for both protocols, specify the `-p` or `--publish` flag twice. +

+ +When you publish a service port using `ingres` mode, the swarm routing mesh +makes the service accessible at the target port on every node regardless if +there is a task for the service running on the node. If you use `host` mode, +the port is only bound on nodes where the service is running, and a given port +on a node can only be bound once. You can only set the publication mode using +the long syntax. For more information refer to [Use swarm mode routing mesh](https://docs.docker.com/engine/swarm/ingress/). -### Publish a port for TCP only or UDP only - -By default, when you publish a port, it is a TCP port. You can -specifically publish a UDP port instead of or in addition to a TCP port. When -you publish both TCP and UDP ports, Docker 1.12.2 and earlier require you to -add the suffix `/tcp` for TCP ports. Otherwise it is optional. - -#### TCP only - -The following two commands are equivalent. - -```bash -$ docker service create --name dns-cache -p 53:53 dns-cache - -$ docker service create --name dns-cache -p 53:53/tcp dns-cache -``` - -#### TCP and UDP - -```bash -$ docker service create --name dns-cache -p 53:53/tcp -p 53:53/udp dns-cache -``` - -#### UDP only - -```bash -$ docker service create --name dns-cache -p 53:53/udp dns-cache -``` - ### Provide credential specs for managed service accounts (Windows only) This option is only used for services using Windows containers. The diff --git a/docs/reference/commandline/service_update.md b/docs/reference/commandline/service_update.md index 7f27f84f..e27e737d 100644 --- a/docs/reference/commandline/service_update.md +++ b/docs/reference/commandline/service_update.md @@ -174,6 +174,21 @@ $ docker service update --mount-rm /somewhere myservice myservice ``` +### Add or remove port mappings + +Use the `--port-add` or `--port-rm` flags to add or remove port mappings to or +from a service. You can use the short or long syntax discussed in the +[docker service update](service_create/#attach-a-service-to-an-existing-network-network) +reference. + +The following example adds a port mapping to an existing service. + +```bash +$ docker service update \ + --port-add port=80,target=8080 \ + myservice +``` + ### Roll back to the previous version of a service Use the `--rollback` option to roll back to the previous version of the service.