f5networks.f5_modules.bigip_policy_rule 模块 – 在 BIG-IP 上管理 LTM 策略规则

注意

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

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

要安装它，请使用：ansible-galaxy collection install f5networks.f5_modules。您需要进一步的要求才能使用此模块，请参阅 要求 以了解详细信息。

要在剧本中使用它，请指定：f5networks.f5_modules.bigip_policy_rule。

f5networks.f5_modules 1.0.0 中的新功能

概要

• 此模块管理 BIG-IP 上的 LTM 策略规则。

要求

执行此模块的主机需要以下要求。

• BIG-IP >= v12.1.0

参数

参数	注释
actions 列表 / 元素=字典	您希望策略规则执行的操作。 可用属性因操作而异，但是，每个操作都需要您指定一个 type。 这些条件可以按任意顺序指定。尽管它们在列表中，但列表中顺序对 BIG-IP 而言无关紧要。
asm_policy 字符串	要启用的 ASM 策略。 此参数仅在 enable 类型有效。
cookie_expiry 整数 在 f5networks.f5_modules 1.1.0 中添加	可选参数，指定会话持续的时间。 此参数仅在 persist 类型有效。
cookie_insert 字符串 在 f5networks.f5_modules 1.1.0 中添加	您要持久化的 Cookie 名称。 此参数仅在 persist 类型有效。
disable_target 字符串 在 f5networks.f5_modules 1.8.0 中添加	您要禁用的目标。 此参数仅在 disable 类型有效。 选项 "server_ssl" "persist" "asm"
event 字符串	可以触发诸如重置和转发之类的操作的事件。 使用 set_variable 操作时，它用于指定操作事件，例如请求或响应。 forward 操作类型的有效事件选项为：client_accepted、proxy_request request、ssl_client_hello 和 ssl_client_server_hello_send。 reset 操作类型的有效事件选项为：client_accepted、proxy_connect proxy_request、proxy_response、request、response、server_connected、ssl_client_hello、ssl_client_server_hello_send、ssl_server_handshake、ssl_server_hello、websocket_request、websocket_response。 disable 操作类型的有效事件选项为：client_accepted、proxy_connect proxy_request、proxy_response、request、server_connected。
expression 字符串	与 set_variable 操作一起使用的 Tcl 表达式。
http_connect 字典 在 f5networks.f5_modules 1.8.0 中添加	您要替换的 HTTP Connect 标头。 此参数仅在 replace 类型有效。
event 字符串 / 必需	替换 http_connect 标头时的事件类型。 选项 "client_accepted" "proxy_connect" "proxy_request" "proxy_response" "request" "server_connected" "ssl_client_hello"
port 整数	端口号。 如果未提供端口号，则默认情况下该值设置为 0。 在定义规则时要明确，以便系统不会覆盖端口值。
value 字符串 / 必需	http_connect 的值。
http_cookie 字典 在 f5networks.f5_modules 1.8.0 中添加	您要删除或插入的 HTTP Cookie 标头。 此参数仅在 remove 和 insert 类型有效。
event 字符串 / 必需	删除或插入 http_cookie 时的事件类型。 选项 "request" "proxy_connect" "proxy_request"
name 字符串 / 必需	http_cookie 的名称。
value 字符串	http_cookie 的值。 当配置为 insert 类型操作时，这是强制性参数。
http_header 字典 在 f5networks.f5_modules 1.8.0 中添加	您要删除或插入的 HTTP 标头。 此参数仅在 remove、insert 和 replace 类型有效。
event 字符串 / 必需	删除、替换或插入 http_header 时的事件类型。 request 和 response 事件仅在 remove 和 insert 类型中是选项。 所有事件对于 replace 类型操作均有效。 选项 "request" "response" "proxy_connect" "proxy_request" "proxy_response"
name 字符串 / 必需	http_header 的名称。
value 字符串	http_header 的值。 当配置为 insert 或 replace 类型时，此参数是强制性的。
http_host 字典 在 f5networks.f5_modules 1.8.0 中添加	您要替换的 HTTP Host 标头。 此参数仅在 replace 类型有效。
event 字符串 / 必需	替换 http_host 时的事件类型。 选项 "request" "proxy_connect" "proxy_request"
value 字符串 / 必需	http_host 的值。
http_referer 字典 在 f5networks.f5_modules 1.8.0 中添加	您要删除、替换或插入的 HTTP Referer 标头。 此参数仅在 remove、insert 和 replace 类型有效。
event 字符串 / 必需	删除、替换或插入 c(http_referer) 时的事件类型。 选项 "request" "proxy_connect" "proxy_request"
value 字符串	http_referer 的值。 当配置为 insert 类型操作时，这是强制性参数。 此参数对于 remove 类型将被忽略。 此参数对于 replace 类型是可选的。
http_set_cookie 字典 在 f5networks.f5_modules 1.8.0 中添加	您要删除或插入的 HTTP Set-Cookie 标头。 此参数仅在 remove 或 c(insert) 类型有效。
name 字符串 / 必需	http_set_cookie 的名称。
value 字符串	http_set_cookie 的值。 当配置为 insert 类型操作时，这是强制性参数。
http_uri 字典 在 f5networks.f5_modules 1.8.0 中添加	替换 HTTP URI、路径或字符串。 此参数仅在 replace 类型有效。
event 字符串 / 必需	当 http_uri 被替换时发生的事件类型。 选项 "request" "proxy_connect" "proxy_request"
type 字符串 / 必需	指定要替换的 http_uri 的部分。 选项 "path" "query_string" "full_string"
value 字符串 / 必需	http_uri 的值。
location 字符串	发送重定向响应的新 URL。 此字段可以使用 Tcl 命令替换。
node 字符串 在 f5networks.f5_modules 1.2.0 中添加	要将流量转发到的节点。 此参数仅在 forward 类型有效。
pool 字符串	要将流量转发到的池。 此参数仅在 forward 类型有效。
type 字符串 / 必需	操作类型。此值控制需要以下哪些选项。 当 type 为 forward 时，系统将给定的 pool、virtual 或 node 与此规则关联。 当 type 为 enable 时，系统将给定的 asm_policy 与此规则关联。 当 type 为 ignore 时，系统从此规则中删除所有现有操作。 当 type 为 redirect 时，系统会将 HTTP 请求重定向到其他 URL。 当 type 为 reset 时，系统会在 event 发生时重置连接。 当 type 为 persist 时，系统将 cookie_insert 和 cookie_expiry 与此规则关联。 当 type 为 set_variable 时，系统会根据基于 event 评估的 Tcl expression 设置变量。 当 type 为 remove 时，系统会使用此规则删除 http_set_cookie、http_referer、http_header 或 http_cookie。 当 type 为 insert 时，系统会使用此规则插入 http_set_cookie、http_referer、http_header 或 http_cookie。 当 type 为 replace 时，系统会使用此规则替换 http_connect、http_referer、http_header、http_uri 或 http_host。 当 type 为 disable 时，系统会使用此规则禁用 disable_target。 选项 "forward" "enable" "ignore" "redirect" "reset" "persist" "set_variable" "remove" "insert" "replace" "disable"
variable_name 字符串	与 set_variable 操作一起使用的变量名称。
virtual 字符串	要将流量转发到的虚拟服务器。 此参数仅在 forward 类型有效。
conditions 列表 / 元素=字典	描述条件的属性列表。 有关如何构造每个列表条目的详细信息，请参阅子选项。 此列表的顺序很重要，模块在修改任务时会确保保持该顺序。 并非所有条件类型都需要以下子选项，请阅读说明了解更多详细信息。 这些条件可以按任意顺序指定。尽管它们在列表中，但列表中顺序对 BIG-IP 而言无关紧要。
address_matches_with_any list / elements=string 在 f5networks.f5_modules 1.8.0 中添加	IP 地址应匹配的 IP 子网地址字符串列表。 此参数仅在 tcp 类型有效。
address_matches_with_datagroup list / elements=string 在 f5networks.f5_modules 1.8.0 中添加	IP 地址应匹配的内部数据组字符串列表。 此参数仅在 tcp 类型有效。
address_matches_with_external_datagroup list / elements=string 在 f5networks.f5_modules 1.10.0 中添加	IP 地址应匹配的外部数据组字符串列表。 此参数仅在 tcp 类型有效。
event 字符串	可以触发条件类型匹配规则的事件。 仅支持 http_header、http_method、ssl_extension 和 tcp。 http_header 条件类型的有效选择为： proxy_connect、proxy_request、proxy_response、request 和 response。 http_method 条件类型的有效选择为： proxy_connect、proxy_request、proxy_response、request 和 response。 tcp 条件类型的有效选择为： request、client_accepted、proxy_connect、proxy_request、proxy_response、ssl_client_hello 和 ssl_client_server_hello_send。 ssl_extension 的有效选择为： ssl_client_hello 和 ssl_client_server_hello_send。
header_is_any list / elements=string 在 f5networks.f5_modules 1.8.0 中添加	HTTP 标头值应匹配的字符串列表。 此参数仅在 http_header 类型有效。
header_name 字符串 在 f5networks.f5_modules 1.8.0 中添加	http_header 的名称。 此参数仅在 http_header 类型有效。
host_begins_not_with_any list / elements=string 在 f5networks.f5_modules 1.22.0 中添加	HTTP Host 不应以之开头的字符串列表。 此参数仅在 http_host 类型有效。
host_begins_with_any list / elements=string	HTTP Host 应以之开头的字符串列表。 此参数仅在 http_host 类型有效。
host_contains list / elements=string 在 f5networks.f5_modules 1.23.0 中添加	HTTP Host 应包含的字符串列表。 此参数仅在 http_host 类型有效。
host_ends_not_with_any list / elements=string 在 f5networks.f5_modules 1.22.0 中添加	HTTP Host 不应以之开头的字符串列表。 此参数仅在 http_host 类型有效。
host_ends_with_any list / elements=string 在 f5networks.f5_modules 1.8.0 中添加	HTTP Host 应以之结尾的字符串列表。 此参数仅在 http_host 类型有效。
host_is_any list / elements=string	HTTP Host 应匹配的字符串列表。 此参数仅在 http_host 类型有效。
host_is_not_any list / elements=string	HTTP Host 不应匹配的字符串列表。 此参数仅在 http_host 类型有效。
method_matches_with_any list / elements=string 在 f5networks.f5_modules 1.10.0 中添加	HTTP 方法值应匹配的字符串列表。 此参数仅在 http_method 类型有效。
path_begins_with_any list / elements=string	HTTP URI 应以之开头的字符串列表。 此参数仅在 http_uri 类型有效。
path_contains list / elements=string 在 f5networks.f5_modules 1.8.0 中添加	HTTP URI 应包含的字符串列表。 此参数仅在 http_uri 类型有效。
path_is_any list / elements=string 在 f5networks.f5_modules 1.8.0 中添加	HTTP URI 应匹配的字符串列表。 此参数仅在 http_uri 类型有效。
server_name_begins_not_with_any list / elements=string 在 f5networks.f5_modules 1.27.0 中添加	服务器名称不应以之开头的名称列表。 此参数仅在 ssl_extension 类型有效。
server_name_begins_with_any list / elements=string 在 f5networks.f5_modules 1.27.0 中添加	服务器名称应以之开头的名称列表。 此参数仅在 ssl_extension 类型有效。
server_name_contains list / elements=string 在 f5networks.f5_modules 1.27.0 中添加	服务器名称应包含的名称列表。 此参数仅在 ssl_extension 类型有效。
server_name_ends_not_with_any list / elements=string 在 f5networks.f5_modules 1.27.0 中添加	服务器名称不应以之结尾的名称列表。 此参数仅在 ssl_extension 类型有效。
server_name_ends_with_any list / elements=string 在 f5networks.f5_modules 1.27.0 中添加	服务器名称应以之结尾的名称列表。 此参数仅在 ssl_extension 类型有效。
server_name_is_any list / elements=string	包含服务器名称的名称列表。 此参数仅在 ssl_extension 类型有效。
server_name_is_not_any list / elements=string 在 f5networks.f5_modules 1.27.0 中添加	不包含服务器名称的名称列表。 此参数仅在 ssl_extension 类型有效。
type 字符串 / 必需	条件类型。此值控制需要以下哪些选项。 当 type 为 http_uri 时，有效选择为： path_begins_with_any、path_contains 或 path_is_any。 当 type 为 http_host 时，有效选择为： host_is_any、host_is_not_any、host_contains、host_begins_with_any、host_begins_not_with_any、host_ends_with_any 或 host_ends_not_with_any。 当 type 为 http_header 时，header_name 参数是强制性的，有效选择为： header_is_any。 当 type 为 http_method 时，有效选择为： method_matches_with_any。 当 type 为 all_traffic 时，系统将从此规则中删除所有现有条件。 选项 "http_uri" "all_traffic" "http_host" "http_header" "http_method" "ssl_extension" "tcp"
描述 字符串	策略规则的描述。
name 字符串 / 必需	规则的名称。
分区 字符串	用于管理资源的设备分区。 默认值： "Common"
策略 字符串 / 必需	要将此规则关联的策略的名称。
提供程序 字典 在 f5networks.f5_modules 1.0.0 中添加	包含连接详细信息的字典对象。
身份验证提供程序 字符串	配置身份验证提供程序以从远程设备获取身份验证令牌。 此选项在与 BIG-IQ 设备一起工作时真正使用。
no_f5_teem 布尔值	如果为 yes，则不会将 TEEM 遥测数据发送到 F5。 您可以通过设置环境变量 F5_TELEMETRY_OFF 来省略此选项。 之前使用的变量 F5_TEEM 已被弃用，因为其名称容易混淆。 选项 false ← (默认) true
密码 别名：pass，pwd 字符串 / 必需	用于连接到 BIG-IP 或 BIG-IQ 的用户帐户的密码。 您可以通过设置环境变量 F5_PASSWORD 来省略此选项。
服务器 字符串 / 必需	BIG-IP 主机或 BIG-IQ 主机。 您可以通过设置环境变量 F5_SERVER 来省略此选项。
服务器端口 整数	BIG-IP 服务器端口。 您可以通过设置环境变量 F5_SERVER_PORT 来省略此选项。 默认值： 443
超时 整数	指定与网络设备通信以进行连接或发送命令的超时时间（以秒为单位）。如果在操作完成之前超过超时时间，则模块将出错。
传输 字符串	配置连接到远程设备时使用的传输连接。 选项 "rest" ← (默认)
用户 字符串 / 必需	用于连接到 BIG-IP 或 BIG-IQ 的用户名。此用户必须具有设备上的管理员权限。 您可以通过设置环境变量 F5_USER 来省略此选项。
验证证书 布尔值	如果为 no，则不验证 SSL 证书。仅在个人控制的站点上使用自签名证书时使用此选项。 您可以通过设置环境变量 F5_VALIDATE_CERTS 来省略此选项。 选项 false true ← (默认)
替换为 布尔值	指定用户给定的 conditions/actions 是否应覆盖设备上已存在的内容。 当需要删除 conditions/actions 的子集时，此选项非常有用。此选项类似于 TMSH 命令中可用的 replace-all-with 标志。 使用此选项不是幂等的。 选项 false ← (默认) true
规则顺序 整数 在 f5networks.f5_modules 1.10.0 中添加	指定一个数字，该数字指示此规则相对于策略中其他规则的顺序。 如果未设置，设备会将参数设置为 0。 如果存在具有相同规则顺序编号的规则，则设备将使用规则名称来确定规则的排序方式。 数字越小，规则在整体顺序中的位置越低，最小数字 0 是最顶部的规则。 有效值范围介于 0 和 4294967295 之间（包括端点值）。
状态 字符串	当为 present 时，确保密钥已上传到设备。当为 absent 时，确保密钥已从设备中删除。如果密钥当前正在使用中，则模块将无法删除密钥。 选项 "present" ← (默认) "absent"

注释

注意

• 有关使用 Ansible 管理 F5 Networks 设备的更多信息，请参阅 https://ansible.org.cn/integrations/networks/f5。

• 需要 BIG-IP 软件版本 >= 12。

• F5 模块仅操作 F5 产品的运行配置。为确保特定于 BIG-IP 的配置持久保存到磁盘，请务必至少包含一个使用 f5networks.f5_modules.bigip_config 模块来保存运行配置的任务。有关正确使用该模块来保存运行配置的信息，请参阅该模块的文档。

示例

- name: Create policies
  bigip_policy:
    name: Policy-Foo
    state: present
    provider:
      server: lb.mydomain.com
      user: admin
      password: secret
  delegate_to: localhost

- name: Add a rule to the new policy
  bigip_policy_rule:
    policy: Policy-Foo
    name: rule3
    conditions:
      - type: http_uri
        path_begins_with_any:
          - /ABC
    actions:
      - type: forward
        pool: pool-svrs
    provider:
      server: lb.mydomain.com
      user: admin
      password: secret
  delegate_to: localhost

- name: Add multiple rules to the new policy
  bigip_policy_rule:
    policy: Policy-Foo
    name: "{{ item.name }}"
    conditions: "{{ item.conditions }}"
    actions: "{{ item.actions }}"
    provider:
      server: lb.mydomain.com
      user: admin
      password: secret
  delegate_to: localhost
  loop:
    - name: rule1
      actions:
        - type: forward
          pool: pool-svrs
      conditions:
        - type: http_uri
          path_begins_with_any:
            - /euro
    - name: rule2
      actions:
        - type: forward
          pool: pool-svrs
      conditions:
        - type: http_uri
          path_begins_with_any:
            - /HomePage/
    - name: rule3
      actions:
        - type: set_variable
          variable_name: user-agent
          expression: tcl:[HTTP::header User-Agent]
          event: request
      conditions:
        - type: http_uri
          path_begins_with_any:
            - /HomePage/

- name: Remove all rules and conditions from the rule
  bigip_policy_rule:
    policy: Policy-Foo
    name: rule1
    conditions:
      - type: all_traffic
    actions:
      - type: ignore
    provider:
      server: lb.mydomain.com
      user: admin
      password: secret
  delegate_to: localhost

返回值

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

键	描述
actions 复杂	应用于规则的新操作列表。 返回： 已更改 示例： "值的哈希/字典"
pool 字符串	要转发到的池。 返回： 已更改 示例： "foo-pool"
type 字符串	操作类型。 返回： 已更改 示例： "forward"
conditions 复杂	应用于规则的新条件列表。 返回： 已更改 示例： "值的哈希/字典"
path_begins_with_any list / elements=string	URI 开头的字符串列表。 返回： 已更改 示例： ["foo", "bar"]
type 字符串	条件类型。 返回： 已更改 示例： "http_uri"
描述 字符串	规则的新描述。 返回： 已更改 示例： "我的规则"
规则顺序 整数	指定一个数字，该数字指示此规则相对于策略中其他规则的顺序。 返回： 已更改 示例： 10

作者

• Tim Rupp (@caphrim007)

• Wojciech Wypior (@wojtek0806)

集合链接

• 问题跟踪器
• 主页
• 存储库（来源）