diff options
Diffstat (limited to 'doc/user/project/clusters/runbooks/index.md')
| -rw-r--r-- | doc/user/project/clusters/runbooks/index.md | 63 |
1 files changed, 31 insertions, 32 deletions
diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index c67b12fb91a..8df27976662 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -1,28 +1,27 @@ # Runbooks -Runbooks are a collection of documented procedures that explain how to -carry out a particular process, be it starting, stopping, debugging, +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. Using [Jupyter Notebooks](https://jupyter.org/) and the [Rubix library](https://github.com/Nurtch/rubix), users can get started writing their own executable runbooks. - ## Overview -Historically, runbooks took the form of a decision tree or a detailed -step-by-step guide depending on the condition or system. +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 -runbooks", where, along with a well-defined process, operators can execute +Modern implementations have introduced the concept of an "executable +runbooks", where, along with a well-defined process, operators can execute pre-written code blocks or database queries against a given environment. ## Executable Runbooks > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/45912) in GitLab 11.4. -The JupyterHub app offered via GitLab’s Kubernetes integration now ships -with Nurtch’s Rubix library, providing a simple way to create DevOps +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. While Rubix makes it simple to create common Kubernetes and AWS workflows, you can also create them manually without Rubix. @@ -35,33 +34,33 @@ for an overview of how this is accomplished in GitLab!** 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](../index.md#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 +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](../index.md#add-new-gke-cluster). +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 +1. **Ingress** - Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications. -1. **JupyterHub** - [JupyterHub](https://jupyterhub.readthedocs.io/) is a multi-user service for managing notebooks across - a team. Jupyter Notebooks provide a web-based interactive programming environment +1. **JupyterHub** - [JupyterHub](https://jupyterhub.readthedocs.io/) is a multi-user service for managing notebooks across + 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 -down to a couple of lines of code. See the [Nurtch Documentation](http://docs.nurtch.com/en/latest) +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 +down to a couple of lines of code. See the [Nurtch Documentation](http://docs.nurtch.com/en/latest) for more information. ## Configure an executable runbook with GitLab -Follow this step-by-step guide to configure an executable runbook in GitLab using +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](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab) +Follow the steps outlined in [Add new GKE cluster](../index.md#add-new-gke-cluster) to add a Kubernetes cluster to your project. ### 2. Install Helm Tiller, Ingress, and JupyterHub @@ -80,13 +79,13 @@ Once Ingress has been installed successfully, click the **Install** button next ### 3. Login to JupyterHub and start the server -Once JupyterHub has been installed successfully, navigate to the displayed **Jupyter Hostname** URL and click -**Sign in with GitLab**. Authentication is automatically enabled for any user of the GitLab instance via OAuth2. This +Once JupyterHub has been installed successfully, navigate to the displayed **Jupyter Hostname** URL and click +**Sign in with GitLab**. Authentication is automatically enabled for any user of the GitLab instance via OAuth2. This will redirect to GitLab in order to authorize JupyterHub to use your GitLab account. Click **Authorize**.  -Once the application has been authorized you will taken back to the JupyterHub application. Click **Start My Server**. +Once the application has been authorized you will taken back to the JupyterHub application. Click **Start My Server**. The server will take a couple of seconds to start. ### 4. Configure access @@ -103,7 +102,7 @@ Double-click the "Nurtch-DevOps-Demo.ipynb" runbook.  -The contents on the runbook will be displayed on the right side of the screen. Under the "Setup" section, you will find +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 @@ -111,7 +110,7 @@ PRIVATE_TOKEN = 'n671WNGecHugsdEDPsyo' PROJECT_ID = '1234567' ``` -Update the `VARIABLE_NAME` on the last line of this section to match the name of the variable you are using for your +Update the `VARIABLE_NAME` on the last line of this section to match the name of the variable you are using for your access token. In this example our variable name is `PRIVATE_TOKEN`. ```sql @@ -120,8 +119,8 @@ 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. +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} @@ -134,10 +133,10 @@ Create the matching variables in your project's **Settings >> CI/CD >> Variables  -Back in Jupyter, click the "Run SQL queries in Notebook" heading and the click *Run*. The results will be +Back in Jupyter, click the "Run SQL queries in Notebook" heading and the click *Run*. The results will be displayed in-line as follows:  -You can try other operations such as running shell scripts or interacting with a Kubernetes cluster. Visit the -[Nurtch Documentation](http://docs.nurtch.com/) for more information.
\ No newline at end of file +You can try other operations such as running shell scripts or interacting with a Kubernetes cluster. Visit the +[Nurtch Documentation](http://docs.nurtch.com/) for more information. |