2018-10-26 16:09:26 +00:00
# Runbooks
Runbooks are a collection of documented procedures that explain how to
carry out a particular process, be it starting, stopping, debugging,
or troubleshooting a particular system.
2019-02-28 20:23:31 +00:00
Using [Jupyter Notebooks ](https://jupyter.org/ ) and the [Rubix library ](https://github.com/Nurtch/rubix ),
users can get started writing their own executable runbooks.
2018-10-26 16:09:26 +00:00
## Overview
Historically, runbooks took the form of a decision tree or a detailed
step-by-step guide depending on the condition or system.
Modern implementations have introduced the concept of an "executable
2018-11-09 22:54:09 +00:00
runbooks", where, along with a well-defined process, operators can execute
pre-written code blocks or database queries against a given environment.
2018-10-26 16:09:26 +00:00
## Nurtch Executable Runbooks
2018-10-26 16:42:57 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/45912) in GitLab 11.4.
2018-10-26 16:09:26 +00:00
The JupyterHub app offered via GitLab’ s Kubernetes integration now ships
with Nurtch’ s Rubix library, providing a simple way to create DevOps
runbooks. A sample runbook is provided, showcasing common operations.
**< i class = "fa fa-youtube-play youtube" aria-hidden = "true" > < / i >
Watch this [video ](https://www.youtube.com/watch?v=Q_OqHIIUPjE )
2019-02-23 12:49:55 +00:00
for an overview of how this is accomplished in GitLab!**
2018-10-26 16:09:26 +00:00
## Requirements
To create an executable runbook, you will need:
1. **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications.
The simplest way to get started is to add a cluster using [GitLab's GKE integration ](https://docs.gitlab.com/ee/user/project/clusters/#adding-and-creating-a-new-gke-cluster-via-gitlab ).
1. **Helm Tiller** - Helm is a package manager for Kubernetes and is required to install
all the other applications. It is installed in its own pod inside the cluster which
can run the helm CLI in a safe environment.
1. **Ingress** - Ingress can provide load balancing, SSL termination, and name-based
virtual hosting. It acts as a web proxy for your applications.
2019-02-28 20:23:31 +00:00
1. **JupyterHub** - [JupyterHub ](https://jupyterhub.readthedocs.io/ ) is a multi-user service for managing notebooks across
2018-10-26 16:09:26 +00:00
a team. Jupyter Notebooks provide a web-based interactive programming environment
used for data analysis, visualization, and machine learning.
## Nurtch
Nurtch is the company behind the [Rubix library ](https://github.com/Nurtch/rubix ). Rubix is
an open-source python library that makes it easy to perform common DevOps tasks inside Jupyter Notebooks.
Tasks such as plotting Cloudwatch metrics and rolling your ECS/Kubernetes app are simplified
2018-11-09 22:54:09 +00:00
down to a couple of lines of code. See the [Nurtch Documentation ](http://docs.nurtch.com/en/latest )
2018-10-26 16:13:10 +00:00
for more information.
2018-11-07 17:16:52 +00:00
## Configure an executable runbook with GitLab
Follow this step-by-step guide to configure an executable runbook in GitLab using
the components outlined above and the preloaded demo runbook.
### 1. Add a Kubernetes cluster
Follow the steps outlined in [Adding and creating a new GKE cluster via GitLab ](https://docs.gitlab.com/ee/user/project/clusters/#adding-and-creating-a-new-gke-cluster-via-gitlab )
to add a Kubernetes cluster to your project.
### 2. Install Helm Tiller, Ingress, and JupyterHub
2018-11-09 22:59:11 +00:00
Once the cluster has been provisioned in GKE, click the **Install** button next to the **Helm Tiller** app.
2018-11-07 17:16:52 +00:00
![install helm ](img/helm-install.png )
2018-11-09 22:59:11 +00:00
Once Tiller has been installed successfully, click the **Install** button next to the **Ingress** app.
2018-11-07 17:16:52 +00:00
2018-11-07 19:36:38 +00:00
![install ingress ](img/ingress-install.png )
2018-11-07 17:16:52 +00:00
2018-11-09 22:59:11 +00:00
Once Ingress has been installed successfully, click the **Install** button next to the **JupyterHub** app.
2018-11-07 17:16:52 +00:00
2018-11-07 19:45:26 +00:00
![install jupyterhub ](img/jupyterhub-install.png )
2018-11-07 17:16:52 +00:00
### 3. Login to JupyterHub and start the server
2018-11-09 22:54:09 +00:00
Once JupyterHub has been installed successfully, navigate to the displayed **Jupyter Hostname** URL and click
2018-11-12 15:48:29 +00:00
**Sign in with GitLab**. Authentication is automatically enabled for any user of the GitLab instance via OAuth2. This
2018-11-09 22:54:09 +00:00
will redirect to GitLab in order to authorize JupyterHub to use your GitLab account. Click **Authorize** .
2018-11-07 17:16:52 +00:00
![authorize jupyter ](img/authorize-jupyter.png )
2018-11-12 15:48:29 +00:00
Once the application has been authorized you will taken back to the JupyterHub application. Click **Start My Server** .
2018-11-07 17:16:52 +00:00
The server will take a couple of seconds to start.
### 4. Configure access
2018-11-09 22:59:11 +00:00
In order for the runbook to access your GitLab project, you will need to enter a
[GitLab Access Token ](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html )
as well as your Project ID in the **Setup** section of the demo runbook.
2018-11-07 17:16:52 +00:00
2018-11-09 22:54:09 +00:00
Double-click the **DevOps-Runbook-Demo** folder located on the left panel.
2018-11-07 17:16:52 +00:00
![demo runbook ](img/demo-runbook.png )
2018-11-09 22:54:09 +00:00
Double-click the "Nurtch-DevOps-Demo.ipynb" runbook.
2018-11-07 17:16:52 +00:00
![sample runbook ](img/sample-runbook.png )
The contents on the runbook will be displayed on the right side of the screen. Under the "Setup" section, you will find
entries for both your `PRIVATE_TOKEN` and your `PROJECT_ID` . Enter both these values, conserving the single quotes as follows:
```sql
2018-11-12 15:48:29 +00:00
PRIVATE_TOKEN = 'n671WNGecHugsdEDPsyo'
2018-11-07 17:16:52 +00:00
PROJECT_ID = '1234567'
```
2018-11-09 22:54:09 +00:00
Update the `VARIABLE_NAME` on the last line of this section to match the name of the variable you are using for your
2018-11-07 17:16:52 +00:00
access token. In this example our variable name is `PRIVATE_TOKEN` .
```sql
VARIABLE_VALUE = project.variables.get('PRIVATE_TOKEN').value
```
### 5. Configure an operation
For this example we'll use the "**Run SQL queries in Notebook**" section in the sample runbook to query
a postgres database. The first 4 lines of the section define the variables that are required for this query to function.
```sql
%env DB_USER={project.variables.get('DB_USER').value}
%env DB_PASSWORD={project.variables.get('DB_PASSWORD').value}
%env DB_ENDPOINT={project.variables.get('DB_ENDPOINT').value}
%env DB_NAME={project.variables.get('DB_NAME').value}
```
Create the matching variables in your project's **Settings >> CI/CD >> Variables**
![gitlab variables ](img/gitlab-variables.png )
2018-11-09 22:54:09 +00:00
Back in Jupyter, click the "Run SQL queries in Notebook" heading and the click *Run* . The results will be
2018-11-07 17:16:52 +00:00
displayed in-line as follows:
![postgres query ](img/postgres-query.png )
2018-11-09 22:54:09 +00:00
You can try other operations such as running shell scripts or interacting with a Kubernetes cluster. Visit the
2018-11-07 17:16:52 +00:00
[Nurtch Documentation ](http://docs.nurtch.com/ ) for more information.