ansible_runner 包

子包

• ansible_runner.config 包
  • 子模块
    • ansible_runner.config.runner 模块
      • RunnerConfig
• ansible_runner.display_callback 包
  • 子模块
    • ansible_runner.display_callback.callback.awx_display 模块
      • AnsibleJSONEncoderLocal
        • AnsibleJSONEncoderLocal.default()
      • CallbackModule
        • CallbackModule.CALLBACK_NAME
        • CallbackModule.CALLBACK_TYPE
        • CallbackModule.CALLBACK_VERSION
        • CallbackModule.EVENTS_WITHOUT_PLAY
        • CallbackModule.EVENTS_WITHOUT_TASK
        • CallbackModule.capture_event_data()
        • CallbackModule.clear_play()
        • CallbackModule.clear_task()
        • CallbackModule.set_play()
        • CallbackModule.set_playbook()
        • CallbackModule.set_task()
        • CallbackModule.v2_on_file_diff()
        • CallbackModule.v2_playbook_on_cleanup_task_start()
        • CallbackModule.v2_playbook_on_handler_task_start()
        • CallbackModule.v2_playbook_on_import_for_host()
        • CallbackModule.v2_playbook_on_include()
        • CallbackModule.v2_playbook_on_no_hosts_matched()
        • CallbackModule.v2_playbook_on_no_hosts_remaining()
        • CallbackModule.v2_playbook_on_not_import_for_host()
        • CallbackModule.v2_playbook_on_notify()
        • CallbackModule.v2_playbook_on_play_start()
        • CallbackModule.v2_playbook_on_setup()
        • CallbackModule.v2_playbook_on_start()
        • CallbackModule.v2_playbook_on_stats()
        • CallbackModule.v2_playbook_on_task_start()
        • CallbackModule.v2_playbook_on_vars_prompt()
        • CallbackModule.v2_runner_item_on_failed()
        • CallbackModule.v2_runner_item_on_ok()
        • CallbackModule.v2_runner_item_on_skipped()
        • CallbackModule.v2_runner_on_async_failed()
        • CallbackModule.v2_runner_on_async_ok()
        • CallbackModule.v2_runner_on_async_poll()
        • CallbackModule.v2_runner_on_failed()
        • CallbackModule.v2_runner_on_file_diff()
        • CallbackModule.v2_runner_on_no_hosts()
        • CallbackModule.v2_runner_on_ok()
        • CallbackModule.v2_runner_on_skipped()
        • CallbackModule.v2_runner_on_start()
        • CallbackModule.v2_runner_on_unreachable()
        • CallbackModule.v2_runner_retry()
      • EventContext
        • EventContext.add_global()
        • EventContext.add_local()
        • EventContext.dump()
        • EventContext.dump_begin()
        • EventContext.dump_end()
        • EventContext.get()
        • EventContext.get_begin_dict()
        • EventContext.get_end_dict()
        • EventContext.get_global()
        • EventContext.get_local()
        • EventContext.remove_global()
        • EventContext.remove_local()
        • EventContext.set_global()
        • EventContext.set_local()
      • IsolatedFileWrite
        • IsolatedFileWrite.set()
      • current_time()
      • display_with_context()
      • with_context()
      • with_verbosity()
  • 模块内容

子模块

ansible_runner.exceptions 模块

exception ansible_runner.exceptions.AnsibleRunnerException

基类: Exception

通用 Runner 错误

exception ansible_runner.exceptions.CallbackError

基类: AnsibleRunnerException

回调中发生的异常

exception ansible_runner.exceptions.ConfigurationError

基类: AnsibleRunnerException

Runner 的错误配置

ansible_runner.interface 模块

ansible_runner.interface.get_ansible_config(action, config_file=None, only_changed=None, **kwargs)

运行 ansible-config 命令以获取与 Ansible 配置相关的详细信息。

参数:

• action (str) – 有效值之一：list、dump、view，list 返回所有配置选项，dump 返回活动配置，view 返回配置文件的视图。

• config_file (str) – 配置文件路径，默认为优先级中找到的第一个文件。

• only_changed (bool) – 当设置为 True 时，布尔值仅返回已从默认值更改的配置。 此参数仅在 action 设置为 dump 时适用。

• runner_mode (str) – 适用的值为 pexpect 和 subprocess。 默认设置为 subprocess。

• host_cwd (str) – 从中执行 executable_cmd 中的命令的当前工作目录。

• envvars (dict) – 运行 Ansible 时要使用的环境变量。 环境变量也将从 env/envvars（位于 private_data_dir 中）读取。

• passwords (dict) – 包含密码提示模式和响应值的字典，用于处理来自 Ansible 的输出。 密码也将从 env/passwords（位于 private_data_dir 中）读取。

• settings (dict) – 包含 ansible-runner 运行时环境的设置值的字典。 这些值也将从 env/settings（位于 private_data_dir 中）读取。

• ssh_key (str) – 传递给 ssh-agent 作为 ansible-playbook 运行的一部分的 SSH 私钥。

• quiet (bool) – 禁用所有输出

• json_mode (bool) – 在控制台和标准输出文件中将事件数据存储在标准输出的位置

• artifact_dir (str) – 存放工件的目录的路径，默认情况下为私有数据目录下的 ‘artifacts’

• project_dir (str) – 剧本内容的路径，默认情况下为私有数据目录下的 ‘project’

• rotate_artifacts (int) – 最多保留 n 个工件目录，禁用值为 0，这是默认值

• timeout (int) – 传递给 pexpect 或 subprocess 调用（基于选择的 runner_mode）时的超时值（以秒为单位）。 如果触发超时，它将强制取消执行。

• process_isolation (bool) – 启用进程隔离，使用容器引擎（例如 podman）。

• process_isolation_executable (str) – 用于隔离执行的进程隔离可执行文件或容器引擎。（默认值：podman）

• container_image (str) – 运行 Ansible 任务时使用的容器镜像

• container_volume_mounts (list) – 绑定挂载的列表，格式为 ‘host_dir:/container_dir:labels。（默认值：None）

• container_options (list) – 传递给执行引擎的容器选项列表。

• container_workdir (str) – 容器中的工作目录。

• fact_cache (str) – 将用作事实缓存中工件目录的子目录的名称的字符串。 此选项仅适用于 ‘jsonfile’ 类型的事实缓存。

• fact_cache_type (str) – 用于事实缓存的类型字符串。默认值为“jsonfile”。

• private_data_dir (str) – 包含所有调用运行器模块所需的运行器元数据的目录。输出工件也将存储在此处，以便稍后使用。

• ident (str) – 此次调用 Runner 的运行标识符。将用于创建和命名保存调用结果的工件目录。

• event_handler (Callable) – 可选的回调函数，将在 Runner 自身接收到事件时调用，返回 True 以保留事件

• cancel_callback (Callable) – 可选的回调函数，可以告知运行器取消（返回 True）或不取消（返回 False）

• finished_callback (Callable) – 可选的回调函数，将在进程清理后关闭时调用。

• status_handler (Callable) – 可选的回调函数，将在状态更改时调用（例如：启动、运行、失败、成功、超时）

• artifacts_handler (Callable) – 可选的回调函数，将在运行结束时调用，以处理运行中的工件。

• check_job_event_data (bool) – 检查作业事件数据是否完全生成。如果事件数据没有完全生成并且该值设置为“True”，它将引发“AnsibleRunnerException”异常，如果设置为“False”，它将记录调试消息并继续执行。默认值为“False”。

返回:

返回响应和错误字符串的元组。如果runner_mode设置为pexpect，则错误值为空，因为pexpect对 stdout 和 stderr 使用相同的输出描述符。

ansible_runner.interface.get_inventory(action, inventories, response_format=None, host=None, playbook_dir=None, vault_ids=None, vault_password_file=None, output_file=None, export=None, **kwargs)

运行 ansible-inventory 命令以获取与清单相关的详细信息。

参数:

• action (str) – 有效值为以下之一：graph、host、list。 graph 返回清单图。 host 返回特定主机的信息，并作为清单脚本工作。 list 返回所有主机的信息，也作为清单脚本工作。

• inventories (list) – 清单主机路径的列表。

• response_format (str) – 响应的输出格式。有效值可以是以下之一：json、yaml、toml。默认值为json。如果action为graph，则唯一允许的值为json。

• host (str) – 当action设置为host时，此参数用于获取主机特定信息。

• playbook_dir (str) – 此参数用于设置清单的相对路径。

• vault_ids (str) – 要使用的保管库标识。

• vault_password_file (str) – 要使用的保管库密码文件。

• output_file (str) – 清单详细信息应发送到的文件路径。

• export (bool) – 布尔值，如果设置，则表示以优化导出方式，而不是作为 Ansible 处理它的准确表示。

• runner_mode (str) – 适用的值为 pexpect 和 subprocess。 默认设置为 subprocess。

• host_cwd (str) – 要在容器中（如果已启用）挂载的主机当前工作目录，并且将是容器中的工作目录。

• envvars (dict) – 运行 Ansible 时要使用的环境变量。 环境变量也将从 env/envvars（位于 private_data_dir 中）读取。

• passwords (dict) – 包含密码提示模式和响应值的字典，用于处理来自 Ansible 的输出。 密码也将从 env/passwords（位于 private_data_dir 中）读取。

• settings (dict) – 包含 ansible-runner 运行时环境的设置值的字典。 这些值也将从 env/settings（位于 private_data_dir 中）读取。

• ssh_key (str) – 传递给 ssh-agent 作为 ansible-playbook 运行的一部分的 SSH 私钥。

• quiet (bool) – 禁用所有输出

• json_mode (bool) – 在控制台和标准输出文件中将事件数据存储在标准输出的位置

• artifact_dir (str) – 存放工件的目录的路径，默认情况下为私有数据目录下的 ‘artifacts’

• project_dir (str) – 剧本内容的路径，默认情况下为私有数据目录下的 ‘project’

• rotate_artifacts (int) – 最多保留 n 个工件目录，禁用值为 0，这是默认值

• timeout (int) – 传递给 pexpect 或 subprocess 调用（基于选择的 runner_mode）时的超时值（以秒为单位）。 如果触发超时，它将强制取消执行。

• process_isolation (bool) – 启用进程隔离，使用容器引擎（例如 podman）。

• process_isolation_executable (str) – 用于隔离执行的进程隔离可执行文件或容器引擎。（默认值：podman）

• container_image (str) – 运行 Ansible 任务时使用的容器镜像

• container_volume_mounts (list) – 绑定挂载的列表，格式为 ‘host_dir:/container_dir:labels。（默认值：None）

• container_options (list) – 传递给执行引擎的容器选项列表。

• container_workdir (str) – 容器中的工作目录。

• fact_cache (str) – 将用作事实缓存中工件目录的子目录的名称的字符串。 此选项仅适用于 ‘jsonfile’ 类型的事实缓存。

• fact_cache_type (str) – 用于事实缓存的类型字符串。默认值为“jsonfile”。

• private_data_dir (str) – 包含所有调用运行器模块所需的运行器元数据的目录。输出工件也将存储在此处，以便稍后使用。

• ident (str) – 此次调用 Runner 的运行标识符。将用于创建和命名保存调用结果的工件目录。

• event_handler (Callable) – 可选的回调函数，将在 Runner 自身接收到事件时调用，返回 True 以保留事件

• cancel_callback (Callable) – 可选的回调函数，可以告知运行器取消（返回 True）或不取消（返回 False）

• finished_callback (Callable) – 可选的回调函数，将在进程清理后关闭时调用。

• status_handler (Callable) – 可选的回调函数，将在状态更改时调用（例如：启动、运行、失败、成功、超时）

• artifacts_handler (Callable) – 可选的回调函数，将在运行结束时调用，以处理运行中的工件。

• check_job_event_data (bool) – 检查作业事件数据是否完全生成。如果事件数据没有完全生成并且该值设置为“True”，它将引发“AnsibleRunnerException”异常，如果设置为“False”，它将记录调试消息并继续执行。默认值为“False”。

返回:

返回响应和错误字符串的元组。如果runner_mode设置为pexpect，则错误值为空，因为pexpect对 stdout 和 stderr 使用相同的输出描述符。如果response_format的值为json，则返回 Python 字典对象。

ansible_runner.interface.get_plugin_docs(plugin_names, plugin_type=None, response_format=None, snippet=False, playbook_dir=None, module_path=None, **kwargs)

运行 ansible-doc 命令以在前景获取插件文档，并在完成后返回 Runner 对象。

参数:

• plugin_names (list) – 要获取文档的插件的名称。

• plugin_type (str) – plugins_names 中提到的插件的类型。有效值为become、cache、callback、cliconf、connection、httpapi、inventory、lookup、netconf、shell、vars、module、strategy。如果未提供该值，则默认为module。

• response_format (str) – 响应的输出格式。有效值可以是json或human，响应可以是 JSON 字符串，也可以是人类可读格式的纯文本。默认值为json。

• snippet (bool) – 显示指定插件的剧本片段。

• playbook_dir (str) – 此参数用于设置相对路径以处理剧本相邻的已安装插件。

• module_path (str) – 此参数将冒号分隔的路径（s）附加到模块库（默认值为~/.ansible/plugins/modules:/usr/share/ansible/plugins/modules）。

• runner_mode (str) – 适用的值为 pexpect 和 subprocess。 默认设置为 subprocess。

• host_cwd (str) – 要在容器中（如果已启用）挂载的主机当前工作目录，并且将是容器中的工作目录。

• envvars (dict) – 运行 Ansible 时要使用的环境变量。 环境变量也将从 env/envvars（位于 private_data_dir 中）读取。

• passwords (dict) – 包含密码提示模式和响应值的字典，用于处理来自 Ansible 的输出。 密码也将从 env/passwords（位于 private_data_dir 中）读取。

• settings (dict) – 包含 ansible-runner 运行时环境的设置值的字典。 这些值也将从 env/settings（位于 private_data_dir 中）读取。

• ssh_key (str) – 传递给 ssh-agent 作为 ansible-playbook 运行的一部分的 SSH 私钥。

• quiet (bool) – 禁用所有输出

• json_mode (bool) – 在控制台和标准输出文件中将事件数据存储在标准输出的位置

• artifact_dir (str) – 存放工件的目录的路径，默认情况下为私有数据目录下的 ‘artifacts’

• project_dir (str) – 剧本内容的路径，默认情况下为私有数据目录下的 ‘project’

• rotate_artifacts (int) – 最多保留 n 个工件目录，禁用值为 0，这是默认值

• timeout (int) – 传递给 pexpect 或 subprocess 调用（基于选择的 runner_mode）时的超时值（以秒为单位）。 如果触发超时，它将强制取消执行。

• process_isolation (bool) – 启用进程隔离，使用容器引擎（例如 podman）。

• process_isolation_executable (str) – 用于隔离执行的进程隔离可执行文件或容器引擎。（默认值：podman）

• container_image (str) – 运行 Ansible 任务时使用的容器镜像

• container_volume_mounts (list) – 绑定挂载的列表，格式为 ‘host_dir:/container_dir:labels。（默认值：None）

• container_options (list) – 传递给执行引擎的容器选项列表。

• container_workdir (str) – 容器中的工作目录。

• fact_cache (str) – 将用作事实缓存中工件目录的子目录的名称的字符串。 此选项仅适用于 ‘jsonfile’ 类型的事实缓存。

• fact_cache_type (str) – 用于事实缓存的类型字符串。默认值为“jsonfile”。

• private_data_dir (str) – 包含所有调用运行器模块所需的运行器元数据的目录。输出工件也将存储在此处，以便稍后使用。

• ident (str) – 此次调用 Runner 的运行标识符。将用于创建和命名保存调用结果的工件目录。

• event_handler (Callable) – 可选的回调函数，将在 Runner 自身接收到事件时调用，返回 True 以保留事件

• cancel_callback (Callable) – 可选的回调函数，可以告知运行器取消（返回 True）或不取消（返回 False）

• finished_callback (Callable) – 可选的回调函数，将在进程清理后关闭时调用。

• status_handler (Callable) – 可选的回调函数，将在状态更改时调用（例如：启动、运行、失败、成功、超时）

• artifacts_handler (Callable) – 可选的回调函数，将在运行结束时调用，以处理运行中的工件。

• check_job_event_data (bool) – 检查作业事件数据是否完全生成。如果事件数据没有完全生成并且该值设置为“True”，它将引发“AnsibleRunnerException”异常，如果设置为“False”，它将记录调试消息并继续执行。默认值为“False”。

返回:

返回响应和错误字符串的元组。如果runner_mode设置为pexpect，则错误值为空，因为pexpect对 stdout 和 stderr 使用相同的输出描述符。如果response_format的值为json，则返回 Python 字典对象。

ansible_runner.interface.get_plugin_docs_async(plugin_names, plugin_type=None, response_format=None, snippet=False, playbook_dir=None, module_path=None, **kwargs)

在后台运行 ansible-doc 命令，该命令将立即启动。返回线程对象和 Runner 对象。

此方法使用与 ansible_runner.interface.get_plugin_docs() 相同的参数。

返回:

包含 threading.Thread 对象和 ansible_runner.runner.Runner 对象的元组。

ansible_runner.interface.get_plugin_list(list_files=None, response_format=None, plugin_type=None, playbook_dir=None, module_path=None, **kwargs)

运行 ansible-doc 命令以获取已安装的 Ansible 插件列表。

参数:

• list_files (bool) – 如果此布尔参数设置为 True，则返回插件文件路径以及插件名称。

• response_format (str) – 响应的输出格式。有效值可以是json或human，响应可以是 JSON 字符串，也可以是人类可读格式的纯文本。默认值为json。

• plugin_type (str) – plugins_names 中提到的插件的类型。有效值为become、cache、callback、cliconf、connection、httpapi、inventory、lookup、netconf、shell、vars、module、strategy。如果未提供该值，则默认为module。

• playbook_dir (str) – 此参数用于设置相对路径以处理剧本相邻的已安装插件。

• module_path (str) – 此参数将冒号分隔的路径（s）附加到模块库（默认值为~/.ansible/plugins/modules:/usr/share/ansible/plugins/modules）。

• runner_mode (str) – 适用的值为 pexpect 和 subprocess。 默认设置为 subprocess。

• host_cwd (str) – 要在容器中（如果已启用）挂载的主机当前工作目录，并且将是容器中的工作目录。

• envvars (dict) – 运行 Ansible 时要使用的环境变量。 环境变量也将从 env/envvars（位于 private_data_dir 中）读取。

• passwords (dict) – 包含密码提示模式和响应值的字典，用于处理来自 Ansible 的输出。 密码也将从 env/passwords（位于 private_data_dir 中）读取。

• settings (dict) – 包含 ansible-runner 运行时环境的设置值的字典。 这些值也将从 env/settings（位于 private_data_dir 中）读取。

• ssh_key (str) – 传递给 ssh-agent 作为 ansible-playbook 运行的一部分的 SSH 私钥。

• quiet (bool) – 禁用所有输出

• json_mode (bool) – 在控制台和标准输出文件中将事件数据存储在标准输出的位置

• artifact_dir (str) – 存放工件的目录的路径，默认情况下为私有数据目录下的 ‘artifacts’

• project_dir (str) – 剧本内容的路径，默认情况下为私有数据目录下的 ‘project’

• rotate_artifacts (int) – 最多保留 n 个工件目录，禁用值为 0，这是默认值

• timeout (int) – 传递给 pexpect 或 subprocess 调用（基于选择的 runner_mode）时的超时值（以秒为单位）。 如果触发超时，它将强制取消执行。

• process_isolation (bool) – 启用进程隔离，使用容器引擎（例如 podman）。

• process_isolation_executable (str) – 用于隔离执行的进程隔离可执行文件或容器引擎。（默认值：podman）

• container_image (str) – 运行 Ansible 任务时使用的容器镜像

• container_volume_mounts (list) – 绑定挂载的列表，格式为 ‘host_dir:/container_dir:labels。（默认值：None）

• container_options (list) – 传递给执行引擎的容器选项列表。

• container_workdir (str) – 容器中的工作目录。

• fact_cache (str) – 将用作事实缓存中工件目录的子目录的名称的字符串。 此选项仅适用于 ‘jsonfile’ 类型的事实缓存。

• fact_cache_type (str) – 用于事实缓存的类型字符串。默认值为“jsonfile”。

• private_data_dir (str) – 包含所有调用运行器模块所需的运行器元数据的目录。输出工件也将存储在此处，以便稍后使用。

• ident (str) – 此次调用 Runner 的运行标识符。将用于创建和命名保存调用结果的工件目录。

• event_handler (Callable) – 可选的回调函数，将在 Runner 自身接收到事件时调用，返回 True 以保留事件

• cancel_callback (Callable) – 可选的回调函数，可以告知运行器取消（返回 True）或不取消（返回 False）

• finished_callback (Callable) – 可选的回调函数，将在进程清理后关闭时调用。

• status_handler (Callable) – 可选的回调函数，将在状态更改时调用（例如：启动、运行、失败、成功、超时）

• artifacts_handler (Callable) – 可选的回调函数，将在运行结束时调用，以处理运行中的工件。

• check_job_event_data (bool) – 检查作业事件数据是否完全生成。如果事件数据没有完全生成并且该值设置为“True”，它将引发“AnsibleRunnerException”异常，如果设置为“False”，它将记录调试消息并继续执行。默认值为“False”。

返回:

返回响应和错误字符串的元组。如果runner_mode设置为pexpect，则错误值为空，因为pexpect对 stdout 和 stderr 使用相同的输出描述符。如果response_format的值为json，则返回 Python 字典对象。

ansible_runner.interface.get_role_argspec(role, collection=None, playbook_dir=None, **kwargs)

运行 ansible-doc 命令以获取角色参数规范。

注意

添加版本：2.2

参数:

• role (str) – 要查询的简单角色名称或完全限定的集合角色名称。

• collection (str) – 如果指定，将与角色名称组合以形成完全限定的集合角色名称。如果提供此参数，则 role 参数不应是完全限定的。

• playbook_dir (str) – 此参数用于设置相对路径以处理剧本相邻安装的角色。

• runner_mode (str) – 适用的值为 pexpect 和 subprocess。 默认设置为 subprocess。

• host_cwd (str) – 要在容器中（如果已启用）挂载的主机当前工作目录，并且将是容器中的工作目录。

• envvars (dict) – 运行 Ansible 时要使用的环境变量。 环境变量也将从 env/envvars（位于 private_data_dir 中）读取。

• passwords (dict) – 包含密码提示模式和响应值的字典，用于处理来自 Ansible 的输出。 密码也将从 env/passwords（位于 private_data_dir 中）读取。

• settings (dict) – 包含 ansible-runner 运行时环境的设置值的字典。 这些值也将从 env/settings（位于 private_data_dir 中）读取。

• ssh_key (str) – 传递给 ssh-agent 作为 ansible-playbook 运行的一部分的 SSH 私钥。

• quiet (bool) – 禁用所有输出

• json_mode (bool) – 在控制台和标准输出文件中将事件数据存储在标准输出的位置

• artifact_dir (str) – 存放工件的目录的路径，默认情况下为私有数据目录下的 ‘artifacts’

• project_dir (str) – 剧本内容的路径，默认情况下为私有数据目录下的 ‘project’

• rotate_artifacts (int) – 最多保留 n 个工件目录，禁用值为 0，这是默认值

• timeout (int) – 将传递给 pexpect 或 subprocess 调用（基于所选的 runner_mode）的超时值（以秒为单位），在执行命令时。如果触发超时，它将强制取消执行。

• process_isolation (bool) – 使用容器引擎（如 podman）启用进程隔离。

• process_isolation_executable (str) – 用于隔离执行的进程隔离可执行文件或容器引擎。（默认值：podman）

• container_image (str) – 在运行 Ansible 任务时要使用的容器映像。

• container_volume_mounts (list) – 绑定挂载列表，形式为 host_dir:/container_dir:labels。 （默认值：None）

• container_options (list) – 传递给执行引擎的容器选项列表。

• container_workdir (str) – 容器中的工作目录。

• fact_cache (str) – 将用作事实缓存中工件目录的子目录的名称的字符串。 此选项仅适用于 ‘jsonfile’ 类型的事实缓存。

• fact_cache_type (str) – 用于事实缓存的类型字符串。默认值为“jsonfile”。

• private_data_dir (str) – 包含所有调用运行器模块所需的运行器元数据的目录。输出工件也将存储在此处，以便稍后使用。

• ident (str) – 此次调用 Runner 的运行标识符。将用于创建和命名保存调用结果的工件目录。

• event_handler (Callable) – 可选的回调函数，将在 Runner 自身接收到事件时调用，返回 True 以保留事件

• cancel_callback (Callable) – 可选的回调函数，可以告知运行器取消（返回 True）或不取消（返回 False）

• finished_callback (Callable) – 可选的回调函数，将在进程清理后关闭时调用。

• status_handler (Callable) – 一个可选的回调函数，它将在状态发生任何更改时被调用（例如：已启动、正在运行、失败、成功、超时）。

• artifacts_handler (Callable) – 可选的回调函数，将在运行结束时调用，以处理运行中的工件。

• check_job_event_data (bool) – 检查作业事件数据是否已完全生成。如果事件数据未完全生成，并且该值设置为“True”，则将引发“AnsibleRunnerException”异常。如果设置为“False”，则记录调试消息并继续执行。默认值为“False”。

返回:

响应和错误字符串的元组。响应是一个字典对象（如 ansible-doc JSON 输出返回的），包含找到的每个角色，或者如果未找到任何角色，则为空字典。

ansible_runner.interface.get_role_list(collection=None, playbook_dir=None, **kwargs)

运行 ansible-doc 命令以获取已安装的集合角色列表。

仅返回定义了参数规范的角色。

注意

添加版本：2.2

参数:

• collection (str) – 用于筛选结果的完全限定的集合名称。

• playbook_dir (str) – 此参数用于设置相对路径以处理剧本相邻安装的角色。

• runner_mode (str) – 适用的值为 pexpect 和 subprocess。 默认设置为 subprocess。

• host_cwd (str) – 要在容器中（如果已启用）挂载的主机当前工作目录，并且将是容器中的工作目录。

• envvars (dict) – 运行 Ansible 时要使用的环境变量。 环境变量也将从 env/envvars（位于 private_data_dir 中）读取。

• passwords (dict) – 包含密码提示模式和响应值的字典，用于处理来自 Ansible 的输出。 密码也将从 env/passwords（位于 private_data_dir 中）读取。

• settings (dict) – 包含 ansible-runner 运行时环境的设置值的字典。 这些值也将从 env/settings（位于 private_data_dir 中）读取。

• ssh_key (str) – 传递给 ssh-agent 作为 ansible-playbook 运行的一部分的 SSH 私钥。

• quiet (bool) – 禁用所有输出

• json_mode (bool) – 在控制台和标准输出文件中将事件数据存储在标准输出的位置

• artifact_dir (str) – 存放工件的目录的路径，默认情况下为私有数据目录下的 ‘artifacts’

• project_dir (str) – 剧本内容的路径，默认情况下为私有数据目录下的 ‘project’

• rotate_artifacts (int) – 最多保留 n 个工件目录，禁用值为 0，这是默认值

• timeout (int) – 将传递给 pexpect 或 subprocess 调用（基于所选的 runner_mode）的超时值（以秒为单位），在执行命令时。如果触发超时，它将强制取消执行。

• process_isolation (bool) – 使用容器引擎（如 podman）启用进程隔离。

• process_isolation_executable (str) – 用于隔离执行的进程隔离可执行文件或容器引擎。（默认值：podman）

• container_image (str) – 在运行 Ansible 任务时要使用的容器映像。

• container_volume_mounts (list) – 绑定挂载列表，形式为 host_dir:/container_dir:labels。 （默认值：None）

• container_options (list) – 传递给执行引擎的容器选项列表。

• container_workdir (str) – 容器中的工作目录。

• fact_cache (str) – 将用作事实缓存中工件目录的子目录的名称的字符串。 此选项仅适用于 ‘jsonfile’ 类型的事实缓存。

• fact_cache_type (str) – 用于事实缓存的类型字符串。默认值为“jsonfile”。

• private_data_dir (str) – 包含所有调用运行器模块所需的运行器元数据的目录。输出工件也将存储在此处，以便稍后使用。

• ident (str) – 此次调用 Runner 的运行标识符。将用于创建和命名保存调用结果的工件目录。

• event_handler (Callable) – 可选的回调函数，将在 Runner 自身接收到事件时调用，返回 True 以保留事件

• cancel_callback (Callable) – 可选的回调函数，可以告知运行器取消（返回 True）或不取消（返回 False）

• finished_callback (Callable) – 可选的回调函数，将在进程清理后关闭时调用。

• status_handler (Callable) – 一个可选的回调函数，它将在状态发生任何更改时被调用（例如：已启动、正在运行、失败、成功、超时）。

• artifacts_handler (Callable) – 可选的回调函数，将在运行结束时调用，以处理运行中的工件。

• check_job_event_data (bool) – 检查作业事件数据是否已完全生成。如果事件数据未完全生成，并且该值设置为“True”，则将引发“AnsibleRunnerException”异常。如果设置为“False”，则记录调试消息并继续执行。默认值为“False”。

返回:

响应和错误字符串的元组。响应是一个字典对象（如 ansible-doc JSON 输出返回的），包含找到的每个角色，或者如果未找到任何角色，则为空字典。

ansible_runner.interface.init_command_config(executable_cmd, cmdline_args=None, **kwargs)

初始化 Runner() 实例。

此函数将以相同的方式正确初始化 run_command() 和 run_command_async() 函数，并返回 Runner 的值实例。

请参阅传递给 ansible_runner.interface.run_command() 的参数。

ansible_runner.interface.init_plugin_docs_config(plugin_names, plugin_type=None, response_format=None, snippet=False, playbook_dir=None, module_path=None, **kwargs)

初始化 Runner() 实例。

此函数将以相同的方式正确初始化 get_plugin_docs() 和 get_plugin_docs_async() 函数，并返回 Runner 的值实例。

请参阅传递给 ansible_runner.interface.get_plugin_docs() 的参数。

ansible_runner.interface.init_runner(**kwargs)

初始化 Runner() 实例。

此函数将以相同的方式正确初始化 run() 和 run_async() 函数，并返回 Runner 的值实例。

请参阅传递给 ansible_runner.interface.run() 的参数。

ansible_runner.interface.run(**kwargs)

在前景运行 Ansible Runner 任务，并在完成时返回 Runner 对象。

参数:

• private_data_dir (str) – 包含所有调用运行器模块所需的运行器元数据的目录。输出工件也将存储在此处，以便稍后使用。

• ident (str) – 此次调用 Runner 的运行标识符。将用于创建和命名保存调用结果的工件目录。

• json_mode (bool) – 在控制台和标准输出文件中将事件数据存储在标准输出的位置

• playbook (str or list) – 剧本（可以是剧本的列表或字典，也可以是相对于 private_data_dir/project 的路径），将在运行 Ansible 时由 runner 调用。

• module (str) – 将在 ad-hoc 模式下由 runner 调用，在运行 Ansible 时。

• module_args (str) – 将传递给临时模式的模块参数。

• host_pattern (str) – 在临时模式下运行时匹配的主机模式。

• inventory (str 或 dict 或 list) –

  使用特定主机或主机列表覆盖清单目录/文件（在 private_data_dir/inventory 中提供）。它可以采用以下形式：

  • private_data_dir/inventory 目录中清单文件的路径或清单文件的绝对路径

  • 支持 YAML/json 清单结构的原生 Python 字典

  • 文本 INI 格式的字符串

  • 清单源的列表，或空列表以禁用传递清单

• role (str) – 要执行的角色名称。

• roles_path (dict 或 list) – 分配给 ANSIBLE_ROLES_PATH 的目录或目录列表

• envvars (dict) – 运行 Ansible 时要使用的环境变量。 环境变量也将从 env/envvars（位于 private_data_dir 中）读取。

• extravars (dict) – 使用 -e 在运行时传递给 Ansible 的额外变量。额外的变量也将从 private_data_dir 中的 env/extravars 中读取。

• passwords (dict) – 包含密码提示模式和响应值的字典，用于处理来自 Ansible 的输出。 密码也将从 env/passwords（位于 private_data_dir 中）读取。

• settings (dict) – 包含 ansible-runner 运行时环境的设置值的字典。 这些值也将从 env/settings（位于 private_data_dir 中）读取。

• ssh_key (str) – 传递给 ssh-agent 作为 ansible-playbook 运行的一部分的 SSH 私钥。

• cmdline (str) – 从 private_data_dir 中的 env/cmdline 中读取的传递给 Ansible 的命令行选项

• suppress_env_files (bool) – 禁用将文件写入 env，该文件可能存储敏感信息

• limit (str) – 匹配 ansible 的 --limit 参数，以进一步限制要使用的清单

• forks (int) – 控制 Ansible 并行并发

• verbosity (int) – 控制 ansible-playbook 输出的详细程度

• quiet (bool) – 禁用所有输出

• artifact_dir (str) – 存放工件的目录的路径，默认情况下为私有数据目录下的 ‘artifacts’

• project_dir (str) – 剧本内容的路径，默认情况下为私有数据目录下的 ‘project’

• rotate_artifacts (int) – 最多保留 n 个工件目录，禁用值为 0，这是默认值

• timeout (int) – 传递给 pexpect 或 subprocess 调用（基于选择的 runner_mode）时的超时值（以秒为单位）。 如果触发超时，它将强制取消执行。

• streamer (str) – 可选地将 ansible-runner 作为流式管道中的步骤之一调用

• _input (io.FileIO) – 在流式管道中用作输入的可选文件或类似文件对象

• _output (io.FileIO) – 在流式管道中用作输出的可选文件或类似文件对象

• event_handler (Callable) – 可选的回调函数，将在 Runner 自身接收到事件时调用，返回 True 以保留事件

• cancel_callback (Callable) – 可选的回调函数，可以告知运行器取消（返回 True）或不取消（返回 False）

• finished_callback (Callable) – 可选的回调函数，将在进程清理后关闭时调用。

• status_handler (Callable) – 可选的回调函数，将在状态更改时调用（例如：启动、运行、失败、成功、超时）

• artifacts_handler (Callable) – 可选的回调函数，将在运行结束时调用，以处理运行中的工件。

• process_isolation (bool) – 启用进程隔离，使用容器引擎（例如 podman）或沙箱（例如 bwrap）。

• process_isolation_executable (str) – 用于隔离执行的进程隔离可执行文件或容器引擎。（默认值：podman）

• process_isolation_path (str) – 隔离的剧本运行将用于暂存的路径。（默认：/tmp）

• process_isolation_hide_paths (str 或 list) – 系统上应该从剧本运行中隐藏的路径或路径列表。

• process_isolation_show_paths (str 或 list) – 系统上应该暴露给剧本运行的路径或路径列表。

• process_isolation_ro_paths (str 或 list) – 系统上应该暴露给剧本运行的路径或路径列表，作为只读。

• container_image (str) – 运行 Ansible 任务时使用的容器镜像

• container_volume_mounts (list) – 以 ‘host_dir:/container_dir’ 形式的绑定挂载列表。（默认：无）

• container_options (list) – 传递给执行引擎的容器选项列表。

• directory_isolation_base_path (str) – 可选路径将用作创建临时目录的基路径，项目内容将被复制到此位置，然后将用作剧本执行期间的工作目录。

• fact_cache (str) – 将用作事实缓存中工件目录的子目录的名称的字符串。 此选项仅适用于 ‘jsonfile’ 类型的事实缓存。

• fact_cache_type (str) – 用于事实缓存的类型字符串。默认值为“jsonfile”。

• omit_event_data (bool) – 从事件有效负载中省略额外的 Ansible 事件数据（stdout 和事件仍然包含在内）

• only_failed_event_data (bool) – 除非是失败的事件，否则省略额外的 Ansible 事件数据（stdout 和事件仍然包含在内）

• check_job_event_data (bool) – 检查作业事件数据是否完全生成。如果事件数据没有完全生成并且该值设置为“True”，它将引发“AnsibleRunnerException”异常，如果设置为“False”，它将记录调试消息并继续执行。默认值为“False”。

返回:

一个 ansible_runner.runner.Runner 对象，或者一个包含 rc 的简单对象（如果远程运行）

ansible_runner.interface.run_async(**kwargs)

在后台运行 Ansible Runner 任务，该任务将立即启动。返回线程对象和 Runner 对象。

这使用与 ansible_runner.interface.run() 相同的参数

返回:

包含 threading.Thread 对象和 ansible_runner.runner.Runner 对象的元组。

ansible_runner.interface.run_command(executable_cmd, cmdline_args=None, **kwargs)

在前景中运行（Ansible）命令，并在完成时返回 Runner 对象。

参数:

• executable_cmd (str) – 要执行的命令。

• cmdline_args (list) – 要传递给可执行命令的参数列表。

• input_fd (int) – 此参数适用于 runner_mode 设置为 subprocess 的情况，它提供与运行命令的子进程交互的输入文件描述符。

• output_fd (int) – 要流式传输命令执行输出的输出文件描述符。

• error_fd (int) – 此参数适用于 runner_mode 设置为 subprocess 的情况，它提供错误文件描述符以读取执行命令时收到的错误。

• runner_mode (str) – 可用值为 pexpect 和 subprocess。如果 input_fd 参数的值已设置或可执行命令是 ansible-config、ansible-doc 或 ansible-galaxy 之一，则默认值设置为 subprocess，否则在其他情况下设置为 pexpect。

• host_cwd (str) – 要在容器中（如果已启用）挂载的主机当前工作目录，并且将是容器中的工作目录。

• envvars (dict) – 运行 Ansible 时要使用的环境变量。 环境变量也将从 env/envvars（位于 private_data_dir 中）读取。

• passwords (dict) – 包含密码提示模式和响应值的字典，用于处理来自 Ansible 的输出。 密码也将从 env/passwords（位于 private_data_dir 中）读取。

• settings (dict) – 包含 ansible-runner 运行时环境的设置值的字典。 这些值也将从 env/settings（位于 private_data_dir 中）读取。

• ssh_key (str) – 传递给 ssh-agent 作为 ansible-playbook 运行的一部分的 SSH 私钥。

• quiet (bool) – 禁用所有输出

• json_mode (bool) – 在控制台和标准输出文件中将事件数据存储在标准输出的位置

• artifact_dir (str) – 存放工件的目录的路径，默认情况下为私有数据目录下的 ‘artifacts’

• project_dir (str) – 剧本内容的路径，默认情况下为私有数据目录下的 ‘project’

• rotate_artifacts (int) – 最多保留 n 个工件目录，禁用值为 0，这是默认值

• timeout (int) – 传递给 pexpect 或 subprocess 调用（基于选择的 runner_mode）时的超时值（以秒为单位）。 如果触发超时，它将强制取消执行。

• process_isolation (bool) – 启用进程隔离，使用容器引擎（例如 podman）。

• process_isolation_executable (str) – 用于隔离执行的进程隔离可执行文件或容器引擎。（默认值：podman）

• container_image (str) – 运行 Ansible 任务时使用的容器镜像

• container_volume_mounts (list) – 绑定挂载的列表，格式为 ‘host_dir:/container_dir:labels。（默认值：None）

• container_options (list) – 传递给执行引擎的容器选项列表。

• container_workdir (str) – 容器中的工作目录。

• fact_cache (str) – 将用作事实缓存中工件目录的子目录的名称的字符串。 此选项仅适用于 ‘jsonfile’ 类型的事实缓存。

• fact_cache_type (str) – 用于事实缓存的类型字符串。默认值为“jsonfile”。

• private_data_dir (str) – 包含所有调用运行器模块所需的运行器元数据的目录。输出工件也将存储在此处，以便稍后使用。

• ident (str) – 此次调用 Runner 的运行标识符。将用于创建和命名保存调用结果的工件目录。

• event_handler (Callable) – 可选的回调函数，将在 Runner 自身接收到事件时调用，返回 True 以保留事件

• cancel_callback (Callable) – 可选的回调函数，可以告知运行器取消（返回 True）或不取消（返回 False）

• finished_callback (Callable) – 可选的回调函数，将在进程清理后关闭时调用。

• status_handler (Callable) – 可选的回调函数，将在状态更改时调用（例如：启动、运行、失败、成功、超时）

• artifacts_handler (Callable) – 可选的回调函数，将在运行结束时调用，以处理运行中的工件。

• check_job_event_data (bool) – 检查作业事件数据是否完全生成。如果事件数据没有完全生成并且该值设置为“True”，它将引发“AnsibleRunnerException”异常，如果设置为“False”，它将记录调试消息并继续执行。默认值为“False”。

返回:

返回响应、错误字符串和返回代码的元组。如果 runner_mode 设置为 pexpect，则错误值为空，因为 pexpect 对 stdout 和 stderr 使用相同的输出描述符。

ansible_runner.interface.run_command_async(executable_cmd, cmdline_args=None, **kwargs)

在后台运行（Ansible）命令，该命令将立即启动。返回线程对象和 Runner 对象。

这使用与 ansible_runner.interface.run_command() 相同的参数

返回:

包含 threading.Thread 对象和 ansible_runner.runner.Runner 对象的元组。

ansible_runner.loader 模块

class ansible_runner.loader.ArtifactLoader(base_path: str)

Bases: object

处理从磁盘加载和缓存文件内容

此类将加载文件内容，并尝试将内容反序列化为 JSON 或 YAML。如果文件内容无法反序列化，则内容将作为字符串返回给调用者。

反序列化的文件内容将作为缓存对象存储在实例中，以避免对相同文件的后续调用进行任何额外的磁盘读取。

abspath(path: str) → str

将路径转换为绝对路径

参数:

path (str) – 要转换为绝对路径的路径

返回:

文件的绝对路径。

isfile(path: str) → bool

检查路径是否为文件

参数:

path (str) – 要检查的文件的路径。如果路径是相对路径，它将扩展为绝对路径

返回:

如果路径是文件，则为 True，否则为 False。

load_file(path: str, objtype: Any | None = None, encoding='utf-8') → bytes | str | dict | None

加载由 path 指定的文件

此方法将首先尝试从缓存中加载文件内容，如果发生缓存未命中，它将从磁盘中加载内容

参数:

• path (str) – 要加载文件的完整路径或相对路径。

• objtype (Any) – 文件内容的对象类型。这用于将反序列化的内容与从磁盘加载的内容进行类型检查。如果 objtype 为 str，则忽略序列化。仅支持 Mapping 或 str 类型。

• encoding (str) – 文件内容文本编码。

返回:

反序列化的文件内容，可以是字符串对象或字典对象

引发:

在文件加载或反序列化期间出错时出现 ConfigurationError。

ansible_runner.runner 模块

class ansible_runner.runner.Runner(config, cancel_callback=None, remove_partials=True, event_handler=None, artifacts_handler=None, finished_callback=None, status_handler=None)

Bases: object

event_callback(event_data)

针对每个 Ansible 事件调用，以收集带有事件数据的标准输出并将其存储以供将来使用

property events

一个生成器，将按照它们从 Ansible 发出的顺序返回所有 Ansible 作业事件

示例:

 {
    "event": "runner_on_ok",
    "uuid": "00a50d9c-161a-4b74-b978-9f60becaf209",
    "stdout": "ok: [localhost] => {\r\n    \"   msg\":\"Test!\"\r\n}",
    "counter": 6,
    "pid": 740,
    "created": "2018-04-05T18:24:36.096725",
    "end_line": 10,
    "start_line": 7,
    "event_data": {
       "play_pattern": "all",
       "play": "all",
       "task": "debug",
       "task_args": "msg=Test!",
       "remote_addr": "localhost",
       "res": {
          "msg": "Test!",
          "changed": false,
          "_ansible_verbose_always": true,
          "_ansible_no_log": false
       },
       "pid": 740,
       "play_uuid": "0242ac11-0002-443b-cdb1-000000000006",
       "task_uuid": "0242ac11-0002-443b-cdb1-000000000008",
       "event_loop": null,
       "playbook_uuid": "634edeee-3228-4c17-a1b4-f010fdd42eb2",
       "playbook": "test.yml",
       "task_action": "debug",
       "host": "localhost",
       "task_path": "/tmp/demo/project/test.yml:3"
    }
}

get_fact_cache(host)

仅当 fact_cache_type 为 ‘jsonfile’ 时，才获取整个 fact 缓存

classmethod handle_termination(pid, pidfile=None)

用于终止由 pexpect 生成的代表运行程序调用的子进程的内部方法。

参数:

• pid – 正在运行作业的进程 ID。

• pidfile – 守护进程的 PID 文件

host_events(host)

给定一个主机名，这将返回在该主机上执行的所有任务事件

kill_container()

用于终止用于作业隔离的容器的内部方法

run()

启动 self.config（一个 RunnerConfig 对象）中配置的 Ansible 任务，在调用完成时返回

set_fact_cache(host, data)

仅当 fact_cache_type 为 ‘jsonfile’ 时，才设置整个 fact 缓存数据

property stats

返回 Ansible 运行的最终高级别统计信息

示例

{‘dark’: {}, ‘failures’: {}, ‘skipped’: {}, ‘ok’: {u’localhost’: 2}, ‘processed’: {u’localhost’: 1}}

status_callback(status)

property stderr

返回代表 Ansible 运行的标准错误的打开文件句柄

property stdout

返回代表 Ansible 运行的标准输出的打开文件句柄

ansible_runner.runner_config 模块

ansible_runner.utils 模块

class ansible_runner.utils.Bunch(**kwargs)

Bases: object

在一个对象中收集一堆变量。这只是对 Alex Martelli 和 Doug Hudgeon 的 Bunch 模式的一点修改。

get(key)

update(**kwargs)

class ansible_runner.utils.OutputEventFilter(handle: StreamReaderWriter, event_callback: Callable[[dict], None], suppress_ansible_output: bool = False, output_json: bool = False)

Bases: object

从标准输出数据中查找编码的作业事件的类文件对象。

EVENT_DATA_RE = re.compile('\\x1b\\[K((?:[A-Za-z0-9+/=]+\\x1b\\[\\d+D)+)\\x1b\\[K')

close() → None

flush() → None

write(data: str) → None

ansible_runner.utils.args2cmdline(*args)

ansible_runner.utils.check_isolation_executable_installed(isolation_executable: str) → bool

检查进程隔离可执行文件是否已安装。

参数:

isolation_executable (str) – 可执行文件名称（例如 podman、docker、bwrap）。

返回:

如果可执行文件已安装，则为 True，否则为 False。

ansible_runner.utils.cleanup_artifact_dir(path: str, num_keep: int = 0) → None

ansible_runner.utils.cleanup_folder(folder: str) → bool

删除文件夹，根据是否发生了更改返回 True 或 False。

ansible_runner.utils.cli_mounts()

ansible_runner.utils.collect_new_events(event_path: str, old_events: dict) → Iterator[tuple[dict, dict]]

为“events”生成器属性收集新事件

ansible_runner.utils.dump_artifact(obj: str, path: str, filename: str | None = None) → str

将工件写入指定路径的磁盘。

参数:

• obj (str) – 要在指定路径的磁盘中转储的字符串对象。工件文件名将自动创建。

• path (str) – 工件数据目录的完整路径。

• filename (str) – 要将工件写入的文件名。如果没有提供文件名，则会生成一个文件名。

返回:

生成的工件的完整路径文件名。

ansible_runner.utils.dump_artifacts(kwargs: dict) → None

内省 kwargs 并将对象转储到磁盘

ansible_runner.utils.ensure_str(s: Any, encoding='utf-8', errors='strict') → str

将 s 强制转换为 str。

• str -> str

• bytes -> 解码为 str

ansible_runner.utils.get_callback_dir() → str

ansible_runner.utils.get_executable_path(name: str) → str

ansible_runner.utils.get_plugin_dir() → str

ansible_runner.utils.is_dir_owner(directory: str) → bool

如果当前用户是目录的所有者，则返回 True

ansible_runner.utils.isinventory(obj: Any) → bool

检查对象并返回它是否是清单

参数:

obj (Any) – 要由此函数检查的对象。

返回:

如果对象是清单字典，则为 True，否则为 False。

ansible_runner.utils.isplaybook(obj: Any) → bool

检查对象并返回它是否是剧本

参数:

obj (Any) – 要由此函数检查的对象。

返回:

如果对象是列表，则为 True，否则为 False。

ansible_runner.utils.open_fifo_write(path: str, data: str | bytes) → None

在新的线程中打开名为 pipe 的 fifo。

这会阻塞线程，直到外部进程（例如 ssh-agent）从管道中读取数据。

ansible_runner.utils.register_for_cleanup(folder: str) → None

提供文件夹的路径以确保在执行完成时将其删除。该文件夹在调用此函数时不需要存在。

ansible_runner.utils.sanitize_container_name(original_name: str) → str

Docker 和 podman 仅接受容器名称中的某些字符。这将从用户指定的 value 中获取给定的名称，并替换无效字符，以便它可以用于 docker/podman CLI 命令

参数:

original_name (str) – 容器名称，可能包含无效字符

ansible_runner.utils.sanitize_json_response(data: str) → str

从 Ansible 命令行实用程序发出的响应消息中删除警告消息。

参数:

data (str) – 要清理的字符串数据

ansible_runner.utils.signal_handler() → Callable[[], bool] | None