Upgrading/Troubleshooting Docs: Agent Hosts with Command Endpoint require a Zone

refs #7514

diff --git a/doc/15-troubleshooting.md b/doc/15-troubleshooting.md
index 5523887078057b084d7975a76dc57aea34b0a278..02f6ef0721a7c88b1802e7b63f972811dd906c80 100644 (file)
--- a/doc/15-troubleshooting.md
+++ b/doc/15-troubleshooting.md
@@ -1393,6 +1393,56 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local
 ```
 
 
+#### Agent Hosts with Command Endpoint require a Zone <a id="troubleshooting-cluster-command-endpoint-errors-agent-hosts-command-endpoint-zone"></a>
+
+2.11 fixes bugs where agent host checks would never be scheduled on
+the master. One requirement is that the checkable host/service
+is put into a zone.
+
+By default, the Director puts the agent host in `zones.d/master`
+and you're good to go. If you manually manage the configuration,
+the config compiler now throws an error with `command_endpoint`
+being set but no `zone` defined.
+
+In case you previously managed the configuration outside of `zones.d`,
+follow along with the following instructions.
+
+The most convenient way with e.g. managing the objects in `conf.d`
+is to move them into the `master` zone.
+
+First, verify the name of your endpoint's zone. The CLI wizards
+use `master` by default.
+
+```
+vim /etc/icinga2/zones.conf
+
+object Zone "master" {
+  ...
+}
+```
+
+Then create a new directory in `zones.d` called `master`, if not existing.
+
+```
+mkdir -p /etc/icinga2/zones.d/master
+```
+
+Now move the directory tree from `conf.d` into the `master` zone.
+
+```
+mv conf.d/* /etc/icinga2/zones.d/master/
+```
+
+Validate the configuration and reload Icinga.
+
+```
+icinga2 daemon -C
+systemctl restart icinga2
+```
+
+Another method is to specify the `zone` attribute manually, but since
+this may lead into other unwanted "not checked" scenarios, we don't
+recommend this for your production environment.
 
 ### Cluster Troubleshooting Config Sync <a id="troubleshooting-cluster-config-sync"></a>
 

diff --git a/doc/16-upgrading-icinga-2.md b/doc/16-upgrading-icinga-2.md
index 792ec18b4f9aa89bebf70c9d21d47beb3fad0491..2ffed83f2b4b57ad6650a035250ab72b281ace77 100644 (file)
--- a/doc/16-upgrading-icinga-2.md
+++ b/doc/16-upgrading-icinga-2.md
@@ -152,6 +152,22 @@ please let us know with an issue on GitHub.
 
 ### Cluster <a id="upgrading-to-2-11-cluster"></a>
 
+#### Agent Hosts with Command Endpoint require a Zone <a id="upgrading-to-2-11-cluster-agent-hosts-command-endpoint-zone"></a>
+
+2.11 fixes bugs where agent host checks would never be scheduled on
+the master. One definite requirement is that the checkable host/service
+is put into a zone.
+
+By default, the Director puts the agent host in `zones.d/master`
+and you're good to go. If you manually manage the configuration,
+the config compiler now throws an error with `command_endpoint`
+being set but no `zone` defined.
+
+The most convenient way with e.g. managing the objects in `conf.d`
+is to move them into the `master` zone. Please continue in the
+[troubleshooting docs](#troubleshooting-cluster-command-endpoint-errors-agent-hosts-command-endpoint-zone)
+for further instructions.
+
 #### Config Sync <a id="upgrading-to-2-11-cluster-config-sync"></a>
 
 2.11 overhauls the cluster config sync in many ways. This includes the