community.zabbix.zabbix_host (2.3.1) — module

Create/update/delete Zabbix hosts

Authors: Cove (@cove), Tony Minfei Ding (!UNKNOWN), Harrison Gu (@harrisongu), Werner Dijkerman (@dj-wasabi), Eike Frost (@eikef)

Install collection

Install with ansible-galaxy collection install community.zabbix:==2.3.1


Add to requirements.yml

  collections:
    - name: community.zabbix
      version: 2.3.1

Description

This module allows you to create, modify and delete Zabbix host entries and associated group and template data.


Requirements

Usage examples

  • Success
    Steampunk Spotter scan finished with no errors, warnings or hints.
# 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
  • Success
    Steampunk Spotter scan finished with no errors, warnings or hints.
# 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
  • Success
    Steampunk Spotter scan finished with no errors, warnings or hints.
- name: Create a new host or rewrite an existing host's info
# 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
  • Success
    Steampunk Spotter scan finished with no errors, warnings or hints.
- 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

Inputs

    
tags:
    aliases:
    - host_tags
    description:
    - List of host tags to assign to the zabbix host.
    - Providing I(tags=[]) with I(force=yes) will clean all of the tags from the host.
    elements: dict
    suboptions:
      tag:
        description:
        - Name of the host tag.
        required: true
        type: str
      value:
        default: ''
        description:
        - Value of the host tag.
        type: str
    type: list

force:
    default: 'yes'
    description:
    - Overwrite the host configuration, even if already present.
    type: bool

proxy:
    description:
    - The name of the Zabbix proxy to be used.
    type: str

state:
    choices:
    - present
    - absent
    default: present
    description:
    - State of the host.
    - On C(present), it will create if host does not exist or update the host if the associated
      data is different.
    - On C(absent) will remove a host if it exists.
    type: str

macros:
    aliases:
    - user_macros
    description:
    - List of user macros to assign to the zabbix host.
    - Providing I(macros=[]) with I(force=yes) will clean all of the existing user macros
      from the host.
    elements: dict
    suboptions:
      description:
        default: ''
        description:
        - Description of the user macro.
        required: false
        type: str
      macro:
        description:
        - Name of the user macro.
        - Can be in zabbix native format "{$MACRO}" or short format "MACRO".
        required: true
        type: str
      type:
        choices:
        - text
        - secret
        default: text
        description:
        - Type of the macro.
        - Since value is not returned by API for secret macros, there is no reliable way
          to detect changes in the content of secret macro value.
        - To update secret macro value, please update description alongside it so it passes
          the check.
        required: false
        type: str
      value:
        description:
        - Value of the user macro.
        required: true
        type: str
    type: list

status:
    choices:
    - enabled
    - disabled
    default: enabled
    description:
    - Monitoring status of the host.
    type: str

ca_cert:
    aliases:
    - tls_issuer
    description:
    - Required certificate issuer.
    type: str

tls_psk:
    description:
    - PSK value is a hard to guess string of hexadecimal digits.
    - The preshared key, at least 32 hex digits. Required if either I(tls_connect) or
      I(tls_accept) has PSK enabled.
    - Using this parameter makes this module non-idempotent.
    type: str

host_name:
    description:
    - Name of the host in Zabbix.
    - I(host_name) is the unique identifier used and cannot be updated using this module.
    required: true
    type: str

interfaces:
    default: []
    description:
    - List of interfaces to be created for the host (see example below).
    - For more information, review host interface documentation at
    - U(https://www.zabbix.com/documentation/current/en/manual/api/reference/hostinterface/object#host-interface)
    elements: dict
    suboptions:
      details:
        default: {}
        description:
        - Additional details for SNMP host interfaces.
        - Required when I(type="snmp").
        suboptions:
          authpassphrase:
            default: ''
            description:
            - SNMPv3 authentication passphrase.
            - Used when I(securitylevel=1)(authNoPriv) or I(securitylevel=2)(AuthPriv).
            type: str
          authprotocol:
            choices:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            default: 0
            description:
            - SNMPv3 authentication protocol.
            - Used when I(securitylevel=1)(authNoPriv) or I(securitylevel=2)(AuthPriv).
            - Variants 2,3,4,5 are supported only on Zabbix 5.4 or greater
            - 0 (MD5), 1 (SHA1), 2 (SHA224), 3 (SHA256), 4 (SHA384), 5 (SHA512)
            type: int
          bulk:
            choices:
            - 0
            - 1
            default: 1
            description:
            - Whether to use bulk SNMP requests.
            - 0 (don't use bulk requests), 1 (use bulk requests)
            type: int
          community:
            default: ''
            description:
            - SNMPv1 and SNMPv2 community string.
            - Required when I(version=1) or I(version=2).
            type: str
          contextname:
            default: ''
            description:
            - SNMPv3 context name.
            type: str
          privpassphrase:
            default: ''
            description:
            - SNMPv3 privacy passphrase.
            - Used when I(securitylevel=2)(AuthPriv).
            type: str
          privprotocol:
            choices:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            default: 0
            description:
            - SNMPv3 privacy protocol.
            - Used when I(securitylevel=2)(authPriv).
            - Variants 2,3,4,5 are supported only on Zabbix 5.4 or greater
            - 0 (DES), 1 (AES128), 2 (AES192), 3 (AES256), 4 (AES192C), 5 (AES256C)
            type: int
          securitylevel:
            choices:
            - 0
            - 1
            - 2
            default: 0
            description:
            - SNMPv3 security level.
            - 0 (noAuthNoPriv), 1 (authNoPriv), 2 (authPriv).
            type: int
          securityname:
            default: ''
            description:
            - SNMPv3 security name.
            type: str
          version:
            choices:
            - 1
            - 2
            - 3
            default: 2
            description:
            - SNMP version.
            - 1 (SNMPv1), 2 (SNMPv2c), 3 (SNMPv3)
            type: int
        type: dict
      dns:
        description:
        - DNS name of the host interface.
        - Required if I(useip=0).
        type: str
      ip:
        description:
        - IP address used by host interface.
        - Required if I(useip=1).
        type: str
      main:
        choices:
        - 0
        - 1
        default: 0
        description:
        - Whether the interface is used as default.
        - If multiple interfaces with the same type are provided, only one can be default.
        - 0 (not default), 1 (default)
        type: int
      port:
        description:
        - Port used by host interface.
        - If not specified, default port for each type of interface is used
        - 10050 if I(type="agent")
        - 161 if I(type="snmp")
        - 623 if I(type="ipmi")
        - 12345 if I(type="jmx")
        type: str
      type:
        choices:
        - agent
        - '1'
        - snmp
        - '2'
        - ipmi
        - '3'
        - jmx
        - '4'
        description:
        - Interface type to add
        - Numerical values are also accepted for interface type
        - 1 = agent
        - 2 = snmp
        - 3 = ipmi
        - 4 = jmx
        required: true
        type: str
      useip:
        choices:
        - 0
        - 1
        default: 0
        description:
        - Connect to host interface with IP address instead of DNS name.
        - 0 (don't use ip), 1 (use ip)
        type: int
    type: list

tls_accept:
    description:
    - Specifies what types of connections are allowed for incoming connections.
    - The tls_accept parameter accepts values of 1 to 7
    - Possible values, 1 (no encryption), 2 (PSK), 4 (certificate).
    - Values can be combined.
    type: int

description:
    description:
    - Description of the host in Zabbix.
    type: str

host_groups:
    description:
    - List of host groups the host is part of.
    - Make sure the Zabbix user used for Ansible can read these groups.
    elements: str
    type: list

tls_connect:
    description:
    - Specifies what encryption to use for outgoing connections.
    - Possible values, 1 (no encryption), 2 (PSK), 4 (certificate).
    type: int

tls_subject:
    description:
    - Required certificate subject.
    type: str

visible_name:
    description:
    - Visible name of the host in Zabbix.
    type: str

ipmi_authtype:
    description:
    - IPMI authentication algorithm.
    - Please review the Host object documentation for more information on the supported
      properties
    - https://www.zabbix.com/documentation/3.4/manual/api/reference/host/object
    - Possible values are, C(0) (none), C(1) (MD2), C(2) (MD5), C(4) (straight), C(5)
      (OEM), C(6) (RMCP+), with -1 being the API default.
    - Please note that the Zabbix API will treat absent settings as default when updating
      any of the I(ipmi_)-options; this means that if you attempt to set any of the four
      options individually, the rest will be reset to default values.
    type: int

ipmi_password:
    description:
    - IPMI password.
    - also see the last note in the I(ipmi_authtype) documentation
    type: str

ipmi_username:
    description:
    - IPMI username.
    - also see the last note in the I(ipmi_authtype) documentation
    type: str

inventory_mode:
    choices:
    - automatic
    - manual
    - disabled
    description:
    - Configure the inventory mode.
    type: str

ipmi_privilege:
    description:
    - IPMI privilege level.
    - Please review the Host object documentation for more information on the supported
      properties
    - https://www.zabbix.com/documentation/3.4/manual/api/reference/host/object
    - Possible values are C(1) (callback), C(2) (user), C(3) (operator), C(4) (admin),
      C(5) (OEM), with C(2) being the API default.
    - also see the last note in the I(ipmi_authtype) documentation
    type: int

link_templates:
    description:
    - List of templates linked to the host.
    elements: str
    type: list

http_login_user:
    description:
    - Basic Auth login
    required: false
    type: str

inventory_zabbix:
    description:
    - Add Facts for a zabbix inventory (e.g. Tag) (see example below).
    - Please review the interface documentation for more information on the supported
      properties
    - U(https://www.zabbix.com/documentation/current/en/manual/api/reference/host/object#host-inventory)
    type: dict

tls_psk_identity:
    description:
    - It is a unique name by which this specific PSK is referred to by Zabbix components
    - Do not put sensitive information in the PSK identity string, it is transmitted over
      the network unencrypted.
    - Works only with >= Zabbix 3.0
    - Using this parameter with Zabbix >= 5.4 makes this module non-idempotent.
    type: str

http_login_password:
    description:
    - Basic Auth password
    required: false
    type: str