hub23-deploy

A repository to manage the private Turing BinderHub instance, Hub23.

| | :recycle: CI Status | | --- | --- | | :moneywithwings: Subscription | | | :rocket: Deployment | | | :broom: Linting and Formatting | | | :notebook: Docs | |

Table of Contents:

• :wheelofdharma: Hub23 Helm Chart
• :rocket: Developing Hub23
  • :pushpin: Requirements
  • :repeat: Changing hub23-chart
• :question: How-To's
  • :housewithgarden: Work Locally
  • :electric_plug: Connect to Kubernetes
• :computer: Code Snippets
  • :dizzy: Restarting the JupyterHub
  • :moneywithwings: Billing
• :books: Documentation

:wheelofdharma: Hub23 Helm Chart

This repository contains the local Helm Chart that configures the Hub23 BinderHub deployment: hub23-chart.

The HelmUpgradeBot automatically opens Pull Requests to this repository that update the dependencies of the Helm Chart in the requirements.yaml file.

Upon merging the Pull Request, the Continuous Deployment Azure Pipeline automatically applies the updated Helm Chart to the Kubernetes cluster running Hub23.

:rocket: Developing Hub23

Please read the :purpleheart:Code of Conduct:purpleheart: and :spaceinvader:Contributing Guidelines:spaceinvader: before you begin developing.

:pushpin: Requirements

Three command line interfaces are used to manage Hub23:

• Azure CLI - to manage the Azure compute resources
• Kubernetes CLI (kubectl) - to manage the Kubernetes cluster
• Helm CLI - to manage the BinderHub application running on the Kubernetes cluster

:repeat: Changing hub23-chart

If changes are made during development, make sure that:

• the new format is reflected in deploy/prod-template.yaml and any new secrets/tokens/passwords are redacted;
• new secrets/tokens/passwords are added to the Azure Key Vault (see the Key Vault docs); and
• .az-pipelines/cd-pipeline.yml is updated in order to populate the template with the appropriate information.

This will ensure that the Hub23 deployment is kept up-to-date with the repo, and a future developer (someone else or future-you!) can recreate the configuration files for Hub23.

:question: How-To's

:housewithgarden: Work Locally

If you DO have write access: :black_nib:

```bash

Clone this repository

git clone https://github.com/alan-turing-institute/hub23-deploy.git cd hub23-deploy

Create a new branch

git checkout -b NEWBRANCHNAME ```

And you're ready to go! :tada:

If you DON'T have write access: :no_good:

1. Click "Fork" in the top-right corner of the browser window
2. Select your GitHub username as the fork destination
3. Clone the forked repository

```bash

Clone your fork

git clone https://github.com/YOURGITHUBUSERNAME/hub23-deploy.git cd hub23-deploy

Create a new branch

git checkout -b NEWBRANCHNAME ```

:electric_plug: Connect to Kubernetes

This section uses the Azure CLI.

1. Login to Azure

   bash az login

2. Set the Azure subscription

   bash az account set --subscription turingmybinder

3. Connect to the cluster

   bash az aks get-credentials --name turing --resource-group binder-prod

:computer: Code Snippets

To find out more info about a Kubernetes pod:

bash kubectl --namespace hub23 describe pod POD_NAME

:dizzy: Restarting the JupyterHub

If the Hub is being problematic, for example, throwing "Internal Server Error" messages or not spinning up user nodes, it can be restarted with the following commands.

Scale down the Hub:

bash kubectl --namespace hub23 scale deployment hub --replicas=0

Wait until the hub- pod has been terminated. Use kubectl --namespace hub23 get pods to check its status.

Scale the Hub back up:

bash kubectl --namespace hub23 scale deployment hub --replicas=1

:moneywithwings: Billing

The billing subdir contains resources for calculating running costs of Hub23.

:books: Documentation

The Deployment Guide docs for Hub23 are stored in the docs folder. A GitHub Action workflow renders the documentation using Jupyter Book and publishes it to the gh-pages branch of the repo to be hosted at https://alan-turing-institute.github.io/hub23-deploy