diff --git a/ChangeLog.md b/ChangeLog.md index ba6366d9df59acfe9a9a42a3cba084ff12d95b1a..8c5bc533fd25275a3c8d7400d9125412f6f96225 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,3 +1,8 @@ +* 15 [doc] tomek + + Users and machines management is now documented in the Stork ARM. + (Gitlab #99) + * 14 [doc] sgoldlust Introduced new Stork logo in the documentation. diff --git a/README.md b/README.md index 43d4a4426055e01833b00403c175d11081927a37..9234de035a4653ca9bc07b530238533464ac3312 100644 --- a/README.md +++ b/README.md @@ -4,22 +4,18 @@ Stork is a new project started by ISC in October 2019 with the aim of delivering BIND and Kea dashboard. It is going to be a spiritual successor of earlier attempts - Kittiwake and Antherius. -It is currently in very early stages of planning. More information will become publicly -available in October 2019. Stay tuned! +It is currently in very early stages of development. -# Getting Started - -Please see the Installation section in the Stork ARM for details. Stork ARM will -be published soon, but for the time being you can generate it on your own by -doing this: - -```console -rake doc -``` - -Make sure you have rake and sphinx installed. +For details, please see [Stork Administrator Reference Manual](https://stork.readthedocs.io). # Build instructions The easiest way to run Stork is with docker (`rake docker_up`). However, it is possible to run Stork without docker. See Installation section of the Stork ARM. + +# Getting involved + +Stork is in very early stages of its development. There isn't much available yet that end users +could use. However, if you'd like to get involved, feel free to subscribe to the +[stork-dev mailing list](https://lists.isc.org/mailman/listinfo/stork-dev) or look +at [Stork project page](https://gitlab.isc.org/isc-projects/stork). diff --git a/doc/backend-api.rst b/doc/backend-api.rst index dfe5505a00ff3993cc8bdb161aaedfe94aff781a..690a2127a27cdc74b923e6412ff29d3b854c4dc4 100644 --- a/doc/backend-api.rst +++ b/doc/backend-api.rst @@ -1,17 +1,12 @@ .. _backend-api: -***************** -Stork Backend API -***************** +*********** +Backend API +*********** -URL: (stork-url)/version-get - -Returns: - -.. code-block:: json - - { - "version": "1.2.3" - } +Stork agent provides a REST API. The API is generated using [Swagger](https://swagger.io/). The API +points are currently documented in the ``api/swagger.yaml`` file. +.. note:: + In the future Stork releases, the API documentation will be generated automatically. diff --git a/doc/devel.rst b/doc/devel.rst index 80bc436ae82bc513b03df11c6a92feca36a17296..a3e9f86cc0d8652746065b85ac57b18f5b5c96df 100644 --- a/doc/devel.rst +++ b/doc/devel.rst @@ -9,3 +9,52 @@ Developer's Guide We acknowledge that users and developers are two different groups of people, so the documents should eventually be separated. However, since these are still very early days of the project, this section is kept in the Stork ARM for convenience only. + +Generating Documentation +======================== + +To generate documentation, simply type ``rake doc``. You need to have `Sphinx `_ +and `rtd-theme `_ installed. The generated +documentation will be available in the ``doc/singlehtml`` directory. + +Agent API +========= + +The connection between the server and the agents is established using gRPC over http/2. The agent API +definition is kept in the ``backend/api/agent.proto`` file. For debugging purposes, it is possible +to connect to the agent using `grpcurl `_ tool. For example, +you can retrieve a list of currently provided gRPC calls by using this command: + +.. code:: console + + $ grpcurl -plaintext -proto backend/api/agent.proto localhost:8888 describe + agentapi.Agent is a service: + service Agent { + rpc detectServices ( .agentapi.DetectServicesReq ) returns ( .agentapi.DetectServicesRsp ); + rpc getState ( .agentapi.GetStateReq ) returns ( .agentapi.GetStateRsp ); + rpc restartKea ( .agentapi.RestartKeaReq ) returns ( .agentapi.RestartKeaRsp ); + } + +You can also make specific gRPC calls. For example, to get the machine state, the following command +can be used: + +.. code:: console + + $ grpcurl -plaintext -proto backend/api/agent.proto localhost:8888 agentapi.Agent.getState + { + "agentVersion": "0.1.0", + "hostname": "copernicus", + "cpus": "8", + "cpusLoad": "1.68 1.46 1.28", + "memory": "16", + "usedMemory": "59", + "uptime": "2", + "os": "darwin", + "platform": "darwin", + "platformFamily": "Standalone Workstation", + "platformVersion": "10.14.6", + "kernelVersion": "18.7.0", + "kernelArch": "x86_64", + "hostID": "c41337a1-0ec3-3896-a954-a1f85e849d53" + } + diff --git a/doc/index.rst b/doc/index.rst index 8da45aac641b17d951b1675a185129459fd98ef8..56eff64eaf871239ab5857737df799834c8f387b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -10,10 +10,9 @@ It is going to be a spiritual successor of earlier attempts - Kittiwake and Anth It is currently in very early stages of planning. This is the reference guide for Stork version |release|. -Links to the most up-to-date version of this document (in PDF, HTML, -and plain text formats), along with other documents for -Kea, can be found in ISC's `Stork project homepage `_. - +Links to the most up-to-date version of this document, along with other documents for +Stork, can be found in ISC's `Stork project homepage `_ +or `readthedocs `_ . .. toctree:: :numbered: diff --git a/doc/man/stork-agent.8.rst b/doc/man/stork-agent.8.rst index 9d7bcfb60176d9c45b4d39307844e47a20602e5d..1385b4a001f048decc62dccb694392e81347eb51 100644 --- a/doc/man/stork-agent.8.rst +++ b/doc/man/stork-agent.8.rst @@ -15,7 +15,7 @@ stork-agent - Stork agent that monitors BIND and Kea services Synopsis ~~~~~~~~ -:program:`stork-agent` +:program:`stork-agent` [**--host**] [**--port**] Description ~~~~~~~~~~~ @@ -24,6 +24,22 @@ The ``stork-agent`` is a small tool that is being run on the systems that are running BIND and Kea services. Stork server connects to the stork agent and uses it to monitor services remotely. +Arguments +~~~~~~~~~ + +The Stork Agent takes the following arguments: + +``-h`` or ``--help`` + Displays list of available parameters. + +``--host=hostname`` + Specifies the IP to listen on. Can be controlled with $STORK_AGENT_ADDRESS environment + variable. The default value is ``::``. + +``--port=1234`` + Specifies the TCP port to listen on for connections. The default is 8080. Can be controlled + with $STORK_AGENT_PORT environment variable. + Configuration ~~~~~~~~~~~~~ diff --git a/doc/usage.rst b/doc/usage.rst index cc397a6133ca398114ebf5508579b14993171388..49280d7650492908a023a96cb6413d9208f13089 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -4,22 +4,109 @@ Using Stork *********** -Setting up users -================ +This section describes how to use features available in stork. To connect to Stork, use your +web browser and connect to port 4200. If Stork is running on your localhost, you can navigate +to http://localhost:4200. - As of Stork 0.1.0 release, there is no possibility to create new users. This - functionality will be added in the next release. Currently, the default - administrator's account is created and can be used to sign in to the - system via the web UI. Please use the login `admin` and password `admin` to - sign in to the system. +Managing users +============== +Currently, the default administrator's account is created and can be used to sign in to the system +via the web UI. Please use the login ``admin`` and password ``admin`` to sign in to the system. -Monitoring machines with BIND and Kea -===================================== +To manage users, click on the ``Configuration`` menu and choose ``Users``. You will see a list of +existing users. At the very least, there will be user ``admin``. -.. todo:: +To add new user, click ``Create User Account``. A new tab will opened that will let you specify the +new account parameters. Some fields have specific restrictions. Username can consist of only +letters, numbers and underscore. E-mail field is optional. However, if specified, it must be a well +formed e-mail. First and lastname fields are mandatory. Password must only contain letters, digits, +@, ., !, +, - and must be at least 8 characters long. Once all requirements are met, the ``Save`` +button will become active and you will be able to add new account. - Describe how the user can deploy agent, connect new machines, how to monitor them, etc. +.. note:: + As of Stork 0.2.0 release, the role-based access control is not implemented yet. Every user + is considered a super-admin and has full control over the system. +Deploying Stork Agent +===================== + +Stork system uses agents to monitor services. Stork Agent (`STAG` or simply `agent`) is a +daemon that is expected to be deployed and run on each machine to be monitored. As of Stork 0.2.0 +release there are no automated deployment routines and STAG has to be copied and run manually. +This can be done in a variety of ways. Here is one of them. + +Assuming you want to monitor services running on machine with IP 192.0.2.1, you can do the following +on the Stork server command line: + +.. code:: console + + cd + scp backend/cmd/stork-agent login@192.0.2.1:/path + +On the machine to be monitored, you need to start the agent. In the basic case, you can simply +run it: + +.. code:: console + + ./stork-agent + +You can optionally pass ``--host=`` or set the ``STORK_AGENT_ADDRESS`` environment variable to +specify which address the agent will listen on. You can pass ``--port`` or set the ``STORK_AGENT_PORT`` +environment variable to specify which TCP port the agent will listen on. + +.. note:: + + Unless explicitly specified, the agent will listen on all addresses on port 8080. There are no + authentication mechanisms implemented in the agent yet. Use with care! + +Registering New Machine +======================= + +Once the agent is deployed and running on the machine to be monitored, you should instruct Stork +server to start monitoring it. You can do so by going to Services menu and choosing Machines. +You will be presented with a list of currently registered machines. + +To add a new machine, click ``Add New Machine``. You need to specify the machine address or hostname +and a port. If Stork agent is running in a container, you may specify the container name. This is +particularly useful, if you built stork using ``rake docker_up`` command and the agent is running in +a container. In such case, you can use kea-agent as your hostname. If you run agent by using ``rake +run_agent``, the agent will listen on port 8888. + +Once you click Add, the server will attempt to establish gRPC over http/2 connection to the agent. +Make sure that any firewalls in between will allow incoming connections to the TCP port specified. + +Once a machine is added, number of parameters, such as hostname, address, agent version, number +of CPU cores, CPU load, available total memory, current memory utilization, uptime, OS, platform +family, platform name, OS version, kernel, virtualization details (if any), host ID and other +information will be provided. More information will become available in the future Stork versions. + +Monitoring Machines +=================== + +To monitor registered machines, go to Services menu and click Machines. A list of currently +registered machines will be displayed. Pagination mechanism is available to display larger +number of machines. + +There is a filtering mechanism that acts as an omnibox. The string typed is searched for an address, +agent version, hostname, OS, platform, OS version, kernel version, kernel architecture, +virtualization system, host-id fields. The filtering happens once you hit ENTER. + +You can inspect the state of a machine by clicking its hostname. A new tab will open with machine +details. Multiple tabs can be open at the same time. You can click Refresh state to get updated +information. + +The machine state can also be refreshed using Action menu. On the machines list, each machine has +its own menu. Click on the triple lines button at the right side and choose the Refresh option. + +Deleting Machines +================= + +To stop monitoring a machine, you can go to the Machines list, find the machine you want to stop +monitoring, click on the triple lines button at the right side and choose Delete. Note this will +terminate the connection between Stork server and the agent running on the machine and the server +will no longer monitor it. However, the Stork agent process will continue running. If you want to +completely shut it down, you need to do so manually, e.g. by connecting to the machine using ssh and +stopping the agent there. One way to achieve that is to issue ``killall stork-agent`` command.