update documentation, related to additional services

- mail service attach
- prometheus service attach
- cloud providers settings

Pay attention, than there is no Nginx-service default configuration, it depends on
#246

RATIONALE.md

@@ -65,4 +65,3 @@ KQueen supplies the backend API for provider-agnostic cluster management. It ena
 * **Update** - install newer version of Kubernetes
 * **Autoscale** - watch Kubernetes scheduler or pods and start new minions when all existing minions are fully utilized
 * **Manage addons** - enable or disable cluster addons
-

docs/kqueen.rst

@@ -153,6 +153,110 @@ in the configuration file, set the environment variable matching the KQUEEN_<con
       - Addresses allowed to access metrics endpoint without token
 
 
+External services deployment
+-------
+1. **Members managing** - To provide user registration by invitations from other users by emails, mail server should be set up. 
+It is possible to use kqueen predefined mail service or to run new one. Example configuration mail service in docker-compose.production.yml:
+
+.. code-block:: yaml
+   mail:
+     image: modularitycontainers/postfix
+     volumes:
+       - /var/spool/postfix:/var/spool/postfix
+       - /var/mail:/var/spool/mail
+     environment:
+       MYHOSTNAME: 'mail'
+
+Configure following variables in kqueen ui service:
+
+.. code-block:: yaml
+   KQUEENUI_MAIL_SERVER: mail
+   KQUEENUI_MAIL_PORT: 10025
+
+Pay attention that volume-mapping for mail containers is additional feature. It used for store mailing history and forward additional postfix mail configuration (it should configured properly on local machine),
+otherwise its possible to run mail server without volume-mapping. After all configuration steps, user should invite members using email notification. Member should receive mail with activation link to Kqueen service and possibility of password-setting.
+Superadmin also can manage member roles.
+
+2. **Metrics collecting** - Its possible to add external Prometheus serveri to extend monitoring in Kqueen. In case of using external server, need to include rules from kqueen/prod/prometheus into existing Prometheus service. Otherwise, its possible to use predefined Prometheus, defined in docker-compose.production.yml.
+Configure prometheus service (ip address/port, volumes) in docker-compose.production.yml. Define  scraper IP address for PROMETHEUS_WHITELIST variable in kqueen api service section.
+All application metrics exported on **/metrics** and this metric can scraped by any external Prometheus instance. There two ways to authenticate to get this endpoint:
+
+- Kqueen API
+.. code-block:: bash
+   TOKEN=$(curl -s -H "Content-Type: application/json" --data '{"username":"admin","password":"default"}' -X POST <<kqueen_api_host>>:5000/api/v1/auth | jq -r '.access_token'); echo $TOKEN
+   curl -H "Authorization: Bearer $TOKEN" <<kqueen_api_host>>:5000/metrics/
+
+
+- Prometheus API
+Add scraper IP address to PROMETHEUS_WHITELIST configuration and then:
+
+.. code-block:: bash
+   curl <<prometheus_host>>:<<prometheus_port>>/metrics
+
+
+Provisioner configuration settings
+-------
+
+* **Google Kubernetes Engine**
+
+1. Register account on GCE (https://console.cloud.google.com)
+2. Create your project
+3. Go to ```API’s & Services```  tab
+4. Go ```Credentials``` tab
+5. Click ```Create credentials```
+6. Choose ```Service Account key```
+7. Choose your Service account
+8. Choose Json format for key
+9. Download it
+10. On Kqueen UI choose ```Create Provisioner```
+11. Choose ```Google Kubernetes Engine```
+12. Insert your project ID (```Project info``` tab on the main page of GCE Dashboard https://console.cloud.google.com )
+13. Insert downloaded Json snippet, which contains key and submit provisioner creation
+14. On Kqueen UI choose ```Deploy Cluster```
+15. Choose defined GCE provisioner
+16. Specify cluster requirements
+17. Click ```Submit```
+18. Watch for cluster status from Kqueen main dashboard
+
+* **Azure Kubernetes Service**
+
+1. Login into https://portal.azure.com with your azure account
+2. Follow official Microsoft guide https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal#create-an-azure-active-directory-application
+3. Get Application ID, Application Secret, Tenant ID (Directory ID), Subscription ID
+4. Pay attention to set ‘Owner’ role to your Application in Subscription settings to provide possibility of creating k8s clusters. (see latest steps in p.2). Save Application secret manually, because it will be unavailable from Azure Web UI after generating.
+5. Create Resource group from ‘Resource groups’ tab and get ‘Resource group name’
+6. Check that Application had ‘Owner’ role in Resource group. (go to ‘Resource groups’ -> your_group -> Access Control(IAM))
+7. Go to Kqueen ‘Create provisioner’ tab and choose AKS engine
+8. Set ‘Client ID’ as Application ID from p.3
+9. Set ‘Resource group name’ as ‘Resource group name’ from p.4
+10 Set ‘Secret’ as Application Secret from p.3
+11. Set ‘Subscription ID’ as  Subscription ID from p.3
+12. Set ‘Tenant ID’ as Tenant(Directory) ID from p.3
+13. On Kqueen UI choose ```Deploy Cluster```
+14. Choose defined AKS provisioner
+15. Specify cluster requirements
+16. Specify public ssh key for connect to AKS vm’s *
+17. Click ```Submit```
+18. Watch for cluster status from Kqueen main dashboard
+
+**Pay attention** that Admin Console in Azure portal supported properly only in IE and Microsoft Edge, and may fail in Safari, Opera, Chrome, Firefox due MIcrosoft issues, like
+https://microsoftintune.uservoice.com/forums/291681-ideas/suggestions/18602776-admin-console-support-on-mac-osx
+
+**Pay attention** that AKS created separate resource during cluster creating (it used defined RG as prefix ). It may affect your billing. For ex.:
+Your group : Kqueen
+Cluster-generated RG: MC_Kqueen_44a37a65-1dff-4ef8-97ca-87fa3b8aee62_eastus
+Referenced to  https://github.com/Azure/AKS/issues/3
+Docs: https://docs.microsoft.com/en-us/azure/aks/faq#why-are-two-resource-groups-created-with-aks
+
+**Pay attention** for connect to AKS vm’s, need to:
+- assign public ip address to vm (example: https://gist.github.com/naumvd95/576d6e48200597ca89b26de15e8d3675)
+- define valid public ssh key in p.8
+- ssh azureuser@<<public_ip>> -i .ssh/your_defined_id_rsa
+
+
+* **Manual engine for attach existing clusters**
+ Define valid kubernetes configuration file in ```Create Cluster``` tab to attach existing Kubernetes cluster in read-only mode.
+
 Backup
 -------