The Icinga 2 support in DebOps is designed around installation of Icinga Agents
on all hosts and presence of 1 master/director node. The Icinga 2 Director is
not mandatory, without it the
debops.icinga role can be used to configure
Icinga 2 nodes manually, either through Ansible inventory or via role dependent
variables. However, with Icinga Director, the role can register new Icinga
nodes automatically as long as the specified host templates are prepared
It's advisable to test the deployment in a development environment before applying it in production. This should let you find out possible issues with DNS and PKI configuration you might encounter.
You might need to allow connections to the Icinga API interface, by default on
port 5665, through the firewall. You can do this by setting the
icinga__allow or its group or host equivalent in the inventory.
Usually only the master host needs the access opened, unless you plan to
initiate connections from the master to the clients.
Icinga 2 uses X.509 certificates for internal communication between the nodes, therefore the correct DNS records for the hosts are required. When DNS is not configured properly beforehand, communication between the cluster nodes can be disrupted.
At the moment, the debops.icinga role uses the PKI infrastructure maintained by the debops.pki role to provide X.509 certificates for Icinga 2 agents. Due to that, automatic registration of the Icinga 2 agents external to the cluster in the Icinga 2 CA is not possible at this time. It can be implemented later if there's demand for it.
debops.icinga role uses DNS
SRV records to find the addresses of
the master Icinga 2 nodes, as well as the Icinga 2 Director API. The nodes
check the DNS records to determine if they should be configured as the "master"
hosts, or client hosts that register themselves.
The DNS SRV record service names are:
_icinga-master._tcp(for the master node(s))
_icinga-director._tcp(for the director node(s))
There can be multiple master and director DNS SRV records. The role will
configure multiple master nodes in the
zones.conf configuration file,
however only one director node will be used.
You should create the DNS
SRV records for the master and Director hosts,
otherwise all of the Icinga 2 nodes will see themselves as "master" nodes and
won't try to connect to each other. To do that in dnsmasq, you can
add the configuration options:
srv-host = _icinga-master._tcp.example.org,icinga-master.example.org,5665 srv-host = _icinga-director._tcp.example.org,icinga.example.org,443
Similar records in the ISC BIND zone file:
_icinga-master._tcp.example.org. 86400 IN SRV 0 5 5665 icinga-master.example.org. _icinga-director._tcp.example.org. 86400 IN SRV 0 5 443 icinga.example.org.
The above configuration sets the
icinga-master.example.org host as the
"master" host. The Director API is available on a separate FQDN,
You can also define the master and director nodes explicitly in the inventory
variables, using the Ansible
dig lookup syntax. To set the above
configuration, define in the inventory:
icinga__master_nodes: - target: 'icinga-master.example.org' port: '5665' icinga__director_nodes: - target: 'icinga.example.org' port: '443'
This is an example Ansible inventory for deployment of the full Icinga "stack" in DebOps environment. The debops.icinga role is applied on all hosts in the environment, however the debops.icinga_db and debops.icinga_web are applied only on the master host.
[debops_all_hosts] icinga-master hostname1 hostname2 [debops_service_icinga:children] debops_all_hosts [debops_service_postgresql_server] icinga-master [debops_service_icinga_db] icinga-master [debops_service_icinga_web] icinga-master
By default the web interface is configured on the
icinga. subdomain, you
can change this by setting the
It's best to start the deployment on the Icinga master node, by setting up the
local Icinga 2 Agent, and the web interface with the Icinga Director. You can
login to the web interface using the
root username and the password stored
file (see debops.secret for more details).
After logging in, you should create a new basic host template. By default, the
role will try and register the nodes using the
generic-host template. To
create it, go to the "Icinga Director" -> "Hosts" -> "Host Templates" section
and click on "Add". Enter "generic-host" as the "Hostname", set the "Check
command" option as "hostalive". You should also set a reasonable "Check
interval", "Retry interval' and "Max check attempts" fields, for example with
5 minutes, 30 seconds and 5 tries.
It might be best to add a separate host template for hosts with Icinga 2 Agent
installed, in case that you want to include other hosts as well. For this,
create a new template with a chosen name, and in the "Icinga Agent and zone
settings" section set the "Icinga 2 Agent", "Estabilish connection" and
"Accepts config" options to "Yes". You can define the list of templates
automatically applied during registration using the
icinga__director_register_*_templates default variables.
After this you can apply the debops.icinga role to other hosts. If everything was configured correctly, the role should automatically register a new host in Icinga via the Director REST API. Subsequent execution of the role will not change the status of the host in Icinga, but if you remove the host from the web interface and re-run the debops.icinga role, the host will be registered again.