f5networks.f5_modules.bigip_command 模块 – 在 F5 设备上运行 TMSH 和 BASH 命令

注意

此模块是 f5networks.f5_modules 集合（版本 1.32.1）的一部分。

如果您使用的是 ansible 包，则可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install f5networks.f5_modules。

要在 playbook 中使用它，请指定：f5networks.f5_modules.bigip_command。

f5networks.f5_modules 1.0.0 中的新增功能

概要 

将 TMSH 或 BASH 命令发送到 BIG-IP 节点并返回从设备读取的结果。此模块包含一个参数，该参数将导致模块在返回之前等待特定条件，或者如果未满足条件则超时。
此模块**不是**幂等的，将来也不会是。它旨在作为权宜之计，以满足自动化需求，直到开发出真正满足您需求的模块为止。
如果您正在使用此模块，我们建议您也提交一个问题，以便为您的需求创建一个**真正的**模块。

参数 

参数	注释
chdir 字符串	运行命令之前更改到此目录。
commands 任意类型 / 必需	通过配置的提供程序发送到远程 BIG-IP 设备的命令。返回命令的输出结果。如果提供了wait_for参数，则在满足条件或重试次数过期之前，模块不会返回。仅支持`tmsh`命令。如果您正在使用管道或添加超出`tmsh`范围的其他逻辑（例如 grep、awk 或其他与 shell 相关的逻辑，这些逻辑不是`tmsh`），则不支持此行为。
interval 整数	配置以秒为单位的间隔，用于在命令重试之间等待。如果命令未通过指定的条件，则间隔表示在再次尝试命令之前要等待多长时间。默认值： `1`
match 字符串	match参数与wait_for参数一起使用，用于指定匹配策略。有效值为`all`或`any`。如果值为`all`，则必须满足wait_for中的所有条件。如果值为`any`，则只需要满足其中一个条件即可。选项 `"any"` `"all"` ← (默认)
provider 字典 f5networks.f5_modules 1.0.0 中新增	包含连接详细信息的字典对象。
auth_provider 字符串	配置身份验证提供程序，以从远程设备获取身份验证令牌。此选项在使用 BIG-IQ 设备时非常有用。
no_f5_teem 布尔值	如果为`yes`，则不会将 TEEM 遥测数据发送到 F5。您可以通过设置环境变量`F5_TELEMETRY_OFF`来省略此选项。以前使用的变量`F5_TEEM`已弃用，因为其名称令人困惑。选项 `false` ← (默认) `true`
password 别名：pass，pwd 字符串 / 必需	用于连接到 BIG-IP 的用户帐户的密码。您可以通过设置环境变量`F5_PASSWORD`来省略此选项。
server 字符串 / 必需	BIG-IP 主机。您可以通过设置环境变量`F5_SERVER`来省略此选项。
server_port 整数	BIG-IP 服务器端口。您可以通过设置环境变量`F5_SERVER_PORT`来省略此选项。默认值： `443`
ssh_keyfile 路径	指定用于验证与远程设备连接的 SSH 密钥文件。此参数仅用于cli传输。可以通过设置环境变量`ANSIBLE_NET_SSH_KEYFILE`来省略此选项。
超时时间整数	当`transport`设置为`rest`时生效的参数指定与网络设备通信的超时时间（秒），包括连接和发送命令。如果在操作完成之前超时，模块将报错。
传输方式字符串	配置连接到远程设备时使用的传输连接。选项 `"cli"` `"rest"` ← (默认)
用户名字符串 / 必需	连接到BIG-IP的用户名。此用户必须具有设备上的管理员权限。可以通过设置环境变量`F5_USER`来省略此选项。
验证证书布尔值	如果设置为`no`，则不验证SSL证书。仅在使用自签名证书的个人控制站点上使用此选项。可以通过设置环境变量`F5_VALIDATE_CERTS`来省略此选项。选项 `false` `true` ← (默认)
重试次数整数	指定在命令被认为失败之前应尝试的重试次数。命令在每次重试时都在目标设备上运行，并根据wait_for条件进行评估。默认值： `10`
等待条件别名：waitfor 列表 / 元素=字符串	指定要从命令输出中评估的内容以及要应用的条件。此参数将导致任务等待特定条件变为 true 后再继续执行。如果在配置的重试次数内条件不为 true，则任务失败。请参阅示例。
警告布尔值	模块是否应引发与命令幂等性相关的警告。请注意，F5 Ansible 开发人员专门保留此选项，以提醒您，您对该模块的使用可能最好使用官方的 F5 Ansible 模块。此模块应始终作为最后手段使用。选项 `false` `true` ← (默认)

备注 

注意

在 HA 环境中通过 SSH 连接运行此模块并使用除admin或root以外的角色时，即使您没有进行任何更改，也可能会看到Change Pending状态。这个问题正在跟踪中，ID 为 429869。
使用 bigip_command 模块和 REST API 时，内部使用正则表达式转义引号等字符的地方有很多。如果您的 TMSH 命令本身包含正则表达式字符，例如 datagroup 通配符*，则可能需要大量转义字符。
发出长时间运行的命令时，必须为提供程序块中的超时选项提供足够大的值。
有关使用 Ansible 管理 F5 网络设备的更多信息，请参见 https://ansible.org.cn/integrations/networks/f5。
需要 BIG-IP 软件版本 >= 12。
要在transport设置为cli时指定timeout，请使用ANSIBLE_PERSISTENT_COMMAND_TIMEOUT环境变量，或在 ansible.cfg 文件中指定command_timeout，请参见 https://docs.ansible.org.cn/ansible/latest/reference_appendices/config.html#persistent-command-timeout
F5 模块仅操作 F5 产品的运行配置。要确保 BIG-IP 特定配置持久保存到磁盘，请务必包含至少一项使用f5networks.f5_modules.bigip_config模块保存运行配置的任务。请参阅模块的文档，了解保存运行配置的正确使用方法。

示例 

- name: run show version on remote devices
  bigip_command:
    commands: show sys version
    provider:
      server: lb.mydomain.com
      password: secret
      user: admin
  delegate_to: localhost

- name: sleep for 200 seconds
  bigip_command:
    commands: 'run /util bash -c "sleep 200"'
    provider:
      server: lb.mydomain.com
      password: secret
      user: admin
      timeout: 210
  delegate_to: localhost

- name: run show version and check to see if output contains BIG-IP
  bigip_command:
    commands: show sys version
    wait_for: result[0] contains BIG-IP
    provider:
      server: lb.mydomain.com
      password: secret
      user: admin
  register: result
  delegate_to: localhost

- name: run multiple commands on remote nodes
  bigip_command:
    commands:
      - show sys version
      - list ltm virtual
    provider:
      server: lb.mydomain.com
      password: secret
      user: admin
  delegate_to: localhost

- name: run multiple commands and evaluate the output
  bigip_command:
    commands:
      - show sys version
      - list ltm virtual
    wait_for:
      - result[0] contains BIG-IP
      - result[1] contains my-vs
    provider:
      server: lb.mydomain.com
      password: secret
      user: admin
  register: result
  delegate_to: localhost

- name: tmsh prefixes will automatically be handled
  bigip_command:
    commands:
      - show sys version
      - tmsh list ltm virtual
    provider:
      server: lb.mydomain.com
      password: secret
      user: admin
  delegate_to: localhost

- name: Delete all LTM nodes in Partition1, assuming no dependencies exist
  bigip_command:
    commands:
      - delete ltm node all
    chdir: Partition1
    provider:
      server: lb.mydomain.com
      password: secret
      user: admin
  delegate_to: localhost

- name: Command that contains wildcard character to be passed to tmsh
  bigip_command:
    commands:
      - modify ltm data-group internal dg_string records add { "my test\\\\\\\*string"  { data "value" }}
    provider:
      server: lb.mydomain.com
      password: secret
      user: admin
  delegate_to: localhost

返回值 

常用的返回值已在此处记录，以下是此模块特有的字段

键	描述
失败条件列表 / 元素=字符串	失败的条件列表。返回：失败示例： `["...", "..."]`
标准输出列表 / 元素=字符串	命令的响应集。返回：始终返回示例： `["...", "..."]`
标准输出行列表 / 元素=字符串	将标准输出值拆分为列表。返回：始终返回示例： `[["...", "..."], ["..."], ["..."]]`
警告布尔值	是否引发有关修改命令的警告。返回：已更改示例： `true`

作者

Tim Rupp (@caphrim007)
Wojciech Wypior (@wojtek0806)