docker_login - Log into a Docker registry.
New in version 2.0.
Synopsis
- Provides functionality similar to the “docker login” command.
- Authenticate with a docker registry and add the credentials to your local Docker config file. Adding the credentials to the config files allows future connections to the registry using tools such as Ansible’s Docker modules, the Docker CLI and docker-py without needing to provide credentials.
- Running in check mode will perform the authentication without updating the config file.
Requirements (on host that executes module)
- python >= 2.6
- docker-py >= 1.7.0
- Docker API >= 1.20
- Only to be able to logout (state=absent): the docker command line utility
Options
parameter | required | default | choices | comments |
---|---|---|---|---|
api_version | no | default provided by docker-py | The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported by docker-py. aliases: docker_api_version | |
cacert_path | no | Use a CA certificate when performing server verification by providing the path to a CA certificate file. aliases: tls_ca_cert | ||
cert_path | no | Path to the client's TLS certificate file. aliases: tls_client_cert | ||
config_path | no | ~/.docker/config.json | Custom path to the Docker CLI configuration file. aliases: self.config_path, dockercfg_path | |
docker_host | no | unix://var/run/docker.sock | The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the TCP connection string. For example, 'tcp://192.0.2.23:2376'. If TLS is used to encrypt the connection, the module will automatically replace 'tcp' in the connection URL with 'https'. aliases: docker_url | |
email | no | None | The email address for the registry account. NOTE: private registries may not require this, but Docker Hub requires it. | |
key_path | no | Path to the client's TLS key file. aliases: tls_client_key | ||
password | yes | The plaintext password for the registry account | ||
reauthorize | no |
| Refresh exiting authentication found in the configuration file. aliases: reauth | |
registry_url | no | https://index.docker.io/v1/ | The registry URL. aliases: registry, url | |
ssl_version | no | 1.0 | Provide a valid SSL version number. Default value determined by docker-py, currently 1.0. | |
state (added in 2.3)
| no | present |
| This controls the current state of the user. present will login in a user, absent will log him out.To logout you only need the registry server, which defaults to DockerHub. Before 2.1 you could ONLY log in. docker does not support 'logout' with a custom config file. |
timeout | no | 60 | The maximum amount of time in seconds to wait on a response from the API. | |
tls | no | Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. | ||
tls_hostname | no | localhost | When verifying the authenticity of the Docker Host server, provide the expected name of the server. | |
tls_verify | no | Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server. | ||
username | yes | The username for the registry account |
Examples
- name: Log into DockerHub docker_login: username: docker password: rekcod email: [email protected] - name: Log into private registry and force re-authorization docker_login: registry: your.private.registry.io username: yourself password: secrets3 reauthorize: yes - name: Log into DockerHub using a custom config file docker_login: username: docker password: rekcod email: [email protected] config_path: /tmp/.mydockercfg - name: Log out of DockerHub docker_login: state: absent email: [email protected]
Return Values
Common return values are documented here Return Values, the following are the fields unique to this module:
name | description | returned | type | sample |
---|---|---|---|---|
login_results | Results from the login. | when state='present' | dict | {'username': 'testuser', 'password': 'VALUE_SPECIFIED_IN_NO_LOG_PARAMETER', 'email': '[email protected]', 'serveraddress': 'localhost:5000'} |
Notes
Note
- Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docker-py.readthedocs.org/en/stable/machine/ for more details.
Status
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/docker_login_module.html