Affinity labels like -e affinity:com.example.type==test

[vieux]

No description provided.

[vieux]

ping @aluzzardi @abronan

[abronan]

LGTM

[vieux]

@moxiegirl can you please take a quick look at the doc ? Thank you

[aluzzardi]

Doc feedback - how about:

You can force containers to be co-scheduled on the same node as another container by specifying its name or ID.

/cc @moxiegirl

[aluzzardi]

Minor comments.

Overall LGTM

[moxiegirl]

Looking at this now...I'll give feedback shortly.

[moxiegirl]

@vieux I noticed several things in the current text.

• A "stacked head" between Affinity filters and Labels head. There are different ways to fix a stack like this but I decided to use an explanation at the top. Something short that explains what is affinity and why someone might use it. Please check this to make sure it is accurate.
• The word "schedule" seems awkward to me. Why not just "run" -- I didn't remove "schedule" but I'd like to learn more. It looks like you are just doing a docker run but I need to know more about swarm.
• I updated the the Images section to show how you would get an image id docker images --- hope it is technically correct
• I updated the label section with @aluzzardi changes and added a way to filter for labels in docker ps to illustrate better I hope
• I changed the fourth level heads to include the word affinity. This will improve the Google search returns and keep the headings from being confused with other topics in our docs search
• Finally, I tightened up the language a bit. I think you don't need to specify how many containers or the order in which they start --- your examples illustrate this and, of course, they aren't limited to two so why talk numbers

---> https://gist.github.com/moxiegirl/7b1801dacd71c8eb80be

Affinity filter

You use an --affinity:<filter> to create "attractions" between containers. For
example, you can run a container and instruct it to locate and run next to
another container based on an identifier, an image, or a label. These
attractions ensure that containers run on the same network node — without
you having to know what each node is running.

Container affinity

You can schedule a new container to run next to another based on a container
name or ID. For example, you can start a container called front running
nginx:

$ docker run -d -p 80:80 --name front nginx
 87c4376856a8


$ docker ps
CONTAINER ID        IMAGE               COMMAND             CREATED                  STATUS              PORTS                           NODE        NAMES
87c4376856a8        nginx:latest        "nginx"             Less than a second ago   running             192.168.0.42:80->80/tcp         node-1      front

Then, using -e affinity:container==front flag schedule a second container to
locate and run next to front.

$ docker run -d --name logger -e affinity:container==front logger
 87c4376856a8

$ docker ps
CONTAINER ID        IMAGE               COMMAND             CREATED                  STATUS              PORTS                           NODE        NAMES
87c4376856a8        nginx:latest        "nginx"             Less than a second ago   running             192.168.0.42:80->80/tcp         node-1      front
963841b138d8        logger:latest       "logger"            Less than a second ago   running                                             node-1      logger

Because of name affinity, the logger container ends up on node-1 along with
the front container. Instead of the front name you could have supplied its
ID as follows:

docker run -d --name logger -e affinity:container==87c4376856a8`

Image affinity

You can schedule a container to run only on nodes where a specific image is already pulled.

$ docker -H node-1:2375 pull redis
$ docker -H node-2:2375 pull mysql
$ docker -H node-3:2375 pull redis

Only node-1 and node-3 have the redis image. Specify a -e affinity:image=redis filter to schedule several additional containers to run on
these nodes.

$ docker run -d --name redis1 -e affinity:image==redis redis
$ docker run -d --name redis2 -e affinity:image==redis redis
$ docker run -d --name redis3 -e affinity:image==redis redis
$ docker run -d --name redis4 -e affinity:image==redis redis
$ docker run -d --name redis5 -e affinity:image==redis redis
$ docker run -d --name redis6 -e affinity:image==redis redis
$ docker run -d --name redis7 -e affinity:image==redis redis
$ docker run -d --name redis8 -e affinity:image==redis redis

$ docker ps
CONTAINER ID        IMAGE               COMMAND             CREATED                  STATUS              PORTS                           NODE        NAMES
87c4376856a8        redis:latest        "redis"             Less than a second ago   running                                             node-1      redis1
1212386856a8        redis:latest        "redis"             Less than a second ago   running                                             node-1      redis2
87c4376639a8        redis:latest        "redis"             Less than a second ago   running                                             node-3      redis3
1234376856a8        redis:latest        "redis"             Less than a second ago   running                                             node-1      redis4
86c2136253a8        redis:latest        "redis"             Less than a second ago   running                                             node-3      redis5
87c3236856a8        redis:latest        "redis"             Less than a second ago   running                                             node-3      redis6
87c4376856a8        redis:latest        "redis"             Less than a second ago   running                                             node-3      redis7
963841b138d8        redis:latest        "redis"             Less than a second ago   running                                             node-1      redis8

As you can see here, the containers were only scheduled on nodes that had the
redis image. Instead of the image name, you could have specified the image ID.

$ docker images
REPOSITORY                         TAG                       IMAGE ID            CREATED             VIRTUAL SIZE
redis                              latest                    06a1f75304ba        2 days ago          111.1 MB

$ docker run -d --name redis1 -e affinity:image==06a1f75304ba redis

Label affinity

Label affinity allows you to set up an attraction based on a container's label.
For example, you can run a nginx container with the com.example.type=front label.

$ docker run -d -p 80:80 --label com.example.type=front nginx
 87c4376856a8

$ docker ps  --filter "label=com.example.type=front"
CONTAINER ID        IMAGE               COMMAND             CREATED                  STATUS              PORTS                           NODE        NAMES
87c4376856a8        nginx:latest        "nginx"             Less than a second ago   running             192.168.0.42:80->80/tcp         node-1      trusting_yonath

Then, use -e affinity:com.example.type==front to schedule a container next to
the container with the com.example.type=front label.

$ docker run -d -e affinity:com.example.type==front logger
 87c4376856a8

$ docker ps
CONTAINER ID        IMAGE               COMMAND             CREATED                  STATUS              PORTS                           NODE        NAMES
87c4376856a8        nginx:latest        "nginx"             Less than a second ago   running             192.168.0.42:80->80/tcp         node-1      trusting_yonath
963841b138d8        logger:latest       "logger"            Less than a second ago   running                                             node-1      happy_hawking

The logger container ends up on node-1 because its affinity with the com.example.type==front label.

[vieux]

@aluzzardi @moxiegirl can you please take one last look, I believe it's good to merge

[aluzzardi]

LGTM