Merge pull request #127 from quirky4/server_tags_doc

[ePortal] add documentation for server tags

Author: annkots

docs/.vuepress/public/images/tag_assignment.png

@@ -563,6 +563,35 @@ Example:
         force_basic_auth: yes
 ```
 
+Example of server tagging:
+
+```json
+- hosts: kernelcare
+  vars:
+    eportal_srv: http://192.168.246.110
+    eportal_tags: 'staging;location:Boston'
+  tasks:
+    - name: get systemid content
+      slurp:
+        src: /etc/sysconfig/kcare/systemid
+      register: systemid_file
+
+    - name: set server_id
+      set_fact:
+        eportal_server_id: "{{ systemid_file.content | b64decode | trim | regex_replace('^server_id=(\\w+)$', '\\1') }}"
+
+    - name: set server tags using ePortal API
+      uri:
+        url: '{{ eportal_srv }}/admin/api/set_tags'
+        method: POST
+        headers:
+          X-Api-Key: '{{ lookup("env", "EPORTAL_API_TOKEN") }}'
+        body_format: form-urlencoded
+        body:
+          server_id: '{{eportal_server_id }}'
+          tags: '{{ eportal_tags }}'
+```
+
 Ad hoc run with:
 
 ```
@@ -613,6 +642,28 @@ http_request "kernelcare-unregister-api" do
 end
 ```
 
+Example of server tagging (kernelcare-tag-server.rb):
+
+```json
+eportal_url = "http://192.168.246.110"
+eportal_api_key = "Lgk5-qWeBypejSEc6nYmalGbv11Kh_OyWi2_vigrTro"
+tags = "staging;location:Boston"
+
+ruby_block 'get-server-id' do
+  block do
+    node.run_state['server_id'] = File::read('/etc/sysconfig/kcare/systemid').gsub(/server_id=(\w+)\s*/, '\1')
+  end
+  action :run
+end
+
+http_request 'kernelcare-set-server-tags' do
+  url "#{eportal_url}/admin/api/set_tags"
+  action :post
+  message lazy {{'server_id' => "#{node.run_state['server_id']}", 'tags' => tags}.to_json}
+  headers({'X-Api-Key' => eportal_api_key, 'Content-Type' => 'application/json'})
+end
+```
+
 Ad hoc run with:
 
 ```
@@ -671,6 +722,20 @@ fi
 curl -kL -u "${EPORTAL_API_PASSWORD}"':'"${EPORTAL_API_PASSWORD}" -X POST "${EPORTAL_URL}"'/admin/api/delete_server?ip='"${IP_TO_UNREGISTER}"
 ```
 
+Example of server tagging (tag_server.sh)
+
+```
+#!/bin/bash
+
+EPORTAL_URL='http://192.168.246.110'
+EPORTAL_TAGS='staging;location:Boston'
+EPORTAL_API_KEY='Lgk5-qWeBypejSEc6nYmalGbv11Kh_OyWi2_vigrTro'
+
+EPORTAL_SERVER_ID=$( grep -oP 'server_id=\K(.+)' /etc/sysconfig/kcare/systemid )
+
+curl -kL -H "X-Api-Key: ${EPORTAL_API_KEY}" --data-urlencode "server_id=${EPORTAL_SERVER_ID}" --data-urlencode "tags=${EPORTAL_TAGS}" "${EPORTAL_URL}/admin/api/set_tags"
+```
+
 ### Puppet Plan
 
 If you prefer to have a plan rather than a task, then you can create one from this script with the following steps:

docs/.vuepress/public/images/tags_view.png

@@ -821,6 +821,50 @@ A new table is added to the starting page. This table displays the following:
 
 The number of servers for each key is listed on the _Keys_ page.
 
+## Managing server tags
+
+You can use 'Server tags' page to deal with tags.
+
+![server tags view](/images/tags_view.png)
+
+Tagging is a convenient way to group servers by any criteria. For example OS, deployment environment, location, etc.
+You need to create a tag and then it can be assigned to a server from the [Managing Servers](#managing-servers) interface.
+
+![tag assignment](/images/tag_assignment.png)
+
+The tag may have an optional value. For example, this allows you to introduce a new geo location without creating a new tag for it.
+
+### Using agent CLI to manage tags
+
+To add an extra Tag field for the server, run:
+
+```text
+# kcarectl --tag command
+```
+
+where `command` is a parameter defined by a user. This parameter will be displayed in UI for the server. User could add multiple tags for each server. Each tag should be separated with `;` symbol.
+
+Example:
+
+```text
+# kcarectl --tag "env:prod;ubuntu"
+```
+
+This server has two tags : `env:prod` and `ubuntu`.
+
+`env:prod` is a parameter that has tag name `env` and the value `prod`.
+
+![tags](/images/addingextratagfield_zoom88.png)
+
+To remove all tags from a particular server, run:
+
+```text
+# kcarectl --tag ""
+```
+
+Where `""` is a parameter to delete the previously defined tag.
+
+
 ## Feed Management
 
 Feeds are intended to manage patchsets on the server, and they provide a possibility to bind a set of patches to a specific key. Possible use cases:
@@ -946,36 +990,6 @@ The API key is personal, meaning it is tied to a specific user and inherits thei
 A user with read-only permissions can only manage their own keys,
 while an administrator has access to any user's API keys.
 
-## Adding extra Tag field
-
-To add an extra Tag field for the server, run:
-
-```text
-# kcarectl --tag command
-```
-
-where `command` is a parameter defined by a user. This parameter will be displayed in UI for the server. User could add multiple tags for each server. Each tag should be separated with `;` symbol.
-
-Example:
-
-```text
-# kcarectl --tag "env:prod;ubuntu"
-```
-
-This server has two tags : `env:prod` and `ubuntu`.
-
-`env:prod` is a parameter that has tag name `env` and the value `prod`.
-
-![tags](/images/addingextratagfield_zoom88.png)
-
-To remove all tags from a particular server, run:
-
-```text
-# kcarectl --tag ""
-```
-
-Where `""` is a parameter to delete the previously defined tag.
-
 ## How to setup ePortal to use HTTPS
 
 Some assumptions for a server where e-portal is deployed: