Update documentation, related to additional services #255

naumvd95 · 2018-03-22T11:46:16Z

mail service attach
ldap service attach
prometheus service attach
cloud providers settings
Nginx-service default configuration

atengler · 2018-03-22T12:04:01Z

Can you add someone who can check english grammar as reviewer?

naumvd95 · 2018-03-22T12:05:14Z

@atengler @mzlatkova should check this

mzlatkova

This doc describes the KQueen principles. I believe it's better to create a separate doc for configuration procedures.

naumvd95 · 2018-03-22T12:15:04Z

@mzlatkova good idea, and what do u think, maybe its better to post it only on readthedocs.io?

naumvd95 · 2018-03-22T12:16:13Z

@atengler @tomkukral what do u think about it?

mzlatkova · 2018-03-22T12:23:38Z

@naumvd95 Yes, I think that would be better.

katyafervent

Please, reformat document structure (section with steps for provisioner adding)

katyafervent · 2018-03-22T12:21:17Z

RATIONALE.md

@@ -65,4 +65,102 @@ 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
-
+* **Members managing** - Its possible to define own mail server or use default to provide user registering into Kqueen.


what is own and default mail servers are not really clear. Need to add some clarification as:
--> To provide user registration by invitations from other users by emails, mail server should be set up. it is possible to use already existing mail service or to run new one.

katyafervent · 2018-03-22T12:25:24Z

RATIONALE.md

+  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.


I suggest to move last to sentences to the top of this section, to clarify to the user why mail server is needed at all

katyafervent · 2018-03-22T12:26:36Z

RATIONALE.md

+```
+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.


Do we need to add here, that superadmin can invite admins also?

katyafervent · 2018-03-22T12:28:28Z

RATIONALE.md

+# Download it
+# On Kqueen UI choose ```Create Provisioner```
+# Choose ```Google Kubernetes Engine```
+# Insert your project ID (```Project info``` tab on the main page of GCE Dashboard https://console.cloud.google.com )


In the last code version project ID is not required anymore, only ssh key

katyafervent · 2018-03-22T12:35:22Z

RATIONALE.md

+
+* **Google Kubernetes Engine**
+
+# Register account on GCE (https://console.cloud.google.com)


All your # is a first-level headers, did you want to * instead?
Also I suggest to remove * from * Google Kubernetes Engine and add to the list of provided steps, smth like:

Provisioner configuration settings ## -2d level section

Google Kubernetes Engine ### -3d level section

Register

mzlatkova

Please add some intro and restructure the content. Will add more comments later.

mzlatkova · 2018-03-22T14:22:50Z

docs/kqueen.rst

+   curl <<prometheus_host>>:<<prometheus_port>>/metrics
+
+
+Provisioner configuration settings


Provision a Kubernetes cluster?

Please add an intro, for example:

You can provision a Kubernetes cluster using various community installers or provisioners, such as ...

Provision a Kubernetes cluster using the Google Kubernetes Engine:
1.
2.
3.

Provision a Kubernetes cluster using the Azure Kubernetes Service:
1.
2.
3.

...

mzlatkova · 2018-03-22T14:22:55Z

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
+-------


An intro needed. For example:

Before you provision a Kubernetes cluster, you may need to deploy and configure the following external services:

Members management (describe the details)

Metrics collecting (describe the details)

To set up members management:

To set up metrics collecting:

mzlatkova · 2018-03-22T14:23:02Z

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


Deploy external services

katyafervent · 2018-03-23T13:51:49Z

docs/kqueen.rst

+
+External services deployment
+-------
+* **Members managing** - To provide user registration by invitations from other users by emails, mail server should be set up.


To provide user registration by invitations from other users by emails --> To provide user registration by emails invitations from other users.

katyafervent · 2018-03-23T13:53:02Z

docs/kqueen.rst

+* **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.
+
+* **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.


serveri -> server

in docker-compose.production.yml <https://github.com/Mirantis/kqueen/blob/master/docker-compose.production.yml>_

katyafervent · 2018-03-23T13:57:55Z

docs/kqueen.rst

+.. code-block:: yaml
+   KQUEEN_PROMETHEUS_WHITELIST: '172.16.238.0/24'
+
+There two ways to get metrics:


There two -> there are two

katyafervent · 2018-03-26T09:41:23Z

docs/kqueen.rst

+
+**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


Follow official Microsoft guide --> need to add aim of following that guide, user should understand why this guide is needed at all in this instruction. I suggest to combine p2 and p3, smth like:
To be able to connect kqueen and Azure Application ID, Application Secret, Tenant ID (Directory ID), Subscription ID are required. Please, follow ... to find those entities.

katyafervent · 2018-03-26T09:54:57Z

docs/kqueen.rst

+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))


check -> if there are no owner role in your resource group, please add it at ‘Resource groups’ -> your_group -> Access Control(IAM) or smth like that

katyafervent · 2018-03-26T10:21:03Z

docs/kqueen.rst

+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


Set ‘Client ID’ as Application ID --> set application id as 'Client ID', since before in the instruction we deal only with app id

atengler · 2018-03-26T12:53:35Z

docker-compose.demo.yml

@@ -1,7 +1,8 @@
 version: '2'
 services:
  api:
-    image: kqueen/api:v0.18
+#    image: kqueen/api:v0.18
+    image: vnaumov/kqueen-api:mk1
    ports:


Is this intentional? This looks like local image

katyafervent

Please, remove changes in docker compose and fix headers formatting.

katyafervent · 2018-03-26T13:28:46Z

docs/kqueen.rst


-
-Backup
+**To set up the mail server**
 -------


Remove ** from header and set ------- length equal to the text length so all formatting will be done automatically.
And for all headers below do the same, please.

katyafervent · 2018-03-27T08:12:57Z

docs/kqueen.rst

+
+.. note::
+
+   The Admin Console in the Azure portal is supported only in Internet Explorer and Microsoft Edge and may fail to operate in other browsers due to Microsoft issues such as


to Microsoft issues <https://microsoftintune.uservoice.com/forums/291681-ideas/suggestions/18602776-admin-console-support-on-mac-osx/>_.

katyafervent · 2018-03-27T08:15:15Z

docs/kqueen.rst

+
+
+
+** To manually add an existing Kubernetes cluster:**


remove ** and make it sub header with
To manually add an existing Kubernetes cluster
~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
and add empty line

mzlatkova · 2018-03-27T09:12:40Z

docs/kqueen.rst


-The only one statefull component of Kqueen is the etcd and users should follow https://coreos.com/etcd/docs/latest/v2/admin_guide.html#disaster-recovery. We are using `v2` etcd keys so example backup workflow can be:
+* Nginx proxy server, to configure ssl support, domain naming and define certificates.


NGINX proxy server, to configure SSL support, domain naming, and to define certificates.

mzlatkova · 2018-03-27T09:13:00Z

docs/kqueen.rst


-Recovery
+To set up the nginx server


To set up the NGINX server:

mzlatkova · 2018-03-27T09:13:13Z

docs/kqueen.rst

+To set up the nginx server
+--------------------------
+
+1. Configure variables in '.env' file from Nginx section:


Open the '.env' file for editing.

Configure the variables the Nginx section:

mzlatkova · 2018-03-27T09:13:25Z

docs/kqueen.rst

+      NGINX_SSL_CERTIFICATE_DIR=/mnt/letsencrypt
+
+2. Open the docker-compose.production.yml file for editing.
+3. Check proxy service configuration in docker-compose.production.yml. Pay attention on following variables:


Verify the proxy service configuration. Pay attention to the following variables:

mzlatkova · 2018-03-27T09:14:15Z

docs/kqueen.rst

+2. Open the docker-compose.production.yml file for editing.
+3. Check proxy service configuration in docker-compose.production.yml. Pay attention on following variables:
+
+  1. ``VHOSTNAME`` - domain name for Kqueen service. Should be equal with domain name in generated certificates. Default: Using variable from .env file, named NGINX_VHOSTNAME


VHOSTNAME, the domain name for the KQueen service. Should be the same as the domain name in the generated certificates. By default, the NGINX_VHOSTNAME from the .env file is used.

SSL_CERTIFICATE_DIR, the mapped directory for certificates forwarding into a docker container. By default. the NGINX_SSL_CERTIFICATE_DIR/NGINX_VHOSTNAME variable from the .env fil is used.

SSL_CERTIFICATE_PATH , the path for the cert+key certificate. The default is $SSL_CERTIFICATE_DIR/fullchain.cer.

SSL_CERTIFICATE_KEY_PATH, the path for the certificate key. The default is $SSL_CERTIFICATE_DIR/$VHOSTNAME.key.

SSL_TRUSTED_CERTIFICATE_PATH, the path for the certificate. The default is $SSL_CERTIFICATE_DIR/ca.cer

mzlatkova · 2018-03-27T09:18:43Z

docs/kqueen.rst

+6. From the to ``Resource groups`` -> your_group -> Access Control (IAM) tab, verify that the Application has the ``Owner`` role in Resource group.
+7. Log in to the KQueen web UI.
+8. From the ``Create provisioner`` tab, select the AKS engine and set the following:
+	1. Set the ``Client ID`` as Application ID from p.3.


p.3 --> step 3.
(please change below as well)

mzlatkova · 2018-03-27T09:18:59Z

docs/kqueen.rst

+
+   The Admin Console in the Azure portal is supported only in Internet Explorer and Microsoft Edge and may fail to operate in other browsers due to Microsoft `issues <https://microsoftintune.uservoice.com/forums/291681-ideas/suggestions/18602776-admin-console-support-on-mac-osx>`_.
+
+**Pay attention** that AKS created separate resource during kubernetes cluster creating (it used defined Resource Group as prefix ). It may affect your billing. For ex.:


.. note::

The AKS creates a separate resource during the creation of a Kubernetes cluster and uses the defined Resource Group as a prefix. This may affect your billing. For example:
.. code-block:: text

Your Resource Group : Kqueen Additional cluster-generated Resource Group: MC_Kqueen_44a37a65-1dff-4ef8-97ca-87fa3b8aee62_eastus

For more information, see Azure/AKS#3 and https://docs.microsoft.com/en-us/azure/aks/faq#why-are-two-resource-groups-created-with-aks.

mzlatkova · 2018-03-27T09:19:13Z

docs/kqueen.rst

+As a result, the Kubernetes cluster will be attached in a read-only mode.
+
+
+ETCD Backup


Etcd backup and recovery

mzlatkova · 2018-03-27T09:20:32Z

docs/kqueen.rst

+
+   The ``v2`` etcd keys are used in deployment.
+
+Example of a backup and recovery workflow:


Example of etcd backup workflow:

mzlatkova · 2018-03-27T09:20:49Z

docs/kqueen.rst

+         etcdctl backup --data-dir /var/lib/etcd/default --backup-dir /root/backup/
+
+
+Recovery


Example of etcd recovery workflow:

atengler · 2018-03-27T16:13:11Z

@mzlatkova @katyafervent Can you re-review? It seems that change requests were addressed

mzlatkova · 2018-03-27T16:26:40Z

docs/kqueen.rst

+
+   Volume-mapping for mail containers is an additional feature that enables storing the mailing history and forwards an additional postfix mail configuration. You must properly configure it on the local machine. Otherwise, you can run the mail server without volume-mapping.
+
+To set up metrics collecting


Either make it:
To set up metrics collecting:

Or: Set up metrics collecting --------------------------------

mzlatkova · 2018-03-27T16:28:56Z

docs/kqueen.rst

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Log in to the KQueen web UI.
+1. Create ``Manual Provisioner``.


This list is broken

mzlatkova · 2018-03-27T16:31:17Z

docs/kqueen.rst

+
+   Volume-mapping for mail containers is an additional feature that enables storing the mailing history and forwards an additional postfix mail configuration. You must properly configure it on the local machine. Otherwise, you can run the mail server without volume-mapping.
+
+To set up metrics collecting


The same for lines 210 and 164.

mzlatkova · 2018-03-27T16:32:01Z

docs/kqueen.rst

+As a result, the Kubernetes cluster will be attached in a read-only mode.
+
+
+ETCD Backup and recovery


Back up and recover etcd

mzlatkova · 2018-03-27T16:32:24Z

docs/kqueen.rst


-::
+Example of a backup workflow:


Example of etcd backup workflow:

mzlatkova · 2018-03-27T16:35:51Z

docs/kqueen.rst

+9. In the KQueen web UI, click ``Deploy Cluster``.
+10. Select the AKS provisioner.
+11. Specify the cluster requirements.
+12. Specify the public SSH key to connect to AKS VM’s. For ssh access into created VM’s, need to  assign the public IP address to the VM (follow example `guide <https://gist.github.com/naumvd95/576d6e48200597ca89b26de15e8d3675>`_). Then it is possible to ``ssh azureuser@<<public_ip>> -i .ssh/your_defined_id_rsa``


Make this a note or a separate step. Should this be done before step 12?
For SSH access to the created VM’s, assign the public IP address to the VM as described in guide <https://gist.github.com/naumvd95/576d6e48200597ca89b26de15e8d3675>_). Once done, use the following command: ssh azureuser@<<public_ip>> -i .ssh/your_defined_id_rsa.

- mail service attach - ldap service attach - proxy service attach - prometheus service attach - cloud providers settings Pay attention, than there is no Nginx-service default configuration, it depends on #246

naumvd95 requested review from mikezuniga, katyafervent, tomkukral and atengler March 22, 2018 12:04

mzlatkova reviewed Mar 22, 2018

View reviewed changes

katyafervent suggested changes Mar 22, 2018

View reviewed changes

naumvd95 force-pushed the kqueen-docs branch 2 times, most recently from c981eb2 to 53b5c71 Compare March 22, 2018 13:39

mzlatkova suggested changes Mar 22, 2018

View reviewed changes

naumvd95 force-pushed the kqueen-docs branch from 53b5c71 to 49d1004 Compare March 23, 2018 12:44

katyafervent reviewed Mar 23, 2018

View reviewed changes

atengler previously approved these changes Mar 23, 2018

View reviewed changes

katyafervent reviewed Mar 26, 2018

View reviewed changes

naumvd95 force-pushed the kqueen-docs branch from 49d1004 to 48eb860 Compare March 26, 2018 11:46

atengler reviewed Mar 26, 2018

View reviewed changes

katyafervent suggested changes Mar 26, 2018

View reviewed changes

naumvd95 force-pushed the kqueen-docs branch from 48eb860 to 3014904 Compare March 26, 2018 14:24

katyafervent reviewed Mar 27, 2018

View reviewed changes

naumvd95 force-pushed the kqueen-docs branch 4 times, most recently from 5307d4d to 5240636 Compare March 27, 2018 08:42

naumvd95 force-pushed the kqueen-docs branch 2 times, most recently from 204606f to 4edcc8b Compare March 27, 2018 08:46

mzlatkova suggested changes Mar 27, 2018

View reviewed changes

naumvd95 force-pushed the kqueen-docs branch 2 times, most recently from 722248f to 80b0075 Compare March 27, 2018 10:08

mzlatkova reviewed Mar 27, 2018

View reviewed changes

katyafervent previously approved these changes Mar 28, 2018

View reviewed changes

naumvd95 force-pushed the kqueen-docs branch 2 times, most recently from ccc9df8 to 8f89879 Compare April 2, 2018 12:58

mzlatkova approved these changes Apr 2, 2018

View reviewed changes

naumvd95 force-pushed the kqueen-docs branch from 8f89879 to ad95ba7 Compare April 3, 2018 14:01

naumvd95 dismissed stale reviews from katyafervent and atengler via a82c98e April 4, 2018 10:06

naumvd95 force-pushed the kqueen-docs branch from ad95ba7 to a82c98e Compare April 4, 2018 10:06

katyafervent previously approved these changes Apr 4, 2018

View reviewed changes

katyafervent changed the title ~~update documentation, related to additional services~~ Update documentation, related to additional services Apr 4, 2018

naumvd95 dismissed katyafervent’s stale review via 595b81c April 5, 2018 15:54

naumvd95 force-pushed the kqueen-docs branch from a82c98e to 595b81c Compare April 5, 2018 15:54

update documentation, related to additional services

4d19eb9

- mail service attach - ldap service attach - proxy service attach - prometheus service attach - cloud providers settings Pay attention, than there is no Nginx-service default configuration, it depends on #246

naumvd95 force-pushed the kqueen-docs branch from 595b81c to 4d19eb9 Compare April 6, 2018 10:17

atengler approved these changes Apr 6, 2018

View reviewed changes

atengler merged commit 7191e0d into master Apr 6, 2018

ekhomyakova deleted the kqueen-docs branch June 26, 2018 09:56


		* Google Kubernetes Engine

		# Register account on GCE (https://console.cloud.google.com)

		curl <<prometheus_host>>:<<prometheus_port>>/metrics


		Provisioner configuration settings

		@@ -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


		.. note::

		The Admin Console in the Azure portal is supported only in Internet Explorer and Microsoft Edge and may fail to operate in other browsers due to Microsoft issues such as


		The only one statefull component of Kqueen is the etcd and users should follow https://coreos.com/etcd/docs/latest/v2/admin_guide.html#disaster-recovery. We are using `v2` etcd keys so example backup workflow can be:
		* Nginx proxy server, to configure ssl support, domain naming and define certificates.


		The Admin Console in the Azure portal is supported only in Internet Explorer and Microsoft Edge and may fail to operate in other browsers due to Microsoft `issues <https://microsoftintune.uservoice.com/forums/291681-ideas/suggestions/18602776-admin-console-support-on-mac-osx>`_.

		Pay attention that AKS created separate resource during kubernetes cluster creating (it used defined Resource Group as prefix ). It may affect your billing. For ex.:

		As a result, the Kubernetes cluster will be attached in a read-only mode.


		ETCD Backup


		The ``v2`` etcd keys are used in deployment.

		Example of a backup and recovery workflow:

		etcdctl backup --data-dir /var/lib/etcd/default --backup-dir /root/backup/


		Recovery


		Volume-mapping for mail containers is an additional feature that enables storing the mailing history and forwards an additional postfix mail configuration. You must properly configure it on the local machine. Otherwise, you can run the mail server without volume-mapping.

		To set up metrics collecting

Update documentation, related to additional services #255

Update documentation, related to additional services #255

Conversation

naumvd95 commented Mar 22, 2018 • edited Loading

atengler commented Mar 22, 2018

naumvd95 commented Mar 22, 2018

mzlatkova left a comment

Choose a reason for hiding this comment

naumvd95 commented Mar 22, 2018

naumvd95 commented Mar 22, 2018

mzlatkova commented Mar 22, 2018

katyafervent left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Provisioner configuration settings ## -2d level section

Google Kubernetes Engine ### -3d level section

mzlatkova left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

katyafervent left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

katyafervent Mar 27, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

atengler commented Mar 27, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

naumvd95 commented Mar 22, 2018 •

edited

Loading

katyafervent Mar 27, 2018 •

edited

Loading