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

注意

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

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

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

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

概要

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

要求

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

  • python >= 3.9

参数

参数

注释

ca_cert

别名：tls_issuer

字符串

必需的证书颁发者。

描述

字符串

Zabbix 中主机的描述。

强制

布尔值

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

选项

  • 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）时使用。

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

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）时使用。

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

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

类型

字符串 / 必需

要添加的接口类型

数值也接受作为接口类型

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

字符串

配置资产清单模式。

选项

  • "automatic"

  • "manual"

  • "disabled"

inventory_zabbix

字典

为 Zabbix 资产清单添加 Facts (例如，标签) (请参见下面的示例)。

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

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* 文档中的最后一条说明

列表 / 元素=字符串

链接到主机的模板列表。

macros

别名: user_macros

列表 / 元素=字典

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

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

description

字符串

用户宏的描述。

默认值： ""

macro

字符串 / 必需

用户宏的名称。

可以使用 Zabbix 本机格式 “{$MACRO}” 或简短格式 “MACRO”。

type

字符串

宏的类型。

由于 API 不会返回 secret 宏的值，因此没有可靠的方法来检测 secret 宏值的内容更改。

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

选项

  • "text" ← (默认)

  • "secret"

value

字符串 / 必需

用户宏的值。

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" ← (默认)

  • "disabled"

tags

别名: host_tags

列表 / 元素=字典

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

提供带有 *force=yes* 的 *tags=[]* 将清除主机的所有标签。

tag

字符串 / 必需

主机标签的名称。

value

字符串

主机标签的值。

默认值： ""

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)