community.zabbix.zabbix_host 模块 – 创建/更新/删除 Zabbix 主机

注意

此模块是 community.zabbix 集合 (版本 3.2.0) 的一部分。

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

要安装它，请使用： ansible-galaxy collection install community.zabbix。您需要其他要求才能使用此模块，请参阅 要求 获取详细信息。

要在剧本中使用它，请指定： community.zabbix.zabbix_host。

概要

  • 此模块允许您创建、修改和删除 Zabbix 主机条目以及关联的组和模板数据。

要求

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

  • python >= 3.9

参数

参数

注释

ca_cert

别名：tls_issuer

字符串

必需的证书颁发者。

描述

字符串

Zabbix 中主机的描述。

force

布尔值

即使主机配置已存在，也覆盖它。

选项

  • false

  • true ← (默认)

host_groups

列表 / 元素=字符串

主机所属的主机组列表。

确保用于 Ansible 的 Zabbix 用户可以读取这些组。

host_name

字符串 / 必需

Zabbix 中主机的名称。

host_name 是使用的唯一标识符，无法使用此模块更新。

http_login_password

字符串

基本身份验证密码

http_login_user

字符串

基本身份验证用户名

interfaces

列表 / 元素=字典

要为主机创建的接口列表（请参见下面的示例）。

有关更多信息，请查看以下网址的主机接口文档：

https://www.zabbix.com/documentation/current/en/manual/api/reference/hostinterface/object#host-interface

默认： []

details

字典

SNMP 主机接口的其他详细信息。

当 type=”snmp” 时必需。

默认： {}

authpassphrase

字符串

SNMPv3 身份验证密码。

当 securitylevel=1(authNoPriv) 或 securitylevel=2(AuthPriv) 时使用。

默认： ""

authprotocol

整数

SNMPv3 身份验证协议。

当 securitylevel=1(authNoPriv) 或 securitylevel=2(AuthPriv) 时使用。

变体 2,3,4,5 仅在 Zabbix 5.4 或更高版本上受支持

0 (MD5), 1 (SHA1), 2 (SHA224), 3 (SHA256), 4 (SHA384), 5 (SHA512)

选项

  • 0 ← (默认)

  • 1

  • 2

  • 3

  • 4

  • 5

bulk

整数

是否使用批量 SNMP 请求。

0（不使用批量请求），1（使用批量请求）

选项

  • 0

  • 1 ← (默认)

community

字符串

SNMPv1 和 SNMPv2 社区字符串。

当 version=1 或 version=2 时必需。

默认： ""

contextname

字符串

SNMPv3 上下文名称。

默认： ""

privpassphrase

字符串

SNMPv3 私钥密码。

当 securitylevel=2(AuthPriv) 时使用。

默认： ""

privprotocol

整数

SNMPv3 私钥协议。

当 securitylevel=2(authPriv) 时使用。

变体 2,3,4,5 仅在 Zabbix 5.4 或更高版本上受支持

0 (DES), 1 (AES128), 2 (AES192), 3 (AES256), 4 (AES192C), 5 (AES256C)

选项

  • 0 ← (默认)

  • 1

  • 2

  • 3

  • 4

  • 5

securitylevel

整数

SNMPv3 安全级别。

0 (noAuthNoPriv), 1 (authNoPriv), 2 (authPriv)。

选项

  • 0 ← (默认)

  • 1

  • 2

securityname

字符串

SNMPv3 安全名称。

默认： ""

version

整数

SNMP 版本。

1 (SNMPv1), 2 (SNMPv2c), 3 (SNMPv3)

选项

  • 1

  • 2 ← (默认)

  • 3

dns

字符串

主机接口的DNS名称。

如果 useip=0，则必需。

ip

字符串

主机接口使用的IP地址。

如果 useip=1，则必需。

main

整数

接口是否用作默认接口。

如果提供了多个具有相同类型的接口，则只有一个可以是默认接口。

0（非默认），1（默认）

选项

  • 0 ← (默认)

  • 1

port

字符串

主机接口使用的端口。

如果未指定，则使用每种接口类型的默认端口

如果 type=”agent”，则为 10050

如果 type=”snmp”，则为 161

如果 type=”ipmi”，则为 623

如果 type=”jmx”，则为 12345

type

字符串 / 必需

要添加的接口类型

也接受接口类型的数值

1 = agent

2 = snmp

3 = ipmi

4 = jmx

选项

  • "agent"

  • "1"

  • "snmp"

  • "2"

  • "ipmi"

  • "3"

  • "jmx"

  • "4"

useip

整数

使用IP地址而非DNS名称连接到主机接口。

0（不使用IP），1（使用IP）

选项

  • 0 ← (默认)

  • 1

inventory_mode

字符串

配置清单模式。

选项

  • “自动”

  • “手动”

  • “禁用”

inventory_zabbix

字典

添加Zabbix清单的事实信息（例如标签）（参见下面的示例）。

请查看接口文档以获取有关支持属性的更多信息

https://www.zabbix.com/documentation/current/en/manual/api/reference/host/object#host-inventory

ipmi_authtype

整数

IPMI身份验证算法。

请查看主机对象文档以获取有关支持属性的更多信息

https://www.zabbix.com/documentation/3.4/manual/api/reference/host/object

可能的值为：0（无），1（MD2），2（MD5），4（直接），5（OEM），6（RMCP+），-1 为API默认值。

请注意，在更新任何_ipmi_选项时，Zabbix API 会将缺失的设置视为默认值；这意味着，如果您尝试单独设置四个选项中的任何一个，其余选项将重置为默认值。

ipmi_password

字符串

IPMI 密码。

另请参见_ipmi_authtype_文档中的最后一条说明

ipmi_privilege

整数

IPMI 权限级别。

请查看主机对象文档以获取有关支持属性的更多信息

https://www.zabbix.com/documentation/3.4/manual/api/reference/host/object

可能的值为1（回调），2（用户），3（操作员），4（管理员），5（OEM），2为API默认值。

另请参见_ipmi_authtype_文档中的最后一条说明

ipmi_username

字符串

IPMI 用户名。

另请参见_ipmi_authtype_文档中的最后一条说明

列表 / 元素=字符串

链接到主机的模板列表。

宏

别名：user_macros

列表 / 元素=字典

要分配给Zabbix主机的用户宏列表。

使用force=yes 提供macros=[] 将清除主机上所有现有的用户宏。

描述

字符串

用户宏的描述。

默认： ""

宏

字符串 / 必需

用户宏的名称。

可以是Zabbix原生格式“{$MACRO}”或简短格式“MACRO”。

类型

字符串

宏的类型。

由于API不会返回秘密宏的值，因此无法可靠地检测秘密宏值内容的变化。

要更新秘密宏值，请同时更新其描述，以便通过检查。

选项

  • "text" ← (默认)

  • “secret”

值

字符串 / 必需

用户宏的值。

monitored_by

字符串

Zabbix 7.0 中引入的参数。

用于监控主机的来源。

选项

  • “zabbix_server”

  • “proxy”

  • “proxy_group”

proxy

字符串

要使用的Zabbix代理的名称。

如果monitored_by 为“proxy”，则需要此参数。

proxy_group

字符串

Zabbix 7.0 中引入的参数。

用于监控主机的代理组。

如果monitored_by 为“proxy_group”，则需要此参数。

state

字符串

主机的状态。

在present 上，如果主机不存在，则会创建它；如果关联的数据不同，则会更新主机。

在absent 上，如果主机存在，则会将其删除。

选项

  • "present" ← (默认)

  • “absent”

status

字符串

主机的监控状态。

选项

  • "enabled" ← (默认)

  • “禁用”

标签

别名：host_tags

列表 / 元素=字典

要分配给Zabbix主机的主机标签列表。

使用force=yes 提供tags=[] 将清除主机上的所有标签。

标签

字符串 / 必需

主机标签的名称。

值

字符串

主机标签的值。

默认： ""

tls_accept

整数

指定允许哪些类型的连接用于传入连接。

tls_accept参数接受1到7的值

可能的值：1（无加密），2（PSK），4（证书）。

值可以组合。

tls_connect

整数

指定要用于传出连接的加密。

可能的值：1（无加密），2（PSK），4（证书）。

tls_psk

字符串

PSK值是一个难以猜测的十六进制数字字符串。

预共享密钥，至少32个十六进制数字。如果tls_connect或tls_accept启用了PSK，则需要此参数。

使用此参数将使此模块非幂等。

tls_psk_identity

字符串

这是Zabbix组件用来引用此特定PSK的唯一名称

不要在PSK标识字符串中放置敏感信息，因为它会在网络上传输未加密。

仅适用于>= Zabbix 3.0

将此参数与Zabbix >= 5.4一起使用将使此模块非幂等。

tls_subject

字符串

必需的证书主题。

visible_name

字符串

Zabbix中主机的可见名称。

示例

# If you want to use Username and Password to be authenticated by Zabbix Server
- name: Set credentials to access Zabbix Server API
  ansible.builtin.set_fact:
    ansible_user: Admin
    ansible_httpapi_pass: zabbix

# If you want to use API token to be authenticated by Zabbix Server
# https://www.zabbix.com/documentation/current/en/manual/web_interface/frontend_sections/administration/general#api-tokens
- name: Set API token
  ansible.builtin.set_fact:
    ansible_zabbix_auth_key: 8ec0d52432c15c91fcafe9888500cf9a607f44091ab554dbee860f6b44fac895

- name: Create a new host or rewrite an existing host's info (Zabbix <= 7.0)
# Set task level following variables for Zabbix Server host in task
  vars:
    ansible_network_os: community.zabbix.zabbix
    ansible_connection: httpapi
    ansible_httpapi_port: 443
    ansible_httpapi_use_ssl: true
    ansible_httpapi_validate_certs: false
    ansible_zabbix_url_path: "zabbixeu"  # If Zabbix WebUI runs on non-default (zabbix) path ,e.g. http://<FQDN>/zabbixeu
  become: false
  delegate_to: zabbix-example-fqdn.org# you can use delegate_to or task level ansible_host like next example
  community.zabbix.zabbix_host:
    host_name: ExampleHost
    visible_name: ExampleName
    description: My ExampleHost Description
    host_groups:
      - Example group1
      - Example group2
    link_templates:
      - Example template1
      - Example template2
    status: enabled
    state: present
    inventory_mode: manual
    inventory_zabbix:
      tag: "{{ your_tag }}"
      alias: "{{ your_alias }}"
      notes: "Special Informations: {{ your_informations | default('None') }}"
      location: "{{ your_location }}"
      site_rack: "{{ your_site_rack }}"
      os: "{{ your_os }}"
      hardware: "{{ your_hardware }}"
    ipmi_authtype: 2
    ipmi_privilege: 4
    ipmi_username: username
    ipmi_password: password
    interfaces:
      - type: 1
        main: 1
        useip: 1
        ip: 10.xx.xx.xx
        dns: ""
        port: "10050"
      - type: 4
        main: 1
        useip: 1
        ip: 10.xx.xx.xx
        dns: ""
        port: "12345"
    proxy: a.zabbix.proxy
    macros:
      - macro: "{$EXAMPLEMACRO}"
        value: ExampleMacroValue
      - macro: EXAMPLEMACRO2
        value: ExampleMacroValue2
        description: Example desc that work only with Zabbix 4.4 and higher
    tags:
      - tag: ExampleHostsTag
      - tag: ExampleHostsTag2
        value: ExampleTagValue

- name: Create a new host or update it - monitored by Zabbix Proxy (Zabbix >= 7.0)
# Set task level following variables for Zabbix Server host in task
  vars:
    ansible_network_os: community.zabbix.zabbix
    ansible_connection: httpapi
    ansible_httpapi_port: 443
    ansible_httpapi_use_ssl: true
    ansible_httpapi_validate_certs: false
    ansible_zabbix_url_path: "zabbixeu"  # If Zabbix WebUI runs on non-default (zabbix) path ,e.g. http://<FQDN>/zabbixeu
  become: false
  delegate_to: zabbix-example-fqdn.org# you can use delegate_to or task level ansible_host like next example
  community.zabbix.zabbix_host:
    host_name: ExampleHost
    host_groups:
      - Example group1
    status: enabled
    state: present
    monitored_by: proxy
    proxy: a.zabbix.proxy

- name: Create a new host or update it - monitored by Zabbix Proxy Group (Zabbix >= 7.0)
# Set task level following variables for Zabbix Server host in task
  vars:
    ansible_network_os: community.zabbix.zabbix
    ansible_connection: httpapi
    ansible_httpapi_port: 443
    ansible_httpapi_use_ssl: true
    ansible_httpapi_validate_certs: false
    ansible_zabbix_url_path: "zabbixeu"  # If Zabbix WebUI runs on non-default (zabbix) path ,e.g. http://<FQDN>/zabbixeu
  become: false
  delegate_to: zabbix-example-fqdn.org# you can use delegate_to or task level ansible_host like next example
  community.zabbix.zabbix_host:
    host_name: ExampleHost
    host_groups:
      - Example group1
    status: enabled
    state: present
    monitored_by: proxy_group
    proxy: a.zabbix.proxy.group

- name: Update an existing host's TLS settings
# Set current task level variables for Zabbix Server host in task
  vars:
    ansible_network_os: community.zabbix.zabbix
    ansible_connection: httpapi
    ansible_httpapi_port: 443
    ansible_httpapi_use_ssl: true
    ansible_httpapi_validate_certs: false
    ansible_zabbix_url_path: "zabbixeu"  # If Zabbix WebUI runs on non-default (zabbix) path ,e.g. http://<FQDN>/zabbixeu
    ansible_host: zabbix-example-fqdn.org # you can use task level ansible_host or delegate_to like in previous example
  become: false
  community.zabbix.zabbix_host:
    host_name: ExampleHost
    visible_name: ExampleName
    host_groups:
      - Example group1
    tls_psk_identity: test
    tls_connect: 2
    tls_psk: 123456789abcdef123456789abcdef12
    force: false

作者

  • Cove (@cove)

  • 丁敏飞（Tony Minfei Ding）

  • Harrison Gu (@harrisongu)

  • Werner Dijkerman (@dj-wasabi)

  • Eike Frost (@eikef)