Welcome to Nurtch documentation!

Nurtch is an internal documentation platform based on Jupyter Notebooks. It’s used by teams to write executable runbooks for quick incident response. Notebook supports markdown text, images, executable code, and output all within the single document served in a browser.

Nurtch is self hosted for complete control, security, and access to your infrastructure in VPC. All Notebooks are stored in S3 bucket you configure. See this for installation.

While Nurtch is great for storing runbooks, it’s also suitable to share any internal documentation within team. You can write onboarding guides, retrieve metrics, automate walk-up requests and such. This documentation is split into two sections:

  • Nurtch Platform

    We talk about the actual Jupyter UI that’s used to write, edit and execute Notebooks. We provide ability to search documents, publish them to S3, store credentials, add team members to Nurtch etc. We also talk about some useful features that are built into Jupyter Notebooks.

  • Rubix Library

    Rubix is a Python library that simplifies common DevOps actions by leveraging infrastructure APIs. Simply put, we abstract the complexity of communicating with AWS/Kubernetes/<Your favourtute tool> APIs.

    Here are some examples of Rubix methods:

    • plot_metrics method fetches metrics data from cloudwatch and renders the graph in Notebook.
    • rollback_deployment quickly rollbacks an ECS service to any prior version. First it communicates with ECS to retrieve rollback candidates. Performs a rollback deployment to a version that you select & shows deployment progress.

Nurtch Platform

Install

Here are installation instructions for setting up Nurtch. Up to 10 Notebooks and unlimited users are free forever. Beyond that, see pricing. To get in touch, sign up or write to us.

Creating New Runbook

Once you are set up and logged into Nurtch, you can create Notebooks/plain text files/directories. Click New and choose the appropriate option.

_images/click_on_new.png

You can choose programming language while creating Notebooks. Thanks to Jupyter, Nurtch supports execution of all major programming languages. Python kernel comes installed out-of-the-box. For other language kernels write to us and we’ll help you with the build.

Editing Runbook

Any Notebook is opened in the viewing mode by default. You can view content, execute code cells, and see output. Editing is disabled to avoid committing unintentional changes. Click on the EDIT button if you want to edit the Notebook.

_images/edit_button.png

Once editing is enabled you can modify the Notebook as you wish. After editing is done you can Preview the Notebook, if you are satisfied with modifications then Publish the changes to S3. At any time you can Discard your changes to go back to original version.

_images/ppd_buttons.png

Add Users to Nurtch

It’s easy to invite your teammates to Nurtch. Go to the Admin tab after you login and click on Add Users To Nurtch. Type in email addresses of users you want to add (separated by comma). Key in a temporary password for them to login with.

Once added these users can login with their email address and the temporary password. They are forced to change the password when they login for the first time. Note that, we do not send email invites via Nurtch to avoid you any SMTP setup. Simply communicate the username (email) and temporary password to newly added users via your regular means of communication.

_images/add_users.png

Run SQL queries in Notebook

It’s super easy to connect to any sql database and run queries against it from the Notebook. There’s a SQL magic that helps you do it. See example below.

_images/run_sql_query.png

Run shell commands in Notebook

You can run shell commands in the Notebook with the help of ! operator. You can also use %%bash magic to run multi-line bash script. Commands are run on the server where Nurtch is hosted. You can also SSH onto a different machine and run commands there from within the Notebook. See examples below.

_images/run_shell_commands.png

Rubix Library

Rubix is a Python library that simplifies common DevOps actions by leveraging infrastructure APIs. Simply put, we abstract the complexity of communicating with AWS/Kubernetes/<Your favourtute tool> APIs and presenting the result in Notebook. Explore the integrations below to know more.

There are lots of services/tools we would like to integrate with Rubix. We are adding new integrations everyday and deepening the existing ones. We are prioritizing integrations based on customer requirements. Write to us if you are looking for specific integration and we’ll be happy to build it for you.

Cloudwatch

plot_metric(namespace, metric_name, **kwargs)

Fetch metric data from Cloudwatch and render it as a graph inside Notebook.

Parameters:
  • namespace (str) – The namespace of the metric e.g. AWS/EC2. All Possible values.
  • metric_name (str) – Name of the metric e.g. Latency. Here’s a way to list all possible metrics for your namespace.
  • **kwargs – These are optional. See below.
Keyword Arguments (Optional):
 
  • start_time (datetime.datetime)
    Time from which to fetch metrics data. Defaults to (end_time - 12 hours)
  • end_time (datetime.datetime)
    Time until which to fetch metrics data. Defaults to current time.
  • statistics (str)
    Metric statistics for your graph e.g. Minimum, Maximum, Sum, Average. All possible values. Deaults to Average
  • markers ([datetime.datetime])
    Markers to indicate timestamp of significant events e.g. you can fetch deployment times with this method and plot them as markers to see metrics’s corelation with deployment. Any marker not between start_time and end_time is simply ignored. Defaults to [].
  • dimensions (dict)
    A name/value pair that uniquely identifies a metric. See this and examples below. When not specified all metrics matching the namespace and metric_name are graphed.
  • aws_access_key_id (str)
    AWS access key of an IAM user to call cloudwatch API. Defaults to environment variable AWS_ACCESS_KEY_ID. Can be overwritten per method by supplying this keyword argument.
  • aws_secret_access_key (str)
    AWS secret access key of an IAM user to call cloudwatch API. Defaults to environment variable AWS_SECRET_ACCESS_KEY. Can be overwritten per method by supplying this keyword argument.
  • aws_region (str)
    AWS region for the resource whose metrics you are plotting. Defaults to environment variable AWS_REGION. Can be overwritten per method by supplying this keyword argument.
Examples:
from rubix.aws.cloudwatch import plot_metric

# Load balancer P90 latency with deployment time markers
plot_metric(namespace='AWS/ELB',
      metric_name='Latency',
      dimensions={'LoadBalancerName': 'prod-xyz-lb'},
      markers=deployment_times,
      statistics='p90')

# Maximum CPU Utilization across EC2 for a specific time period
plot_metric(namespace='AWS/EC2',
      metric_name='CPUUtilization',
      start_time=datetime.datetime(2018, 04, 25),
      end_time=datetime.datetime(2018, 04, 26)
      statistics='Maximum')
Sample Usage and Output:
 _images/plot_metric_example.png

Elastic Container Service (ECS)

rollback_deployment(service, **kwargs)

Quickly rollback an ECS service to any prior version. This method first communicates with ECS to retrieve rollback candidates (prior task definitions that you can rollback to). Performs a rollback deployment to a version that you select. Shows deployment progress.

Parameters:
  • service (str) – The name of your ECS service.
  • **kwargs – These are optional. See below.
Keyword Arguments (Optional):
 
  • cluster (str)
    Name of the ECS cluster to which the service belongs. If the cluster name is not given, ECS uses default cluster. We highly recommend putting your services inside clusters and not using default cluster unless you are just experimenting.
  • aws_access_key_id (str)
    AWS access key of an IAM user to call ECS APIs. Defaults to environment variable AWS_ACCESS_KEY_ID. Can be overwritten per method by supplying this keyword argument.
  • aws_secret_access_key (str)
    AWS secret access key of an IAM user to call ECS APIs. Defaults to environment variable AWS_SECRET_ACCESS_KEY. Can be overwritten per method by supplying this keyword argument.
  • aws_region (str)
    AWS region where the service resides. Defaults to environment variable AWS_REGION. Can be overwritten per method by supplying this keyword argument.
Examples:
from rubix.aws.ecs import rollback_deployment

rollback_deployment(service='xyz-api', cluster='prod-cluster')
Sample Usage and Output:
 _images/ecs_rollback.png
get_latest_deployment_status(service, **kwargs)

Retrieve metadata of last deployment on your ECS service. Metadata includes deployment time, desired/pending/running counts, task definition etc.

Parameters:
  • service (str) – The name of your ECS service.
  • **kwargs – These are optional. See below.
Returns:

dict – See response section below.

Keyword Arguments (Optional):
 
  • cluster (str)
    Name of the ECS cluster to which the service belongs. If the cluster name is not given, ECS uses default cluster.
  • aws_access_key_id (str)
    AWS access key of an IAM user to call ECS APIs. Defaults to environment variable AWS_ACCESS_KEY_ID. Can be overwritten per method by supplying this keyword argument.
  • aws_secret_access_key (str)
    AWS secret access key of an IAM user to call ECS APIs. Defaults to environment variable AWS_SECRET_ACCESS_KEY. Can be overwritten per method by supplying this keyword argument.
  • aws_region (str)
    AWS region where the service resides. Defaults to environment variable AWS_REGION. Can be overwritten per method by supplying this keyword argument.
Response:
  • id (str)
    The ID of the deployment.
  • taskDefinition (str)
    The most recent task definition that was specified for the service to use.
  • desiredCount (int)
    The most recent desired count of tasks that was specified for the service to deploy or maintain.
  • pendingCount (int)
    The number of tasks in the deployment that are in the PENDING status.
  • runningCount (int)
    The number of tasks in the deployment that are in the RUNNING status.
  • createdAt (datetime.datetime)
    The Unix time stamp for when the deployment was created.
  • updatedAt (datetime.datetime)
    The Unix time stamp for when the service was last updated.
Examples:
from rubix.aws.ecs import get_latest_deployment_status

get_latest_deployment_status(service='hello-world-service', cluster='prod-cluster')
Sample Usage and Output:
 _images/latest_deployment_status.png

Relational Database Service (RDS)

Work in progress. Stay tuned.

If you are simply looking for a way to run SQL queries, see Run SQL queries in Notebook.

Kubernetes

Now you can operate Kubernetes cluster from Nurtch notebooks. You can either use the familiar kubectl commands or use higher level APIs provided by Rubix library.

Setup

Once you login, go to the admin tab and upload Kubernetes config file. The file is typically located at ~/.kube/config. Tip: You might need to press (CMD + Shift + .) on mac to show hidden files in the finder.

_images/ss_k8s_config.png

Once uploaded, wait for a minute for the config to propagate to all the nodes in your cluster. You can verify if the config is propagated as shown below.

_images/ss_k8s_verify.png

That’s it! Now you can use kubectl commands and rubix.kubernetes.* methods to operate your cluster (examples below).

Command Line Usage

You can upload and use your existing scripts in the notebook or use one-off commands as shown in the examples below.

  • List all running services.
_images/k8s_list_services.png
  • See when deployments occurred in your cluster by checking replica sets.
_images/k8s_get_rs.png
  • See the rollout history with kubectl rollout history <resource_name> and rollback to the version you wish.
_images/k8s_rollback.png
  • Check the status of your deployment rollout.
_images/k8s_rollout_status.png

API Usage

get_latest_deployment_status(service_name, namespace='default', context=None)

Retrieve metadata of last deployment on your Kubernetes service. Metadata includes deployment time, desired/available/current counts, container image etc.

Parameters:
  • service (str) – Name of your Kubernetes service.
  • namespace (str) – Namespace under which your service is running, if using namespaces.
  • context – Context under which your service is running, if using context. Since context specifies the trio of (cluster, user, namespace) you don’t need to specify namespace separately while using context.
Returns:

dict – See response section below.

Response:
  • desiredCount (int)
    The desired number of replicas of the application.
  • availableCount (int)
    The number of replicas that are available to your users.
  • currentCount (int)
    The number of replicas that are currently running.
  • createdAt (datetime.datetime)
    The Unix time stamp for when the deployment was created.
  • containerImage (str)
    The name of container image + tag that got deployed.
Examples:
from rubix.kubernetes import get_latest_deployment_status

get_latest_deployment_status(service_name='nurtch-1')
Sample Usage and Output:
 _images/rubix_k8s_get_deployment_status.png