From 9ff02812f52856c83a15d34a2f582e193fbfe5ef Mon Sep 17 00:00:00 2001 From: felixfontein Date: Fri, 27 Sep 2024 10:02:05 +0000 Subject: [PATCH] deploy: 423a9bbf6134933d793e49da38093162209f3b58 --- branch/main/changelog.html | 2 + .../main/current_container_facts_module.html | 2 + branch/main/docker_api_connection.html | 2 + branch/main/docker_compose_module.html | 2 + .../main/docker_compose_v2_exec_module.html | 711 +++++++++++++++ branch/main/docker_compose_v2_module.html | 6 +- .../main/docker_compose_v2_pull_module.html | 10 +- branch/main/docker_compose_v2_run_module.html | 848 ++++++++++++++++++ branch/main/docker_config_module.html | 6 +- branch/main/docker_connection.html | 2 + .../docker_container_copy_into_module.html | 2 + branch/main/docker_container_exec_module.html | 2 + branch/main/docker_container_info_module.html | 2 + branch/main/docker_container_module.html | 2 + branch/main/docker_containers_inventory.html | 2 + branch/main/docker_host_info_module.html | 2 + branch/main/docker_image_build_module.html | 2 + branch/main/docker_image_export_module.html | 2 + branch/main/docker_image_info_module.html | 2 + branch/main/docker_image_load_module.html | 2 + branch/main/docker_image_module.html | 2 + branch/main/docker_image_pull_module.html | 2 + branch/main/docker_image_push_module.html | 2 + branch/main/docker_image_remove_module.html | 2 + branch/main/docker_image_tag_module.html | 2 + branch/main/docker_login_module.html | 2 + branch/main/docker_machine_inventory.html | 2 + branch/main/docker_network_info_module.html | 2 + branch/main/docker_network_module.html | 2 + branch/main/docker_node_info_module.html | 2 + branch/main/docker_node_module.html | 2 + branch/main/docker_plugin_module.html | 2 + branch/main/docker_prune_module.html | 2 + branch/main/docker_secret_module.html | 2 + branch/main/docker_stack_info_module.html | 2 + branch/main/docker_stack_module.html | 2 + .../main/docker_stack_task_info_module.html | 2 + branch/main/docker_swarm_info_module.html | 2 + branch/main/docker_swarm_inventory.html | 2 + branch/main/docker_swarm_module.html | 2 + .../docker_swarm_service_info_module.html | 2 + branch/main/docker_swarm_service_module.html | 2 + branch/main/docker_volume_info_module.html | 2 + branch/main/docker_volume_module.html | 2 + branch/main/docsite/scenario_guide.html | 2 + branch/main/environment_variables.html | 2 + branch/main/index.html | 4 + branch/main/nsenter_connection.html | 2 + branch/main/objects.inv | Bin 20056 -> 21158 bytes branch/main/search.html | 2 + branch/main/searchindex.js | 2 +- 51 files changed, 1664 insertions(+), 9 deletions(-) create mode 100644 branch/main/docker_compose_v2_exec_module.html create mode 100644 branch/main/docker_compose_v2_run_module.html diff --git a/branch/main/changelog.html b/branch/main/changelog.html index d0403041..42198e78 100644 --- a/branch/main/changelog.html +++ b/branch/main/changelog.html @@ -480,7 +480,9 @@
  • community.docker.current_container_facts module – Return facts about whether the module runs in a container
  • community.docker.docker_compose module – Manage multi-container Docker applications with Docker Compose V1
  • community.docker.docker_compose_v2 module – Manage multi-container Docker applications with Docker Compose CLI plugin
    • +
  • community.docker.docker_compose_v2_exec module – Run command in a container of a Compose service
  • community.docker.docker_compose_v2_pull module – Pull a Docker compose project
    • +
  • community.docker.docker_compose_v2_run module – Run command in a new container of a Compose service
  • community.docker.docker_config module – Manage docker configs.
  • community.docker.docker_container module – manage Docker containers
  • community.docker.docker_container_copy_into module – Copy a file into a Docker container
    • diff --git a/branch/main/current_container_facts_module.html b/branch/main/current_container_facts_module.html index 0f19388c..c8db61ea 100644 --- a/branch/main/current_container_facts_module.html +++ b/branch/main/current_container_facts_module.html @@ -95,7 +95,9 @@
  • community.docker.docker_compose module – Manage multi-container Docker applications with Docker Compose V1
  • community.docker.docker_compose_v2 module – Manage multi-container Docker applications with Docker Compose CLI plugin
    • +
  • community.docker.docker_compose_v2_exec module – Run command in a container of a Compose service
  • community.docker.docker_compose_v2_pull module – Pull a Docker compose project
    • +
  • community.docker.docker_compose_v2_run module – Run command in a new container of a Compose service
  • community.docker.docker_config module – Manage docker configs.
  • community.docker.docker_container module – manage Docker containers
  • community.docker.docker_container_copy_into module – Copy a file into a Docker container
    • diff --git a/branch/main/docker_api_connection.html b/branch/main/docker_api_connection.html index 2b49e3e4..63b03e00 100644 --- a/branch/main/docker_api_connection.html +++ b/branch/main/docker_api_connection.html @@ -85,7 +85,9 @@
  • community.docker.current_container_facts module – Return facts about whether the module runs in a container
  • community.docker.docker_compose module – Manage multi-container Docker applications with Docker Compose V1
  • community.docker.docker_compose_v2 module – Manage multi-container Docker applications with Docker Compose CLI plugin
    • +
  • community.docker.docker_compose_v2_exec module – Run command in a container of a Compose service
  • community.docker.docker_compose_v2_pull module – Pull a Docker compose project
    • +
  • community.docker.docker_compose_v2_run module – Run command in a new container of a Compose service
  • community.docker.docker_config module – Manage docker configs.
  • community.docker.docker_container module – manage Docker containers
  • community.docker.docker_container_copy_into module – Copy a file into a Docker container
    • diff --git a/branch/main/docker_compose_module.html b/branch/main/docker_compose_module.html index 58450a67..7c71e54f 100644 --- a/branch/main/docker_compose_module.html +++ b/branch/main/docker_compose_module.html @@ -101,7 +101,9 @@
  • community.docker.docker_compose_v2 module – Manage multi-container Docker applications with Docker Compose CLI plugin
    • +
  • community.docker.docker_compose_v2_exec module – Run command in a container of a Compose service
  • community.docker.docker_compose_v2_pull module – Pull a Docker compose project
    • +
  • community.docker.docker_compose_v2_run module – Run command in a new container of a Compose service
  • community.docker.docker_config module – Manage docker configs.
  • community.docker.docker_container module – manage Docker containers
  • community.docker.docker_container_copy_into module – Copy a file into a Docker container
    • diff --git a/branch/main/docker_compose_v2_exec_module.html b/branch/main/docker_compose_v2_exec_module.html new file mode 100644 index 00000000..a67a8584 --- /dev/null +++ b/branch/main/docker_compose_v2_exec_module.html @@ -0,0 +1,711 @@ + + + + + + + + community.docker.docker_compose_v2_exec module – Run command in a container of a Compose service — Community.Docker Collection documentation + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + +
    Community.Docker Collection Docs
    +     +
    + + +
    + +
    +
    +
    +
      +
      • +
    • community.docker.docker_compose_v2_exec module – Run command in a container of a Compose service
      • +
    • + + Edit on GitHub +
      • +
    +
    +
    +
    + + +
    + +
    +

    community.docker.docker_compose_v2_exec module – Run command in a container of a Compose service

    +
    +

    Note

    +

    This module is part of the community.docker collection (version 3.13.0).

    +

    It is not included in ansible-core. +To check whether it is installed, run ansible-galaxy collection list.

    +

    To install it, use: ansible-galaxy collection install community.docker. +You need further requirements to be able to use this module, +see Requirements for details.

    +

    To use it in a playbook, specify: community.docker.docker_compose_v2_exec.

    +
    +

    New in community.docker 3.13.0

    + +
    +

    Synopsis

    +
      +

    • Uses Docker Compose to run a command in a service’s container.

      • +

    • This can be used to run one-off commands in an existing service’s container, and encapsulates docker compose exec.

      • +
    +
    +
    +

    Requirements

    +

    The below requirements are needed on the host that executes this module.

    +
      +

    • Docker CLI with Docker compose plugin 2.18.0 or later

      • +

    • PyYAML if definition is used

      • +
    +
    +
    +

    Parameters

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

    Parameter

    Comments

    +
    +

    api_version

    +

    aliases: docker_api_version

    +

    string

    +

    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 DOCKER_API_VERSION will be used instead. If the environment variable is not set, the default value will be used.

    +

    Default: "auto"

    +
    +

    argv

    +

    list / elements=string

    +

    The command to execute.

    +

    Since this is a list of arguments, no quoting is needed.

    +

    Exactly one of argv or command must be specified.

    +
    +
    +
    +
    +

    ca_path

    +

    aliases: ca_cert, tls_ca_cert, cacert_path

    +

    path

    +

    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 DOCKER_CERT_PATH is set, the file ca.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.

    +
    +

    chdir

    +

    string

    +

    The directory to run the command in.

    +
    +

    check_files_existing

    +

    boolean

    +

    added in community.docker 3.9.0

    +

    If set to false, the module will not check whether one of the files compose.yaml, compose.yml, docker-compose.yaml, or docker-compose.yml exists in project_src if files is not provided.

    +

    This can be useful if environment files with COMPOSE_FILE are used to configure a different filename. The module currently does not check for COMPOSE_FILE in environment files or the current environment.

    +

    Choices:

    +
      +

    • false

      • +

    • true ← (default)

      • +
    +
    +

    cli_context

    +

    string

    +

    The Docker CLI context to use.

    +

    Mutually exclusive with docker_host.

    +
    +
    +
    +

    client_cert

    +

    aliases: tls_client_cert, cert_path

    +

    path

    +

    Path to the client’s TLS certificate file.

    +

    If the value is not specified in the task and the environment variable DOCKER_CERT_PATH is set, the file cert.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.

    +
    +
    +
    +

    client_key

    +

    aliases: tls_client_key, key_path

    +

    path

    +

    Path to the client’s TLS key file.

    +

    If the value is not specified in the task and the environment variable DOCKER_CERT_PATH is set, the file key.pem from the directory specified in the environment variable DOCKER_CERT_PATH will be used.

    +
    +

    command

    +

    string

    +

    The command to execute.

    +

    Exactly one of argv or command must be specified.

    +
    +

    definition

    +

    dictionary

    +

    added in community.docker 3.9.0

    +

    Compose file describing one or more services, networks and volumes.

    +

    Mutually exclusive with project_src and files. One of project_src and definition must be provided.

    +

    If provided, PyYAML must be available to this module, and project_name must be specified.

    +

    Note that a temporary directory will be created and deleted afterwards when using this option.

    +
    +

    detach

    +

    boolean

    +

    Whether to run the command synchronously (detach=false, default) or asynchronously (detach=true).

    +

    If set to true, stdin cannot be provided, and the return values stdout, stderr, and rc are not returned.

    +

    Choices:

    +
      +

    • false ← (default)

      • +

    • true

      • +
    +
    +

    docker_cli

    +

    path

    +

    Path to the Docker CLI. If not provided, will search for Docker CLI on the PATH.

    +
    +
    +

    docker_host

    +

    aliases: docker_url

    +

    string

    +

    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.

    +

    If the value is not specified in the task, the value of environment variable DOCKER_HOST will be used instead. If the environment variable is not set, the default value will be used.

    +

    Mutually exclusive with cli_context. If neither docker_host nor cli_context are provided, the value unix:///var/run/docker.sock is used.

    +
    +

    env

    +

    dictionary

    +

    Dictionary of environment variables with their respective values to be passed to the command ran inside the container.

    +

    Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example "true") in order to avoid data loss.

    +

    Please note that if you are passing values in with Jinja2 templates, like "{{ value }}", you need to add | string to prevent Ansible to convert strings such as "true" back to booleans. The correct way is to use "{{ value | string }}".

    +
    +

    env_files

    +

    list / elements=path

    +

    By default environment files are loaded from a .env file located directly under the project_src directory.

    +

    env_files can be used to specify the path of one or multiple custom environment files instead.

    +

    The path is relative to the project_src directory.

    +
    +

    files

    +

    list / elements=path

    +

    added in community.docker 3.7.0

    +

    List of Compose file names relative to project_src to be used instead of the main Compose file (compose.yml, compose.yaml, docker-compose.yml, or docker-compose.yaml).

    +

    Files are loaded and merged in the order given.

    +

    Mutually exclusive with definition.

    +
    +

    index

    +

    integer

    +

    The index of the container to run the command in if the service has multiple replicas.

    +
    +

    privileged

    +

    boolean

    +

    Whether to give extended privileges to the process.

    +

    Choices:

    +
      +

    • false ← (default)

      • +

    • true

      • +
    +
    +

    profiles

    +

    list / elements=string

    +

    List of profiles to enable when starting services.

    +

    Equivalent to docker compose --profile.

    +
    +

    project_name

    +

    string

    +

    Provide a project name. If not provided, the project name is taken from the basename of project_src.

    +

    Required when definition is provided.

    +
    +

    project_src

    +

    path

    +

    Path to a directory containing a Compose file (compose.yml, compose.yaml, docker-compose.yml, or docker-compose.yaml).

    +

    If files is provided, will look for these files in this directory instead.

    +

    Mutually exclusive with definition. One of project_src and definition must be provided.

    +
    +

    service

    +

    string / required

    +

    The service to run the command in.

    +
    +

    stdin

    +

    string

    +

    Set the stdin of the command directly to the specified value.

    +

    Can only be used if detach=false.

    +
    +

    stdin_add_newline

    +

    boolean

    +

    If set to true, appends a newline to stdin.

    +

    Choices:

    +
      +

    • false

      • +

    • true ← (default)

      • +
    +
    +

    strip_empty_ends

    +

    boolean

    +

    Strip empty lines from the end of stdout/stderr in result.

    +

    Choices:

    +
      +

    • false

      • +

    • true ← (default)

      • +
    +
    +

    tls

    +

    boolean

    +

    Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Note that if validate_certs is set to true as well, it will take precedence.

    +

    If the value is not specified in the task, the value of environment variable DOCKER_TLS will be used instead. If the environment variable is not set, the default value will be used.

    +

    Choices:

    +
      +

    • false ← (default)

      • +

    • true

      • +
    +
    +

    tls_hostname

    +

    string

    +

    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 DOCKER_TLS_HOSTNAME will be used instead. If the environment variable is not set, the default value will be used.

    +
    +

    tty

    +

    boolean

    +

    Whether to allocate a TTY.

    +

    Choices:

    +
      +

    • false

      • +

    • true ← (default)

      • +
    +
    +

    user

    +

    string

    +

    If specified, the user to execute this command with.

    +
    +
    +

    validate_certs

    +

    aliases: tls_verify

    +

    boolean

    +

    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 DOCKER_TLS_VERIFY will be used instead. If the environment variable is not set, the default value will be used.

    +

    Choices:

    +
      +

    • false ← (default)

      • +

    • true

      • +
    +
    +
    +
    +

    Attributes

    + + + + + + + + + + + + + + + + + + + + + +

    Attribute

    Support

    Description

    +

    action_group

    +

    Action groups: community.docker.docker, docker

    +

    Use group/docker or group/community.docker.docker in module_defaults to set defaults for this module.

    +
    +

    check_mode

    +

    Support: none

    +

    Can run in check_mode and return changed status prediction without modifying target.

    +
    +

    diff_mode

    +

    Support: none

    +

    Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

    +
    +
    +
    +

    Notes

    +
    +

    Note

    +
      +

    • If you need to evaluate environment variables of the container in command or argv, you need to pass the command through a shell, like command=/bin/sh -c "echo $ENV_VARIABLE".

      • +

    • The Docker compose CLI plugin has no stable output format (see for example https://github.com/docker/compose/issues/10872), +and for the main operations also no machine friendly output format. The module tries to accomodate this with various +version-dependent behavior adjustments and with testing older and newer versions of the Docker compose CLI plugin. +Currently the module is tested with multiple plugin versions between 2.18.1 and 2.23.3. The exact list of plugin versions +will change over time. New releases of the Docker compose CLI plugin can break this module at any time.

      • +

    • 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_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://docs.docker.com/machine/reference/env/ for more details.

      • +

    • This module does not use the Docker SDK for Python to communicate with the Docker daemon. It directly calls the Docker CLI program.

      • +
    +
    +
    +
    +

    See Also

    +
    +

    See also

    +
    +
    community.docker.docker_compose_v2

    Manage multi-container Docker applications with Docker Compose CLI plugin.

    +
    +
    +
    +
    +
    +

    Examples

    +
    - name: Run a simple command (command)
+  community.docker.docker_compose_v2_exec:
+    service: foo
+    command: /bin/bash -c "ls -lah"
+    chdir: /root
+  register: result
+
+- name: Print stdout
+  ansible.builtin.debug:
+    var: result.stdout
+
+- name: Run a simple command (argv)
+  community.docker.docker_compose_v2_exec:
+    service: foo
+    argv:
+      - /bin/bash
+      - "-c"
+      - "ls -lah > /dev/stderr"
+    chdir: /root
+  register: result
+
+- name: Print stderr lines
+  ansible.builtin.debug:
+    var: result.stderr_lines
+
    +
    +
    +
    +

    Return Values

    +

    Common return values are documented here, the following are the fields unique to this module:

    + + + + + + + + + + + + + + + + + +

    Key

    Description

    +

    rc

    +

    integer

    +

    The exit code of the command.

    +

    Returned: success and detach=false

    +

    Sample: 0

    +
    +

    stderr

    +

    string

    +

    The standard error output of the container command.

    +

    Returned: success and detach=false

    +
    +

    stdout

    +

    string

    +

    The standard output of the container command.

    +

    Returned: success and detach=false

    +
    +
    +

    Authors

    +
      +

    • Felix Fontein (@felixfontein)

      • +
    +
    + +
    +
    + + +
    +
    + + +
    + +
    + +
    +

    © Copyright Community.Docker Contributors.

    +
    + + + + +
    +
    +
    +
    +
    + + + + \ No newline at end of file diff --git a/branch/main/docker_compose_v2_module.html b/branch/main/docker_compose_v2_module.html index 4f1dc328..33378033 100644 --- a/branch/main/docker_compose_v2_module.html +++ b/branch/main/docker_compose_v2_module.html @@ -24,7 +24,7 @@ - + @@ -99,7 +99,9 @@ +
  • community.docker.docker_compose_v2_exec module – Run command in a container of a Compose service
  • community.docker.docker_compose_v2_pull module – Pull a Docker compose project
    • +
  • community.docker.docker_compose_v2_run module – Run command in a new container of a Compose service
  • community.docker.docker_config module – Manage docker configs.
  • community.docker.docker_container module – manage Docker containers
  • community.docker.docker_container_copy_into module – Copy a file into a Docker container
    • @@ -1053,7 +1055,7 @@ will change over time. New releases of the Docker compose CLI plugin can break t