diff --git a/doc/70-REST-API.md b/doc/70-REST-API.md index ee72a4b9..bb842756 100644 --- a/doc/70-REST-API.md +++ b/doc/70-REST-API.md @@ -508,3 +508,76 @@ Content-Type: application/json Please expect an error in case the host does not exist or has not been configured to be an Icinga Agent. + +### Self Service API + +#### Theory of operation + +Icinga Director offers a Self Service API, allowing new Icinga nodes to register +themselves. No credentials are required, authentication is based on API keys. +There are two types of such keys: + +* Host Template API keys +* Host Object API keys + +Template keys basically grant the permission to: + +* Create a new host based on that template +* Specify name annd address properties for that host + +This is a one-time operation and allows one to claim ownership of a specific host. +Now, there are two possible scenarios: + +* The host already exists +* The host is not known to Icinga Director + +In case the host already exists, Director will check whether it's API key matches +the given one. [..] + +#### Request processing for Host registration + +A new node will `POST` to `self-servie/register-host`, with two parameters in +the URL: + +* `name`: it's desired object name, usually the FQDN +* `key`: a valid Host Template API key + +In it's body it is allowed to specify a specific set of properties. At the time +of this writing, these are: + +* `display_name` +* `address` +* `address6` + +Director will validate the `key` and load the corresponding *Host Template*. In +case no such is found, the request is rejected. Then it checks whether a *Host* +with the given `name` exists. In case it does, the request is rejected unless: + +* It inherits the loaded *Host Template* +* It already has an API key + +If these conditions match, the request is processed. The following sketch roughly shows the decision tree (AFTER the key has been +validated): + +``` + +-----------------------------+ + +--------------+ | * Validate given properties | + | Host exists? | -- NO --> | * Create new host object |-----------+ + +--------------+ | * Return new Host API key | | + | +-----------------------------+ | + YES | + | | + v +-----------------------------+ | + +----------------------+ | * Validate given properties | | + | Host has an API key? | -- NO --> | * Apply eventual changes |----+ + +----------------------+ | * Return new Host API key | | + | +-----------------------------+ | + YES | + | +-------------------+ + v | + +--------------------+ v + | Reject the request | +---------------------+ + +--------------------+ | Client persists the | + | new Host API key | + +---------------------+ +``` diff --git a/doc/74-Self-Service-API.md b/doc/74-Self-Service-API.md new file mode 100644 index 00000000..7797a937 --- /dev/null +++ b/doc/74-Self-Service-API.md @@ -0,0 +1,55 @@ +Self Service API +============================================= + +Introduction +------------ + +Icinga Director offers a Self Service API, allowing new Hosts running the Icinga +Agent to register themselves in a secure way. + +### Windows Agents + +Windows Agents are the main target audience for this feature. It allows you to +generate a single Powershell Script based on the [Icinga 2 Powershell Module]( +https://github.com/Icinga/icinga2-powershell-module +). You can either use the same script for all of your Windows Hosts or generate +different ones for different kind of systems. + +This installation script could then be shipped with your base images, invoked +remotely via **PowerShell Remoting**, distributed as a module via **Group +Policies** and/or triggered via **Run-Once** (AD Policies). + +### Linux Agents + +At the time of this writing, we do not ship a script with all the functionality +you can find in the Windows Powershell script. Linux and Unix environments are +mostly highly automated these days, and such a magic shell script is often not +what people want. + +Still, you can also benefit from this feature by directly using our [Self Service +REST API](70-REST-API.md#Self Service API). It should be easy to integrate it into +the automation tool of your choice. + +Base Configuration +------------------ + +You have full control over the automation Script generated by the Icinga Director. +Please got to the **Infrastructure Dashboard** and choose the **Self Service API**: + +![Infrastructure Dashboard - Self Service API]( +screenshot/director/74_self-service-api/7401-director_self-service-dashboard.png +) + +This leads to the Self Service API Settings form. Most settings are self-explaining +and come with detailled inline hints. The most important choice is whether the +script should automatically install the Icinga Agent: + +![Settings - Choose installation source]( +screenshot/director/74_self-service-api/7402-director_self-service-choose-source.png +) + +In case you opted for automated installation, more options will pop up: + +![Settings - Installer Details]( +screenshot/director/74_self-service-api/7403-director_self-service-settings.png +) diff --git a/doc/screenshot/director/74_self-service-api/7401-director_self-service-dashboard.png b/doc/screenshot/director/74_self-service-api/7401-director_self-service-dashboard.png new file mode 100644 index 00000000..e9b54f51 Binary files /dev/null and b/doc/screenshot/director/74_self-service-api/7401-director_self-service-dashboard.png differ diff --git a/doc/screenshot/director/74_self-service-api/7402-director_self-service-choose-source.png b/doc/screenshot/director/74_self-service-api/7402-director_self-service-choose-source.png new file mode 100644 index 00000000..bbc7559d Binary files /dev/null and b/doc/screenshot/director/74_self-service-api/7402-director_self-service-choose-source.png differ diff --git a/doc/screenshot/director/74_self-service-api/7403-director_self-service-settings.png b/doc/screenshot/director/74_self-service-api/7403-director_self-service-settings.png new file mode 100644 index 00000000..b7d32267 Binary files /dev/null and b/doc/screenshot/director/74_self-service-api/7403-director_self-service-settings.png differ