diff --git a/docs/source/index.rst b/docs/source/index.rst index f242060..6256870 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -25,6 +25,8 @@ :maxdepth: 2 :caption: Tutorial + tutorial/tutorial00 + tutorial/tutorial01 tutorial/_brainstorm Indices and tables diff --git a/docs/source/tutorial/_brainstorm.rst b/docs/source/tutorial/_brainstorm.rst index ad4518b..3050bf7 100644 --- a/docs/source/tutorial/_brainstorm.rst +++ b/docs/source/tutorial/_brainstorm.rst @@ -35,6 +35,12 @@ ACME's Infrastructure - Corporate Server - Backup Server +Characters +---------- + +- Seasoned Ops +- Junior Ops + User Journey ------------ @@ -60,12 +66,11 @@ User Journey .. code-block:: console - $ curl -X PUT http://server:8080/db/backup - + $ kapow route add -X PUT /db/backup -e ./backup_db.sh .. code-block:: console - $ kapow route add -X PUT /db/backup -e ./backup_db.sh + $ curl -X PUT http://server:8080/db/backup #. Basic server monitoring @@ -80,7 +85,7 @@ User Journey .. code-block:: console - $ cat /var/log/backup_db.log | kapow set /response/body + $ cat /tmp/backup_db.log | kapow set /response/body #. Filter over basic monitoring @@ -109,8 +114,11 @@ User Journey - User Learns: Compose complex HTTP responses with more than one local command. - Kapow! Concepts: HEREDOC and subshells - - Problem/Motivation: - - pre-Kapow! solution: + - Problem/Motivation: The OPs manager needs to have information about + the health status of our servers. And she is always asking to the + team to write a report that involves calling several commands. + - pre-Kapow! solution: SSH into the server and manually execute the + commands, collect the output and write the report. - Kapow!-enabled solution: From this: @@ -127,6 +135,7 @@ User Journey .. code-block:: sh + kapow set /response/headers/Content-Type text/plain { echo Date: date @@ -145,24 +154,29 @@ User Journey - User Learns: Format a complex HTTP response with JSON format to feed the corporate dashboard. - Kapow! Concepts: backtick interpolation and `kapow set /response/headers` - - Problem/Motivation: + - Problem/Motivation: The OPs manager wants to create a dashboard to + see the server health information in real time. She hired a fronted + developer to make a nice dashboard application and we need to + provide him with the information in a format suitable for display. - pre-Kapow! solution: Write a php/perl/python script to serve this - Kapow!-enabled solution: - Don't handwrite JSON + Don't handwrite `JSON` .. code-block:: sh - echo "{memory: `free -m`, ...uups..}" | kapow set /response/body + kapow set /response/body application/json + echo "{memory: `free -m`, ...uups...}" | kapow set /response/body - Use jq + Use ``jq`` .. code-block:: sh MEMORY=$(free -m) LOAD=$(uptime) DISK=$(df -h) - jq -nc --arg memory "$MEMORY" '{"memory": $memory}' + kapow set /response/body application/json + jq -nc --arg memory "$MEMORY" '{"memory": $memory}' | kapow set /response/body Ideas ----- @@ -176,3 +190,32 @@ Ideas Add this to serve the webpage that uses the implemented HTTP API kapow route add / -c 'kapow set /resonse/headers/Content-Type text/html ; curl --output - http:// | kapow set /response/body' + + +Test +---- + +**User** + + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod + tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At + vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, + no sea takimata sanctus est Lorem ipsum dolor sit amet. + +**Admin** + + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod + tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At + vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, + no sea takimata sanctus est Lorem ipsum dolor sit amet. + +**User** + + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod + tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. + + .. code-block:: console + + $ cat something.txt + + Right? diff --git a/docs/source/tutorial/tutorial00.rst b/docs/source/tutorial/tutorial00.rst new file mode 100644 index 0000000..b5d426f --- /dev/null +++ b/docs/source/tutorial/tutorial00.rst @@ -0,0 +1,37 @@ +Your First Day at Work +====================== + +**Senior** + + Welcome to ACME Inc. This is your first day here, right? + +**Junior** + + Hi! I am excited to start working. What will be my first task? + +**Senior** + + First let me explain to you what is our infrastructure. + +**Junior** + + Ok. + +**Senior** + + We have two Linux machines that provide services to our employees. + + 1. The Corporate Server: Provides email, database and web services. + + 2. The Backup Server: It is used to store backup of the important + company data. + +**Junior** + + That's it? Ok, just like Google. + +**Senior** + + Well, I think is time for you to start with your first task. It just + so happens that we received another request to backup the database + from the projects team. diff --git a/docs/source/tutorial/tutorial01.rst b/docs/source/tutorial/tutorial01.rst new file mode 100644 index 0000000..7909556 --- /dev/null +++ b/docs/source/tutorial/tutorial01.rst @@ -0,0 +1,85 @@ +Backup that Database! +===================== + +**Junior** + + A Backup? Don't you have this kind of things already automated? + +**Senior** + + Well, is not that simple. We of course have periodic backups. But, our + project team ask us for a backup every time a project is finished. + + I've already prepared a script to do the task. Before executing it in + production download it and test it in your own machine. + + .. todo:: + + - Link backup script from Github. + +**Junior** + + Ok, done! When I executed it the output says: + + .. code-block:: console + + $ ./backup_db.sh + Backup done! + Your log file is at /tmp/backup_db.log + +**Senior** + + That's right. That script performed the backup and stored it into the + **Backup Server** and appended some information into the backup log + file at ``/tmp/backup_db.log``. + + Now you can SSH into the **Corporate Server** and make the real + backup. + + +**Junior** + + Wait, wait... how long have you been doing this? + + +**Senior** + + This procedure was already here when I arrived. + +**Junior** + + And why don't they do it themselves? I mean, what do you contribute + to the process? + +**Senior** + + I am the only allowed to SSH into the **Corporate Server** for obvious + reasons. + +**Junior** + + Why do you need to SSH in the first place? Couldn't it be done + without SSH? + +**Senior** + + Actually it could be done with a promising new tool I've just found... + Kapow! + + Is a tool that allows you to publish scripts as HTTP services. If we + use it here we can give them the ability to do the backup whenever + they want. + +**Junior** + + Sounds like less work for me. I like it. + +**Senior** + + Ok then, let's try on your laptop first. + + First of all you have to follow the installation instructions XXX. + +**Junior** + + ...