New in version 2.0.
The below requirements are needed on the host that executes this module.
Parameter |
Choices/Defaults |
Comments |
---|---|---|
api_version
|
Default:
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
|
|
Use a CA certificate when performing server verification by providing the path to a CA certificate file.
aliases: tls_ca_cert |
cert_path
|
|
Path to the client's TLS certificate file.
aliases: tls_client_cert |
config_path
|
Default:
~/.docker/config.json
|
Custom path to the Docker CLI configuration file.
aliases: self.config_path, dockercfg_path |
docker_host
|
Default:
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
|
|
The email address for the registry account. NOTE: private registries may not require this, but Docker Hub requires it.
|
key_path
|
|
Path to the client's TLS key file.
aliases: tls_client_key |
password
required |
|
The plaintext password for the registry account
|
reauthorize
|
|
Refresh exiting authentication found in the configuration file.
aliases: reauth |
registry_url
|
Default:
https://index.docker.io/v1/
|
The registry URL.
aliases: registry, url |
ssl_version
|
Default:
1.0
|
Provide a valid SSL version number. Default value determined by docker-py, currently 1.0.
|
state
(added in 2.3) |
|
This controls the current state of the user.
present will login in a user, absent will log them 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
|
Default:
60
|
The maximum amount of time in seconds to wait on a response from the API.
|
tls
|
|
Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server.
|
tls_hostname
|
Default:
localhost
|
When verifying the authenticity of the Docker Host server, provide the expected name of the server.
|
tls_verify
|
|
Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server.
|
username
required |
|
The username for the registry account
|
Note
- name: Log into DockerHub
docker_login:
username: docker
password: rekcod
email: docker@docker.io
- 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: docker@docker.io
config_path: /tmp/.mydockercfg
- name: Log out of DockerHub
docker_login:
state: absent
email: docker@docker.com
Common return values are documented here, the following are the fields unique to this module:
Key |
Returned |
Description |
---|---|---|
login_results
dict
|
when state='present' |
Results from the login.
Sample:
{'username': 'testuser', 'email': 'testuer@yahoo.com', 'serveraddress': 'localhost:5000'}
|
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
Hint
If you notice any issues in this documentation you can edit this document to improve it.