Add a new hub¶
This section describes steps around adding hubs to the 2i2c JupyterHub federation.
Infrastructure that is needed for a hub¶
There are three kinds of infrastructure needed to add a new hub. In most cases, they are configured via configuration in the
A Kubernetes cluster. Deploying a Kubernetes cluster is specific to the cloud provider. For hubs that do not need to use their own cloud credits, or otherwise are fine running on a cloud project that is not owned by their institution, we can deploy hubs on an already-running Kubernetes Cluster. For hubs that require their own cluster, we’ll need to set it up on our own. To do so, see [new-cluster].
Support infrastructure. This is a collection of services that run on a Kubernetes Cluster and help us in running and monitoring things. There is one set of services running per cluster, not per hub. This includes things like Grafana, NFS server provisioners, etc.
JupyterHubs. When a cluster is up and running, we may then deploy JupyterHubs on top of it using the JupyterHub Helm Chart. Configuration that is specific to each JupyterHub is stored in the
config/hubsfolder. GitHub actions then deploy and update hubs on a cluster using this configuration. There are some cases where you must manually deploy or modify a hub. See Manually deploy hubs for more details.
Overview of hub configuration¶
Many of our hubs are automatically deployed and updated using GitHub Workflows and configuration that is defined in
These are a collection of YAML files (one per cluster) that define the configuration for all of our hubs.
To learn which subset of clusters are automatically deployed via GitHub workflows, inspect the
matrix:cluster_name: list in the
The process of automatically updating and adding hubs is the same for all of the hubs deployed on these clusters.
To add a new hub¶
To deploy a new hub, follow these steps:
Ask the Community Representative to fill in this issue template. This will create a “New Hub” issue and ask the representative questions that are important for understanding how to set up their hub. Once that issue is created, move to the next step.
Decide whether you’ll deploy on a pre-existing Kubernetes cluster, or if you’ll need to create a new one. See When to deploy a new Kubernetes cluster for information to help you decide.
Determine the hub template that is needed. Hub templates are pre-configured deployments for certain kinds of JupyterHubs. There are a few base templates to choose from. For more information about our templates and how to choose, see Hub templates.
Add a configuration entry for your new hub. Each entry is a Zero to JupyterHub configuration, and you can customize whatever you like. The easiest way to add new configuration is to look at the entries for similar hubs in the same cluster YAML file, copy / paste one of them, and make modifications as needed for this specific hub. For example, see the entries in the 2i2c Google Cloud cluster configuration file.
See Configuration Structure for more information about template configuration.
Create a Pull Request with the new hub entry, and get a team member to review it.
Once you merge the pull request, the GitHub Workflow will detect that a new entry has been added to the configuration file. It will then deploy a new JupyterHub with the configuration you’ve specified onto the corresponding cluster.
Monitor the action to make sure that it completes. If something goes wrong and the action does not finish, then check its logs to understand what is going on. It may be necessary to make new changes to the hub’s configuration via a Pull Request, or to revert the old Pull Request if you cannot determine how to resolve the problem.
Log in to the hub and ensure that the hub works as expected from a user’s perspective.
Send a link to the hub’s Community Representative(s) so they can confirm that it works from their perspective as well.
Automated vs. manual deploys¶
Some of our infrastructure automatically deploys and updates hubs via GitHub Workflows, while others require manual deploys. This is changing over time as we automate more things, and is dependent on the cloud provider.
The best place to look to learn about the latest state of our automatic hub deployment is to look at the
deploy-hubs.yaml GitHub workflow.
That workflow defines the automatic hub deployment for many of our major clusters.
See the sections below for information about deploying hubs on each cloud provider, including whether to manually or automatically deploy.