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

Revert "Update quickstart.rst"

Browse Source 
This reverts commit 7fab8ae529.
This commit is contained in:
pancho horrillo
2019-11-29 10:20:40 +01:00
parent 7fab8ae529
commit 2e1455cb61
1 changed files with 81 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/the_project/quickstart.rst
+81 -57
View File
@@ -1,95 +1,111 @@
Quick start
===========
Quick Start Guide
=================
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
--------
In this example we'll consider that our scenario is a corporate network like this:
Let's suppose that we're in a corporate network like the following one:
.. _quickstart_image:
.. image:: /_static/network.png
:align: center
:width: 80%
Our organization has an external host as a bridge between our intranet an the public Internet.
Our organization has an external host that act as a bridge between our intranet
an the public Internet.
**Our goal: our team need to check if the the host :samp:`Internal Machine` is alive.**
**Our goal: We need to check if the** :samp:`Internal Host` **is alive.**
Limitations and constrains
--------------------------
Limitations and Constraints
---------------------------
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 to *Internal Host* from the Internet.
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** the most standard way mechanism. Easy to use and that facilitates the automation.
5. We **don't have budget** to invest in a custom solution.
2. We **don't want** to manage VPNs or any similar solutions to access :samp:`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.
4. We **want** to use the most standard mechanism. Easy to use and automate.
5. We **don't have a budget** to invest in a custom solution.
Study options
-------------
Alter analyze the problem and our goal we conclude that is enough **with a simple :samp:`ping` to samp:`Internal Host`.**
The Desired Solution
--------------------
So, then **we need analyze how to perform the ping.**
After analyzing the problem and our with our goal in mind, we conclude that it
is enough **to use a simple** :samp:`ping` **to** :samp:`Internal Host`.
Accessing via SSH
+++++++++++++++++
So, the next step is to **analyze how to perform the ping.**
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.
Conclusion: **Not good idea**
Accessing via SSH to :samp:`External Host`
++++++++++++++++++++++++++++++++++++++++++
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:
1. We need to manage users (violates our constrains)
2. We need to access users to system (violates our constrains)
3. We can't control the :samp:`ping` options the user choice to ping :samp:`Internal Host` (violates our constrains)
1. We need to manage users (violates a constraint.)
2. We need to grant usesrs access to a host (violates a constraint.)
3. We can't control what :samp:`ping` options the user can use to ping :samp:`Internal Host` (violates a constraint.)
Develop custom solution
+++++++++++++++++++++++
Oks, this approach could maybe be the more customizable for our organization but:
Develop and Deploy a Custom Solution
++++++++++++++++++++++++++++++++++++
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.
Ok, this approach could be the best choice for our organization, but:
Conclusion: **Not good idea**
1. We'll need to create a new project, develop, test, manage and maintain it.
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:
1. Need to spend money (violates our constrains)
2. Need to spend time (violates our constrains)
1. Need to spend money (violates a constraint.)
2. Need to spend time (and time is money, see reason #1)
Using Kapow! (Spoiler: the winner!)
+++++++++++++++++++++++++++++++++++
Oks, lets analyze Kapow! and check our constrains:
Using Kapow! (spoiler: it's the winner!)
++++++++++++++++++++++++++++++++++++++++
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`**
Ok, lets analyze **Kapow!** and check if it is compatible with our constraints:
Conclusion: **Kapow! is the best choice**.
1. **Kapow!** is Open Source, so **it's also free as in beer**.
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!
------------
Following the example of the :ref:`Scenario <quickstart_image>` we'll follow these steps:
In order to get our example :ref:`Scenario <quickstart_image>` working we need to follow the below steps.
Install Kapow!
++++++++++++++
Follow :doc:`Install Kapow! <install_and_configure>`.
Follow :doc:`Install Kapow! <install_and_configure>` instructions.
Write 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:
Write a `ping.pow` File
+++++++++++++++++++++++
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
@@ -98,24 +114,27 @@ Kapow! use plain text files to define the rules to expose the system command. Fo
Explanation:
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 runs for each HTTP Request to :samp:`/ping`.
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.
2. :samp:`-c` - after this parameter we write the system command that **Kapow!** will run each time the endpoint is invoked.
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` - sends the ping response to be the HTTP Response of HTTP End-point of :samp:`/ping`.
4. :samp:`| kapow set /response/body` - writes the output of `ping` to the body of the response, so you can see it.
Launch the service
Launch the Service
++++++++++++++++++
At this point we only need to launch kapow! with :samp:`simple.pow`:
At this point we only need to launch `kapow` with our :samp:`ping.pow`:
.. code-block:: console
$ kapow server ping.pow
Consume the service
Consume the Service
+++++++++++++++++++
Then we can call HTTP Service as any usual tool for the web. In this example we'll use :samp:`curl`:
Now we can call our newly created endpoint by using our favorite HTTP client.
In this example we're using :samp:`curl`:
.. code-block:: console
@@ -123,13 +142,18 @@ Then we can call HTTP Service as any usual tool for the web. In this example we'
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
Under the hoods
++++++++++++++++
et voilà !
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
:align: center
:width: 80%
As you can see, Kapow! perform the *magic* between system commands and HTTP API.
As you can see, **Kapow!** provides the necessary *magic* to turn a **system
command** into an ``HTTP API``.