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

doc: typos and style fixes

Browse Source
This commit is contained in:
pancho horrillo
2019-12-10 16:09:35 +01:00
parent 84e481f78f
commit b4bc08f491
4 changed files with 90 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/the_project/install_and_configure.rst
+41 -13
View File
@@ -1,7 +1,7 @@
Installing Kapow!
=================
*Kapow!* has a reference implementation in ``Go`` that is under active development
*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.
@@ -20,7 +20,7 @@ Linux
Install the downloaded binary using the following command as a privileged user.
.. code-block:: bash
.. code-block:: console
$ install -t /usr/local/bin/kapow path_to_downloaded_binary
@@ -32,22 +32,50 @@ Copy the downloaded binary to a directory of your choice and update the system
``PATH`` variable to include that directory.
Install the package with go get
-------------------------------
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:
.. code-block:: bash
.. code-block:: console
$ go get -u github.com/BBVA/kapow
$ go get -v github.com/BBVA/kapow
Note that *Kapow!* leverages *Go modules*, so you can target specific releases:
.. code-block:: console
$ GO111MODULE=on go get -v github.com/BBVA/kapow@v0.3.0-rc4
go: finding github.com v0.3.0-rc4
go: finding github.com/BBVA v0.3.0-rc4
go: finding github.com/BBVA/kapow v0.3.0-rc4
go: downloading github.com/BBVA/kapow v0.3.0-rc4
go: extracting github.com/BBVA/kapow v0.3.0-rc4
github.com/google/shlex
github.com/google/uuid
github.com/spf13/pflag
github.com/BBVA/kapow/internal/server/httperror
github.com/BBVA/kapow/internal/http
github.com/BBVA/kapow/internal/server/model
github.com/BBVA/kapow/internal/client
github.com/gorilla/mux
github.com/BBVA/kapow/internal/server/user/spawn
github.com/BBVA/kapow/internal/server/data
github.com/BBVA/kapow/internal/server/user/mux
github.com/BBVA/kapow/internal/server/user
github.com/BBVA/kapow/internal/server/control
github.com/spf13/cobra
github.com/BBVA/kapow/internal/server
github.com/BBVA/kapow/internal/cmd
github.com/BBVA/kapow
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
If you want to include *Kapow!* in a ``Docker`` image, you can add the binary
directly from the releases section. Below is an example ``Dockerfile`` that
includes *Kapow!*.
.. code-block:: dockerfile
@@ -63,15 +91,15 @@ includes *Kapow!*.
ENTRYPOINT ["/usr/bin/kapow"]
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.
configure it, remember to include a ``--control-bind`` param with an external
bind address (e.g., ``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:
.. code-block:: bash
.. code-block:: console
$ 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
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
+33 -20
View File
@@ -19,15 +19,18 @@ this:
Our organization has an external host that acts as a bridge between our intranet
an the public Internet.
**Our goal: Our team needs to check if the** :samp:`Internal Host` **is alive.**
**Our goal: Our team must be able to check if the :samp:`Internal Host` is alive on an ongoing basis.**
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 :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.
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.
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.
@@ -35,7 +38,7 @@ Limitations and Constraints
The Desired Solution
--------------------
After analyzing the problem and our with our goal in mind, we conclude that it
After analyzing the problem and 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.**
@@ -44,9 +47,9 @@ 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 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`.
If we choose this option, then, for every person that needs to check the status
of :samp:`Internal host`, we need to create a user in the ``Extarnal Host`` and
grant them ``SSH`` access.
Conclusion: **Not a good idea.**
@@ -80,10 +83,14 @@ Using *Kapow!* (spoiler: it's the winner!)
Ok, let's analyze *Kapow!* and check if it is compatible with our constraints:
1. *Kapow!* is Open Source, so **it's also free as in beer**.
2. By using kapow! we don't need to code 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`.
1. *Kapow!* is Open Source, so it's also **free as in beer**.
2. By using *Kapow!* we don't need to code 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** :samp:`External Host` **to
anybody**.
Conclusion: *Kapow!* **is the best choice.**
@@ -93,19 +100,20 @@ Reasons: It satisfies all of our requirements.
Using Kapow!
------------
In order to get our example :ref:`Scenario <quickstart_image>` working we need to follow the below steps.
In order to get our example :ref:`Scenario <quickstart_image>` working we need
to follow the steps below.
Install Kapow!
++++++++++++++
Follow :doc:`Install *Kapow!* <install_and_configure>` instructions.
Follow the :doc:`Installing Kapow! <install_and_configure>` instructions.
Write a ``ping.pow`` File
+++++++++++++++++++++++++
*Kapow!* uses plain text files (called ``POW`` files) so you can define the
*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:
@@ -116,16 +124,21 @@ file like this:
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 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 output of `ping` to the body of the response, so you can see it.
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 output of `ping` to the body
of the response, so you can see it.
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
docs/source/the_project/security.rst
+8 -9
View File
@@ -23,8 +23,8 @@ Let's consider the following route:
#!/bin/sh
kapow route add /find -c <<-'EOF'
BASEPATH=$(kapow get /request/params/path)
find "$BASEPATH" | kapow set /response/body
BASEPATH=$(kapow get /request/params/path)
find "$BASEPATH" | kapow set /response/body
EOF
@@ -61,12 +61,11 @@ The command that will eventually be executed by ``bash`` is:
find -delete | kapow set /response/body
This will silently delete all the files below the current directory, no
This will *silently delete all the files below the current directory*, no
questions asked. Probably not what you expected.
This happens because ``find`` has the last word on how to interpret its arguments.
For ``find`` the argument `-delete` is not a path,
For ``find``, the argument `-delete` is not a path.
Let's see how we can handle this particular case:
@@ -74,13 +73,13 @@ Let's see how we can handle this particular case:
#!/bin/sh
kapow route add /find -c <<-'EOF'
USERINPUT=$(kapow get /request/params/path)
BASEPATH=$(dirname -- "$USERINPUT")/$(basename -- "$USERINPUT")
find "$BASEPATH" | kapow set /response/body
USERINPUT=$(kapow get /request/params/path)
BASEPATH=$(dirname -- "$USERINPUT")/$(basename -- "$USERINPUT")
find "$BASEPATH" | kapow set /response/body
EOF
.. note::
Since this is critical for keeping your *Kapow!* services secure, we are working
on a way to make this more transparent and safe, while at the same time keeping
it Kapowy.
it *Kapowy*.
docs/source/tutorial/index.rst
+8 -8
View File
@@ -1,13 +1,13 @@
*Kapow!* Tutorial
=================
This tutorial will allow you to grow slowly in the knowledge of *Kapow!*. It
tells you the story of a senior ops guy just arrived to his new job in a small
company. He'll face different challenges of increasing difficulty, but with
the help of his experienced senior mate and *Kapow!* he will be able to satisfy
all the requierements.
This tutorial will help you to get more familiar with *Kapow!*. It tells you
the story of a senior ops guy just arrived to his new job in a small company.
He'll face different challenges of increasing difficulty, but with the help of
his experienced senior mate and *Kapow!* he will be able to pass all the
hurdles.
You just only need to follow the steps and execute the code shown in the
tutorial to learn the *Kapow!* way of doing.
You just need to follow the steps and execute the code shown in the tutorial
to learn *the Kapow! way*.
Have a nice trip to Kapow!
Enjoy the ride!