Commit 1491291a authored by Thomas Gelf's avatar Thomas Gelf
Browse files

doc: add documentation, screenshots and meta data

parent 763ced62
......@@ -4,59 +4,7 @@ AWS module for Icinga Web 2
This is a simple AWS module. Currently it is nothing but an import source
provider for [Icinga Director](https://github.com/Icinga/icingaweb2-module-director).
Requirements
------------
![AWS module for Icinga Web 2](doc/img/00-overview.png)
This module needs the [AWS PHP SDK v2](http://docs.aws.amazon.com/aws-sdk-php/v2/guide/).
The newer v3 requires PHP 5.5, a version not available without 3rd party
(or SCL) repositories on many Enterprise Linux distributions as of this
writing. So to make life easier for many people we decided to work with
the older SDK.
Installation
------------
Please extract or clone this module to your Icinga Web 2 module path. The
directory name must fit the module name, `aws`. This would usually lead to
`/usr/share/icingaweb2/modules/aws`.
Next please download and extract the [latest v2](https://github.com/aws/aws-sdk-php/releases/download/2.8.30/aws.zip) standalone ZIP archive from
the AWS PHP SDK [releases](https://github.com/aws/aws-sdk-php/releases) page.
You need to extract the AWS PHP SDK v2 to `library/vendor/aws`.
The last required step is to provide at least one AWS access key in `keys.ini`.
Create a file `/etc/icingaweb2/modules/aws/keys.ini` as follows:
```ini
[My readonly AWS key]
access_key_id = RANDOMANFASDFNASDOFA
secret_access_key = WhatASDmn0asdnfASNDInafsdofdasJ980hansdf
```
That's it. Now you are ready to enable the AWS module and you'll find a new
Import Source in your Icinga Director frontend.
Proxy usage
-----------
In case your server needs to use a proxy when connection to the AWS web service
please create `/etc/icingaweb2/modules/aws/config.ini` with a `network` section
like shown in this example:
```ini
[network]
proxy = "192.0.2.192:3128"
```
You could also pass proxy credentials in the form `user:pass@host:port`.
SSL issues
----------
In case you need to provide a specific SSL CA bundle, once again please create
a `[network]` section in your `config.ini`:
```ini
[network]
ssl_ca = "/etc/ssl/certs/ca.pem"
```
Please read the [Installation and Configuration](doc/01-Installation-and-Configuration.md)
and [Usage](doc/02-Usage.md) sections to learn more about this module.
<a name="Installation-and-Configuration"></a>Installation
============
Requirements
------------
This module needs the [AWS PHP SDK v2](http://docs.aws.amazon.com/aws-sdk-php/v2/guide/).
The newer v3 requires PHP 5.5, a version not available without 3rd party
(or SCL) repositories on many Enterprise Linux distributions as of this
writing. So to make life easier for many people we decided to work with
the older SDK.
Module installation
-------------------
Please extract or clone this module to your Icinga Web 2 module path. The
directory name must fit the module name, `aws`. This would usually lead to
`/usr/share/icingaweb2/modules/aws`.
Download AWS SDK
----------------
Next please download and extract the [latest v2](https://github.com/aws/aws-sdk-php/releases/download/2.8.30/aws.zip) standalone ZIP archive from
the AWS PHP SDK [releases](https://github.com/aws/aws-sdk-php/releases) page.
You need to extract the AWS PHP SDK v2 to `library/vendor/aws`.
AWS key configuration
---------------------
The last required step is to provide at least one AWS access key in `keys.ini`.
Create a file `/etc/icingaweb2/modules/aws/keys.ini` as follows:
```ini
[My readonly AWS key]
access_key_id = RANDOMANFASDFNASDOFA
secret_access_key = WhatASDmn0asdnfASNDInafsdofdasJ980hansdf
```
That's it. Now you are ready to enable the AWS module and you'll find a new
Import Source in your Icinga Director frontend. You are now ready to skip to
the [Usage](02-Usage.md) section.
Proxy usage
-----------
In case your server needs to use a proxy when connection to the AWS web service
please create `/etc/icingaweb2/modules/aws/config.ini` with a `network` section
like shown in this example:
```ini
[network]
proxy = "192.0.2.192:3128"
```
You could also pass proxy credentials in the form `user:pass@host:port`.
SSL issues
----------
In case you need to provide a specific SSL CA bundle, once again please create
a `[network]` section in your `config.ini`:
```ini
[network]
ssl_ca = "/etc/ssl/certs/ca.pem"
```
<a id="Usage"></a>Usage
=====
Dynamically create hosts for AWS AutoScaling Groups
---------------------------------------------------
Our first use case are virtual Icinga host objects, one for each of your AWS
AutoScaling Group. Single instances come and go, it's tricky to monitor them
in a meaningful way. Your AutoScaling Groups are here to stay, it is vital for
your service that they are alive.
This example wants to teach you how to configure Director to automagically do
this for you.
### Create a new host template
I'd strongly suggest to create a dedicated template that should be inherited
by all your virtual AWS ASG hosts. This allows you to add service checks to
the template, with the Director automagically deploying them as apply rules
affecting all your ASG hosts.
![AWS host template](img/01_aws_template.png)
Whether you use a dummy host check or a plugin running against the AWS API is
up to your personal preference.
### Define a dedicated Import Source
As soon as you installed and enabled this module, a new Import Source will be
available in your Icinga Director web frontend:
![AWS import source basics](img/02_aws_import_source_basics.png)
You can choose your AWS region from a dropdown:
![AWS import source region](img/03_aws_import_region.png)
It is also necessary to choose one of your AWS keys:
![AWS import source key](img/04_aws_import_source_key.png)
In case this list is empty, please check back to the [Installation and Configuration](01-Installation-and-Configuration.md)
section. Now you are ready to preview and/or run your first import. Don't
worry, nothing bad will happen. An Import run just imports plain data from
your import source, it won't touch any of your hosts or services in your
Icinga Director.
### Create a Sync Rule
Our Sync Rules are responsible for creating real Icinga objects based on
data imported through one or more Import Sources. So let's create a new
rule:
![AWS sync rule](img/05_aws_sync_rule.png)
Sync Properties allow you to specify how to treat the various properties
in a granular way:
![AWS sync properties](img/06_aws_sync_properties.png)
Now you are ready to trigger your first Sync Run. Activity Log and Sync History
will show you what related actions took place
### Have a look at your new hosts
Let's have a look at our newly created host:
![AWS host config](img/07_aws_host_config.png)
In case you want to achieve visibilty for your imported Custom Vars please
define related Fields directly on your AWS ASG Template. Your hosts could
then look as follows:
![AWS host vars](img/08_aws_host_config_with_vars.png)
The preview tab shows our rendered host, this is how it will get deployed
to Icinga:
![AWS host preview](img/09_aws_host_preview.png)
That's all for now, have fun!
Name: AWS
Version: 0.0.1
Depends: monitoring
Description: Amazon Web Services module for Icinga Web 2
This module provides an AWS SDK import source for Icinga Director
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment