This commit changes how we handle Docker authentication. We no longer
try to auth when pushing/pulling images. This was initially done based
on a misunderstanding of how authentication was handled in docker-py.
docker-py will automagically use the base64-encoded username/password
combination stored in config.json if present, so we don't need to auth
at all for push or pull, docker-py will handle all of that. We just need
to make sure that we get the auth info into the config.json. To do this
I have added a login() function to the execution module, which uses the
Docker CLI to authenticate (with output_loglevel set to "quiet" to
suppress any logging of the credentials). The CLI is used in this
instance because docker-py provides no interface by which to persist a
login in the config.json; it can read from the file, but is not designed
to *write* to it. Rather than trying to write to this file ourselves,
and potentially breaking it when (not *if*) Docker decides to change the
internal format of the JSON data structure, using the CLI is a way of
future-proofing the authentication logic.
Context caching of the docker-py client instance has also been removed.
Context caching was used based on the same incorrect understanding of
how docker-py handles authentication, and sought to avoid repeated login
attempts. As that is no longer a concern, there is no need to cache the
client instance in the context dunder because we don't really gain a
performance benefit from it.
The _image_wrapper() function has been removed, as it no longer serves
any purpose, and the image-specific code in it that was still needed
has been absorbed into the _client_wrapper() helper. The functions which
used the _image_wrapper() helper (like push() and pull()) now use
_client_wrapper().
Additionally, the decorators used to enforce a minimum Docker version
(or Docker API version) have been removed. These are not necessary since
docker-py handles raising exceptions when a given feature is not
supported by the effective API version. The _client_wrapper() helper
function now checks for miscellaneous docker exceptions by catching the
docker.errors.DockerException class, which is the base class for the
custom exceptions raised by docker-py, and by doing so catches exceptions
raised due to API version incompatibility (and more).
The list of functions in the top-level docstring has been removed as it
is very out-of-date, and is somewhat superfluous anyway given that we
have for some time now had a list of the functions on the right side of
the page in the documentation.
Other changes:
- Fixed a bug I introduced when I overhauled the
docker_container.running state, in which a container with no changes
to be made, which was not running, would be started by the state even
when test=True was passed.
- Custom registry image names are now properly identified. The colon in
the hostname of the custom registry was previously causing incorrect
identification of the image name and tag, when no explicit tag was
being passed (e.g. localhost:5000/myimage).
- When configuring credentials, the creds for the Docker Hub can be
configured under a registry named ``hub``. This keeps the user from
having to figure out the registry URL and configure it in their Pillar
data, and thus makes using this module easier.
- Removes the email address from the documentation for credential
configuration. This was probably initially added because docker-py
accepts it as an argument, but it is entirely ignored for purposes of
authentication (even by docker-py) and is thus unnecessary. Relic of
an earlier time in Docker's history, perhaps?
- Fixed RST references to functions which weren't caught when this
module was renamed to dockermod.py
- Allow filter arguments in docker.networks to be passed as a
comma-separated list as well as a Python list, in keeping with general
usage elsewhere in Salt.
