Dark-Alex-17/kapow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update quickstart.rst

Browse Source
This commit is contained in:
luissaiz
2019-11-29 09:48:10 +01:00
committed by GitHub
parent f1bdc99267
commit 7fab8ae529
1 changed files with 57 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/the_project/quickstart.rst
+57 -81
View File
@@ -1,111 +1,95 @@
Quick Start Guide Quick start
================= ===========
We'll explain a simple example to help you understand what **Kapow!** can do and
why it is so awesome :-).
We'll explain you a simple example to help you understand what Kapow! really does and why it is awesome.
Scenario Scenario
-------- --------
Let's suppose that we're in a corporate network like the following one: In this example we'll consider that our scenario is a corporate network like this:
.. _quickstart_image: .. _quickstart_image:
.. image:: /_static/network.png .. image:: /_static/network.png
:align: center :align: center
:width: 80% :width: 80%
Our organization has an external host that act as a bridge between our intranet Our organization has an external host as a bridge between our intranet an the public Internet.
an the public Internet.
**Our goal: We need to check if the** :samp:`Internal Host` **is alive.** **Our goal: our team need to check if the the host :samp:`Internal Machine` is alive.**
Limitations and constrains
Limitations and Constraints --------------------------
---------------------------
1. We **don't want** to **grant access** to the :samp:`External Host` to anybody. 1. We **don't want** to **grant access** to the :samp:`External Host` to anybody.
2. We **don't want** to manage VPNs or any similar solutions to access :samp:`Internal Host` from the Internet. 2. We **don't want** to manage VPNs or any similar solutions to access to *Internal Host* from the Internet.
3. We **want to limit the actions** that a user can perform in our intranet while it is checking if :samp:`Internal Host` is alive. 3. We **want to limit the actions** that an user can perform in our intranet when while it is checking if :samp:`Internal Host` is alive.
4. We **want** to use the most standard mechanism. Easy to use and automate. 4. We **want** the most standard way mechanism. Easy to use and that facilitates the automation.
5. We **don't have a budget** to invest in a custom solution. 5. We **don't have budget** to invest in a custom solution.
Study options
-------------
The Desired Solution Alter analyze the problem and our goal we conclude that is enough **with a simple :samp:`ping` to samp:`Internal Host`.**
--------------------
After analyzing the problem and our with our goal in mind, we conclude that it So, then **we need analyze how to perform the ping.**
is enough **to use a simple** :samp:`ping` **to** :samp:`Internal Host`.
So, the next step is to **analyze how to perform the ping.** Accessing via SSH
+++++++++++++++++
In this case we need to create a system user in samp:`External Host` for each user that needs to check if :samp:`Internal host` is alive and we also need to grant access to each user through :samp:`SSH` to the system.
Accessing via SSH to :samp:`External Host` Conclusion: **Not good idea**
++++++++++++++++++++++++++++++++++++++++++
If we choose this option then we need to create a user in the host and grant
them access via :samp:`SSH` to :samp:`External Host` for every person that needs
to check the :samp:status of `Internal host`.
Conclusion: **Not a good idea.**
Reasons: Reasons:
1. We need to manage users (violates a constraint.) 1. We need to manage users (violates our constrains)
2. We need to grant usesrs access to a host (violates a constraint.) 2. We need to access users to system (violates our constrains)
3. We can't control what :samp:`ping` options the user can use to ping :samp:`Internal Host` (violates a constraint.) 3. We can't control the :samp:`ping` options the user choice to ping :samp:`Internal Host` (violates our constrains)
Develop custom solution
+++++++++++++++++++++++
Develop and Deploy a Custom Solution Oks, this approach could maybe be the more customizable for our organization but:
++++++++++++++++++++++++++++++++++++
Ok, this approach could be the best choice for our organization, but: 1. We'll need to start a new project. Develop it, test it, manage it and maintain it.
2. We need time for the development.
3. We need money. Even we have developers in our organization, their time it's not free.
1. We'll need to create a new project, develop, test, manage and maintain it. Conclusion: **Not good idea**
2. We need to wait for for the development to be production ready.
3. We need a budget, even if we have developers in our organization.
Conclusion: **Not a good idea.**
Reasons: Reasons:
1. Need to spend money (violates a constraint.) 1. Need to spend money (violates our constrains)
2. Need to spend time (and time is money, see reason #1) 2. Need to spend time (violates our constrains)
Using Kapow! (Spoiler: the winner!)
+++++++++++++++++++++++++++++++++++
Using Kapow! (spoiler: it's the winner!) Oks, lets analyze Kapow! and check our constrains:
++++++++++++++++++++++++++++++++++++++++
Ok, lets analyze **Kapow!** and check if it is compatible with our constraints: 1. Kapow! is Open Source. Them: **it's free**.
2. By using kapow! we don't need to program our own solution. Them: **don't waste time**.
3. By using Kapow! we can run any command in the :samp:`External Host` limiting the command parameters. Them: **it's safe**.
4. By using Kapow! we can launch any system command as HTTP API easily. Them: **we don't need to grant login access to anybody to :samp:`External Host`**
1. **Kapow!** is Open Source, so **it's also free as in beer**. Conclusion: **Kapow! is the best choice**.
2. By using kapow! we don't need to program our own solution, so we **don't have to waste time**.
3. By using Kapow! we can run any command in the :samp:`External Host` limiting the command parameters, so **it's safe**.
4. By using Kapow! we can launch any system command as an HTTP API easily, so **we don't need to grant login access to anybody to** :samp:`External Host`.
Conclusion: **Kapow! is the best choice.**
Reasons: It satisfies all of our requirements.
Reasons: it cover all of our requirements.
Using Kapow! Using Kapow!
------------ ------------
In order to get our example :ref:`Scenario <quickstart_image>` working we need to follow the below steps. Following the example of the :ref:`Scenario <quickstart_image>` we'll follow these steps:
Install Kapow! Install Kapow!
++++++++++++++ ++++++++++++++
Follow :doc:`Install Kapow! <install_and_configure>` instructions. Follow :doc:`Install Kapow! <install_and_configure>`.
Write ping.pow file
+++++++++++++++++++
Write a `ping.pow` File Kapow! use plain text files to define the rules to expose the system command. For our example we need a file like that:
+++++++++++++++++++++++
Kapow! uses plain text files (called ``POW`` files) so you can define the
endpoints you want to expose the system command with. For our example we need a
file like this:
.. code-block:: console .. code-block:: console
@@ -114,27 +98,24 @@ file like this:
Explanation: Explanation:
1. :samp:`kapow route add /ping` - adds a new HTTP API endpoint at :samp:`/ping` path in the Kapow! server. You have to use `GET` method to invoke the endpoint. 1. :samp:`kapow route add /ping` - adds a new HTTP API end-point at :samp:`/ping`.
2. :samp:`-c` - after this parameter we write the system command that **Kapow!** will run each time the endpoint is invoked. 2. :samp:`-c` - after this parameter we write the system command that Kapow! will runs for each HTTP Request to :samp:`/ping`.
3. :samp:`ping -c 1 10.10.10.100` - sends 1 ping package to the host *10.10.10.100*, i.e. :samp:`Internal Host`. 3. :samp:`ping -c 1 10.10.10.100` - sends 1 ping package to the host *10.10.10.100*, i.e. :samp:`Internal Host`.
4. :samp:`| kapow set /response/body` - writes the output of `ping` to the body of the response, so you can see it. 4. :samp:`| kapow set /response/body` - sends the ping response to be the HTTP Response of HTTP End-point of :samp:`/ping`.
Launch the service
Launch the Service
++++++++++++++++++ ++++++++++++++++++
At this point we only need to launch `kapow` with our :samp:`ping.pow`: At this point we only need to launch kapow! with :samp:`simple.pow`:
.. code-block:: console .. code-block:: console
$ kapow server ping.pow $ kapow server ping.pow
Consume the service
Consume the Service
+++++++++++++++++++ +++++++++++++++++++
Now we can call our newly created endpoint by using our favorite HTTP client. Then we can call HTTP Service as any usual tool for the web. In this example we'll use :samp:`curl`:
In this example we're using :samp:`curl`:
.. code-block:: console .. code-block:: console
@@ -142,18 +123,13 @@ In this example we're using :samp:`curl`:
PING 10.10.100 (10.10.100): 56 data bytes PING 10.10.100 (10.10.100): 56 data bytes
64 bytes from 10.10.100: icmp_seq=0 ttl=55 time=1.425 ms 64 bytes from 10.10.100: icmp_seq=0 ttl=55 time=1.425 ms
et voilà ! Under the hoods
++++++++++++++++
To understand what's happening in the hoods with Kapow! lets see the picture:
Under the Hood
++++++++++++++
To understand what's happening under the hood with **Kapow!** lets see the
following diagram:
.. image:: /_static/sequence.png .. image:: /_static/sequence.png
:align: center :align: center
:width: 80% :width: 80%
As you can see, **Kapow!** provides the necessary *magic* to turn a **system As you can see, Kapow! perform the *magic* between system commands and HTTP API.
command** into an ``HTTP API``.