community.docker.docker_api (3.8.1) — connection

Install collection

Install with ansible-galaxy collection install community.docker:==3.8.1

Add to requirements.yml

  collections:
    - name: community.docker
      version: 3.8.1

Description

Run commands or put/fetch files to an existing docker container.

Uses the L(requests library,https://pypi.org/project/requests/) to interact directly with the Docker daemon instead of using the Docker CLI. Use the P(community.docker.docker#connection) connection plugin if you want to use the Docker CLI.

Requirements

• requests
• pywin32 (when using named pipes on Windows 32)
• paramiko (when using SSH with O(use_ssh_client=false))
• pyOpenSSL (when using TLS)
• backports.ssl_match_hostname (when using TLS on Python 2)

Inputs

    
tls:
    default: false
    description:
    - Secure the connection to the API by using TLS without verifying the authenticity
      of the Docker host server. Note that if O(validate_certs) is set to V(true) as well,
      it will take precedence.
    - If the value is not specified in the task, the value of environment variable E(DOCKER_TLS)
      will be used instead. If the environment variable is not set, the default value
      will be used.
    type: bool
    vars:
    - name: ansible_docker_tls

debug:
    default: false
    description:
    - Debug mode
    type: bool

ca_path:
    aliases:
    - ca_cert
    - tls_ca_cert
    - cacert_path
    description:
    - Use a CA certificate when performing server verification by providing the path to
      a CA certificate file.
    - If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH)
      is set, the file C(ca.pem) from the directory specified in the environment variable
      E(DOCKER_CERT_PATH) will be used.
    - This option was called O(ca_cert) and got renamed to O(ca_path) in community.docker
      3.6.0. The old name has been added as an alias and can still be used.
    type: path
    vars:
    - name: ansible_docker_ca_cert
    - name: ansible_docker_ca_path
      version_added: 3.6.0
      version_added_collection: community.docker

timeout:
    default: 60
    description:
    - The maximum amount of time in seconds to wait on a response from the API.
    - If the value is not specified in the task, the value of environment variable E(DOCKER_TIMEOUT)
      will be used instead. If the environment variable is not set, the default value
      will be used.
    type: int
    vars:
    - name: ansible_docker_timeout

client_key:
    aliases:
    - tls_client_key
    - key_path
    description:
    - Path to the client's TLS key file.
    - If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH)
      is set, the file C(key.pem) from the directory specified in the environment variable
      E(DOCKER_CERT_PATH) will be used.
    type: path
    vars:
    - name: ansible_docker_client_key

api_version:
    aliases:
    - docker_api_version
    default: auto
    description:
    - The version of the Docker API running on the Docker Host.
    - Defaults to the latest version of the API supported by this collection and the docker
      daemon.
    - If the value is not specified in the task, the value of environment variable E(DOCKER_API_VERSION)
      will be used instead. If the environment variable is not set, the default value
      will be used.
    type: str
    vars:
    - name: ansible_docker_api_version

client_cert:
    aliases:
    - tls_client_cert
    - cert_path
    description:
    - Path to the client's TLS certificate file.
    - If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH)
      is set, the file C(cert.pem) from the directory specified in the environment variable
      E(DOCKER_CERT_PATH) will be used.
    type: path
    vars:
    - name: ansible_docker_client_cert

docker_host:
    aliases:
    - docker_url
    default: unix:///var/run/docker.sock
    description:
    - 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, V(tcp://192.0.2.23:2376).
      If TLS is used to encrypt the connection, the module will automatically replace
      C(tcp) in the connection URL with C(https).
    - If the value is not specified in the task, the value of environment variable E(DOCKER_HOST)
      will be used instead. If the environment variable is not set, the default value
      will be used.
    type: str
    vars:
    - name: ansible_docker_docker_host

remote_addr:
    default: inventory_hostname
    description:
    - The name of the container you want to access.
    type: str
    vars:
    - name: inventory_hostname
    - name: ansible_host
    - name: ansible_docker_host

remote_user:
    cli:
    - name: user
    description:
    - The user to execute as inside the container.
    env:
    - name: ANSIBLE_REMOTE_USER
    ini:
    - key: remote_user
      section: defaults
    keyword:
    - name: remote_user
    type: str
    vars:
    - name: ansible_user
    - name: ansible_docker_user

ssl_version:
    description:
    - Provide a valid SSL version number. Default value determined by L(SSL Python module,
      https://docs.python.org/3/library/ssl.html).
    - If the value is not specified in the task, the value of environment variable E(DOCKER_SSL_VERSION)
      will be used instead.
    type: str
    vars:
    - name: ansible_docker_ssl_version

tls_hostname:
    description:
    - When verifying the authenticity of the Docker Host server, provide the expected
      name of the server.
    - If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_HOSTNAME)
      will be used instead. If the environment variable is not set, the default value
      will be used.
    - Note that this option had a default value V(localhost) in older versions. It was
      removed in community.docker 3.0.0.
    type: str
    vars:
    - name: ansible_docker_tls_hostname

use_ssh_client:
    default: false
    description:
    - For SSH transports, use the C(ssh) CLI tool instead of paramiko.
    type: bool
    version_added: 1.5.0
    version_added_collection: community.docker

validate_certs:
    aliases:
    - tls_verify
    default: false
    description:
    - Secure the connection to the API by using TLS and verifying the authenticity of
      the Docker host server.
    - If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_VERIFY)
      will be used instead. If the environment variable is not set, the default value
      will be used.
    type: bool
    vars:
    - name: ansible_docker_validate_certs

container_timeout:
    cli:
    - name: timeout
    default: 10
    description:
    - Controls how long we can wait to access reading output from the container once execution
      started.
    env:
    - name: ANSIBLE_TIMEOUT
    - name: ANSIBLE_DOCKER_TIMEOUT
      version_added: 2.2.0
      version_added_collection: community.docker
    ini:
    - key: timeout
      section: defaults
    - key: timeout
      section: docker_connection
      version_added: 2.2.0
      version_added_collection: community.docker
    type: integer
    vars:
    - name: ansible_docker_timeout
      version_added: 2.2.0
      version_added_collection: community.docker