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

doc: style fixes, example code fixes and clarifications

Browse Source
This commit is contained in:
pancho horrillo
2019-11-27 16:07:23 +01:00
parent 9cd5591490
commit 53b326cb7b
4 changed files with 193 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/the_project/install_and_configure.rst
+16 -16
View File
@@ -1,18 +1,18 @@
Installing Kapow!
=================
Kapow! has a reference implementation in Go that is under active development
right now. If you want to start using Kapow! you can choose from several
Kapow! has a reference implementation in ``Go`` that is under active development
right now. If you want to start using **Kapow!** you can choose from several
options.
Download and install a binary
Download and Install a Binary
-----------------------------
Binaries for several platforms are available from our
Binaries for several platforms are available from the
`releases <https://github.com/BBVA/kapow/releases>`_ section, visit the latest
release page and download the binary corresponding to the platfom and
architecture you want to install Kapow! in.
architecture you want to install **Kapow!** in.
Linux
@@ -29,26 +29,26 @@ Windows
^^^^^^^
Copy the downloaded binary to a directory of your choice and update the system
PATH variable to include that directory.
``PATH`` variable to include that directory.
Install the package with go get
-------------------------------
If you already have `installed and configured <https://golang.org/cmd/go/>`_
the go runtime in the host where you want to run Kapow!, simply run:
the ``go`` runtime in the host where you want to run **Kapow!**, simply run:
.. code-block:: bash
$ go get -u github.com/BBVA/kapow
Include Kapow! in your container image
Include Kapow! in your Container Image
--------------------------------------
If you want to include Kapow! in a Docker image you can add the binary directly
from the releases section. Following is an example dockerfile that includes
Kapow!.
If you want to include **Kapow!** in a ``Docker`` image you can add the binary
directly from the releases section. Following is an example ``Dockerfile`` that
includes **Kapow!**.
.. code-block:: dockerfile
@@ -62,9 +62,9 @@ Kapow!.
ENTRYPOINT ["/usr/bin/kapow"]
If the container is intended to run the server and you want to dinamically
configure it, remember to include a --control-bind param with an external bind
address (i.e. 0.0.0.0) and to map all the needed ports in order to get access
If the container is intended for running the server and you want to dinamically
configure it, remember to include a `--control-bind` param with an external bind
address (i.e. ``0.0.0.0``) and to map all the needed ports in order to get access
to the control interface.
After building the image you can run the container with:
@@ -73,5 +73,5 @@ After building the image you can run the container with:
$ docker run --rm -i -p 8080:8080 -v $(pwd)/whatever.pow:/opt/whatever.pow kapow:latest server /opt/whatever.pow
With the -v parameter we map a local file into the container's filesystem so we
can use it to configure our Kapow! server on startup.
With the `-v` parameter we map a local file into the container's filesystem so
we can use it to configure our **Kapow!** server on startup.
docs/source/the_project/quickstart.rst
+50 -38
View File
@@ -1,38 +1,41 @@
Quick start
===========
Quick Start Guide
=================
We'll explain a simple example to help you understand what Kapow! really does and why it is awesome.
We'll explain a simple example to help you understand what **Kapow!** can do and
why it is so awesome :-).
Scenario
--------
Consider that we're in a corporate network like the following one:
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 that act as a bridget 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: We need to check if the** :samp:`Internal Host` **is alive.**
Limitations and constraints
--------------------------
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 :samp:`Internal Host` from the Internet.
3. We **want to limit the actions** that an 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 that facilitates the automation.
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.
What options we have?
---------------------
The Desired Solution
--------------------
Alter analyzyng the problem and our goal we conclude that is enough **to use a simple** :samp:`ping` **to** :samp:`Internal Host`.
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`.
So, the next step is to **analyze how to perform the ping.**
@@ -40,41 +43,43 @@ So, the next step is to **analyze how to perform the ping.**
Accessing via SSH to :samp:`External Host`
++++++++++++++++++++++++++++++++++++++++++
If we choose this option then we need to create a user and grant him access via :samp:`SSH` to :samp:`External Host` for every person that needs to check for :samp:`Internal host` status.
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 a constraint.)
2. We need to grant access for users to system (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 and deploy a custom solution
Develop and Deploy a Custom Solution
++++++++++++++++++++++++++++++++++++
Ok, this approach could maybe be the better choice for our organization but:
Ok, this approach could be the best choice for our organization, but:
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 bucket, even we have developers in our organization.
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 a constraint.)
2. Need to spend time.
2. Need to spend time (and time is money, see reason #1)
Using Kapow! (Spoiler: the winner!)
+++++++++++++++++++++++++++++++++++
Using Kapow! (spoiler: it's the winner!)
++++++++++++++++++++++++++++++++++++++++
Ok, lets analyze Kapow! and check it for our constraints:
Ok, lets analyze **Kapow!** and check if it is compatible with our constraints:
1. Kapow! is Open Source, so **it's free**.
2. By using kapow! we don't need to program our own solution, so we **don't waste time**.
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`.
@@ -95,10 +100,12 @@ Install Kapow!
Follow :doc:`Install Kapow! <install_and_configure>` instructions.
Write ping.pow file
+++++++++++++++++++
Write a `ping.pow` File
+++++++++++++++++++++++
Kapow! use 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:
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
@@ -107,26 +114,27 @@ Kapow! use plain text files (called ``POW`` files) so you can define the endpoin
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.
2. :samp:`-c` - after this parameter we write the system command that Kapow! will run each time the endpint is invoked.
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` - writes the ping output to the response so you can see it.
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 our :samp:`ping.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
+++++++++++++++++++
Now we can call our new created endpoint by using our favorite HTTP client. In this example we're using :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
@@ -134,14 +142,18 @@ Now we can call our new created endpoint by using our favorite HTTP client. In t
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
et voilà !
Under the hoods
++++++++++++++++
To understand what's happening under 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! performs 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``.