search

TritonDataCenter / sdc-docker

Docker Engine for Triton
Mozilla Public License 2.0
182 stars 49 forks source link

Docker commands mentioning "affinity" should co-mention "locality" #96

Open alexandrascript opened 7 years ago

alexandrascript commented 7 years ago

This issue originated in the documentation repo: https://github.com/joyent/documentation/issues/902

"We refer to locality hints in our doc base for the ability to specify near/far on provision (to allow users to hint where they want containers to go). However, on the docker side we call this "affinity", which means when someone searches the doc base for "locality" they don't find this. We should note this, so at the very least this page comes up when they search."

As far as I can tell, an update need to happen in these two places: https://github.com/joyent/sdc-docker/blob/master/docs/api/commands/create.md https://github.com/joyent/sdc-docker/blob/master/docs/api/commands/run.md

trentm commented 7 years ago

@heyawhite There are also a number of hits in placement.md:

api/commands/create.md
171:Docker Swarm's affinity filters for controlling on which server a container

api/commands/run.md
520:Docker Swarm's affinity filters for controlling on which server a container

api/features/placement.md
53:## Swarm affinity
61:Swarm defines "filters" for node selection, and in particular ["affinity
62:filters"](https://docs.docker.com/swarm/scheduler/filter/#use-an-affinity-filter)
65:    docker run --name db1 -e 'affinity:container!=db0' -d mysql
70:implements the same affinity filters as documented for Docker Swarm, with the
76:An affinity filter is an argument to `docker run` or `docker create` using
79:    docker run -e 'affinity:<filter>' ...
117:    docker run -e 'affinity:container==silent_bob' ...
123:    docker run -e 'affinity:role!=database' ...
126:    docker run -e 'affinity:container!=foo*' ...
129:    docker run -e 'affinity:container!=/^foo/' ...
139:`triton` CLI for creating and running containers supports a similar affinity
151:The use of affinity rules can mean the placement is impossible. For example:
163:$ docker --tls run --name db1 -e 'affinity:container!=db0' alpine hostname

In Docker-land (as brian mentioned on the originating ticket) it is called "affinity". I think it would be helpful/good to add something like (also called "locality hints" in Triton, see the [cloudapi CreateMachine notes](https://apidocs.joyent.com/cloudapi/#CreateMachine)) appended to one or more mentions of affinity in features/placement.md.

alexandrascript commented 7 years ago

I've got some changes in a PR ready to go, per your review: https://github.com/joyent/sdc-docker/pull/97

If there's a better way to go about this process, let me know.

alexandrascript commented 7 years ago

@trentm poking again for a review! Thanks.

alexandrascript commented 7 years ago

I have submitted a change review on Gerrit: https://cr.joyent.us/#/c/1047/