From 8f898793d8cfc112599ea3a3daaddff063448c38 Mon Sep 17 00:00:00 2001 From: Vnaumov Date: Thu, 22 Mar 2018 15:43:56 +0400 Subject: [PATCH] update documentation, related to additional services - 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 https://github.com/Mirantis/kqueen/pull/246 --- RATIONALE.md | 1 - docs/kqueen.rst | 297 +++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 284 insertions(+), 14 deletions(-) diff --git a/RATIONALE.md b/RATIONALE.md index 27c6de01..0c012531 100644 --- a/RATIONALE.md +++ b/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 - diff --git a/docs/kqueen.rst b/docs/kqueen.rst index d041ba99..0bc98b5b 100644 --- a/docs/kqueen.rst +++ b/docs/kqueen.rst @@ -152,26 +152,297 @@ in the configuration file, set the environment variable matching the KQUEEN_>@<>.<> + + For example user ``kqueen@mirantis.com`` should be equal to LDAP entry: ``cn=kqueen, dc=mirantis, dc=com`` + +Users with superadmin rights can also manage member roles. + +To set up metrics collecting +----------------------------------- + +1. Open the docker-compose.production.yml file for editing. +2. Configure the Prometheus service IP address, port, and volumes. For example: + +.. code-block:: yaml + + prometheus: + image: prom/prometheus + restart: always + ports: + - 127.0.0.1:9090:9090 + volumes: + - ./prod/prometheus/:/etc/prometheus/:Z + - /mnt/storage/kqueen/prometheus/:/prometheus/ + links: + - api + - etcd +3. Define the Prometheus scraper IP address in the KQueen API service section: + +.. code-block:: yaml + + KQUEEN_PROMETHEUS_WHITELIST: '172.16.238.0/24' + +The metrics can be obtained using the KQueen API or Prometheus API: + +* Kqueen API: + +.. code-block:: bash + + TOKEN=$(curl -s -H "Content-Type: application/json" --data '{"username":"admin","password":"default"}' -X POST <>:5000/api/v1/auth | jq -r '.access_token'); echo $TOKEN + curl -H "Authorization: Bearer $TOKEN" <>:5000/metrics/ + + +* Prometheus API: + + 1. Add the scraper IP address to ``PROMETHEUS_WHITELIST`` configuration. + 2. Run the following command: + + .. code-block:: bash + + curl <>:<>/metrics + + +All application metrics are exported to the **/metrics** API endpoint. Any external Prometheus instance can then scrape this metric. + + +Provision a Kubernetes cluster +------------------------------ + +You can provision a Kubernetes cluster using various community of engines, such as Google Kubernetes engine or Azure Kubernetes Service. + + +To provision a Kubernetes cluster using the Google Kubernetes Engine: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Login in to the Google Kubernetes Engine (https://console.cloud.google.com). +2. Select your Project. +3. Navigate to the ``API’s & Services`` -> ``Credentials`` tab and click ``Create credentials``. +4. From ``Service Account key``, select your service account. +5. Select Json as the key format. +6. Download the Json snippet. +7. Log in to the KQueen web UI. +8. From the ``Create Provisioner`` tab, select ``Google Kubernetes Engine``. +9. Specify your project ID (``Project info`` tab on the main page of the GCE Dashboard https://console.cloud.google.com). +10. Insert the downloaded Json snippet that contains the service account key and submit the provisioner creation. +11. Click ``Deploy Cluster``. +12. Select the defined GCE provisioner. +13. Specify the cluster requirements. +14. Click ``Submit``. +15. To track the cluster status, navigate to the KQueen main dashboard. + +To provision a Kubernetes cluster using the Azure Kubernetes Service: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Log in to https://portal.azure.com. +2. Create an Azure Active Directory Application as described in the official Microsoft `Documentation `_. +3. Copy the Application ID, Application Secret, Tenant ID (Directory ID), and Subscription ID to use in step 8. +4. Set the ``Owner`` role to your Application in the Subscription settings to enable the creation of Kubernetes clusters. +5. Navigate to the ``Resource groups`` tab and create a resource group. Copy the ‘Resource group name’ to use in step 8. +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 step 3. + 2. Set the ``Resource group name`` as Resource group name from step 4. + 3. Set the ``Secret`` as Application Secret from step 3. + 4. Set the ``Subscription ID`` as Subscription ID from step 3. + 5. Set the ``Tenant ID`` as Tenant(Directory) ID from step 3. +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, assign the public IP address to the VM as described in `guide `_). Once done, use foollowing command: ``ssh azureuser@<> -i .ssh/your_defined_id_rsa``. +13. Click ``Submit``. +14. To track the cluster status, navigate to the KQueen main dashboard. + + +.. 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 `_. + +.. 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 `Issues `_, and https://docs.microsoft.com/en-us/azure/aks/faq#why-are-two-resource-groups-created-with-aks. + + +To manually add an existing Kubernetes cluster: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Log in to the KQueen web UI. +2. Create ``Manual Provisioner``. +3. In the ``Create Cluster`` tab choose predefined manual provisioner and attach a valid Kubernetes configuration file. +As a result, the Kubernetes cluster will be attached in a read-only mode. + + +Backup and recovery ETCD +------------------------ + +Etcd is the only stateful component of KQueen. To recover etcd in case of a failure, follow the procedure described in https://coreos.com/etcd/docs/latest/v2/admin_guide.html#disaster-recovery. + +.. note:: -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: + The ``v2`` etcd keys are used in deployment. -:: +Example of etcd backup workflow: - # Backup etcd to directory /root/backup/ (etcd data stored in /var/lib/etcd/default) - etcdctl backup --data-dir /var/lib/etcd/default --backup-dir /root/backup/ + .. code-block:: bash -Recovery + # Backup etcd to directory /root/backup/ (etcd data stored in /var/lib/etcd/default) + etcdctl backup --data-dir /var/lib/etcd/default --backup-dir /root/backup/ -:: - # Move data to etcd directory - mv -v /root/backup/* /var/lib/etcd/default/ +Example of etcd recovery workflow: - # Start new etcd with these two extra parameters (among the other) - # for example: etcd --force-new-cluster + .. code-block:: bash + # Move data to etcd directory + mv -v /root/backup/* /var/lib/etcd/default/ -kqueen + # Start new etcd with these two extra parameters (among the other) + # for example: etcd --force-new-cluster