Architecture

The binderhub-service chart runs the BinderHub Python software, in api-only mode (the default), as a standalone service to build, and push Docker images from source code repositories, on demand, using repo2docker. This service can then be paired with JupyterHub to allow users to initiate build requests from their hubs.

Architecture requirements

Thus, the architecture of this system must:

• facilitate the building and pushing of Docker images with repo2docker

• easily integrate with a JupyterHub deployment

• but also run as a standalone service

• operate within a Kubernetes environment

Architecture overview

Tip

Checking out the BinderHub’s architecture diagram might also be helpful.

Details on how it works

When a build & push request is fired, the following events happen:

1. BinderHub creates and starts a build pod that runs repo2docker

   The build pods are managed by BinderHub through KubernetesBuildExecutor and are created as a result of an image build request.

   For the image build to work, the docker client processes running on these nodes need to be able to communicate with the dockerd daemon. This communication is done via unix socket mounted on the node.

2. repo2docker use a docker client to build and push images

   A running dockerd daemon will intercept the docker commands initiated by the the docker client processes running on these build pods. This dockerd daemon is setup by the docker-api pods.

   The docker-api pods are setup to start on each node matching the dockerApi.nodeSelector by the following DaemonSet definition.

   The daemonset also setups a hostPath volume that mounts a unix socket from this node into the docker-api pods.

   Important

   The docker-api pods and the build pods must run on the same node so they can use the unix socket on it to interact with the docker daemon listening on this socket.

3. the build pods will then use the configured credentials to push the image to the repository

   The build pods mount a k8s Secret with the docker config file holding the necessary registry credentials so they can push to the container registry.

Warning

The binderhub-service chart currently only supports Docker. Checkout https://github.com/2i2c-org/binderhub-service/issues/31 for updates on Podman support.

Technical stack