Container Registry
A registry is a place where container images are stored. When a job is started, the necessary image is pulled from the registry to create a local copy of the image on the machine where the job will be run. The container runtime on the machine orchestrates a container using the local copy of the image and the job will be run.
The installation process of BeetleboxCI sets up a local docker registry to store images. This makes it simple for the local Kubernetes cluster to pull images.
BeetleboxCI also has the capability to pull images from remote registries such as Dockerhub and Amazon ECR—when the user configures jobs (using a config file in their codebase), they need to define the name of the image and the registry where the image is located for the job to run.
Access
The registry can be accessed by issuing a HTTPS request to the name or IP address of the server where it was installed.
For example, if the registry is on a machine named work1-virtualbox, then the registry can be accessed on work1-virtualbox:5000 (where :5000 represents the port on which the registry is accessed).
If the IP address of the machine is 192.168.1.91, then the registry can be accessed on 192.168.1.91:5000.
If the fully qualified domain name of the machine is work1-virtualbox.internal.beetlebox.org, then the registry can be accessed on work1-virtualbox.internal.beetlebox.org:5000.
You can directly check the images in the registry using the following command (adjust the IP or DNS name as required):
curl -sS https://192.168.1.91:5000/v2/_catalog
To check the name of the (virtual) machine where you are running the cluster, run the following command in a terminal:
kubectl get nodes
In most applications, your registry will be running on the main control node.
Infrastructure
The picture below summarises the mechanism by which BeetleboxCI operates. This shows a registry with a number of different images such as Ubuntu and Nginx. The containers live on the host machine. Local copies of images are also cached on the host machine, from which the containers are created.
Prebuilt Images
Beetlebox provides two prebuilt Ubuntu and Centos images to run basic applications. These images are stored on a public online registry and they are automatically saved to the local registry that was created during the BeetleboxCI installation process. If you are using the prebuilt virtual machine image, you can access these two images using:
docker pull work1-virtualbox:5000/ubuntu-generic
docker pull work1-virtualbox:5000/centos-generic
If you want to directly access the images stored in the public online registry:
docker pull public.ecr.aws/y2s4f3y9/ubuntu-generic
docker pull public.ecr.aws/y2s4f3y9/centos-generic
The Ubuntu image in the local registry can be used to run jobs by including the following in the .bbx/config.yaml file in your git repository:
runners:
ubuntu-runner:
image: work1-virtualbox:5000/ubuntu-generic:latest
The Centos image in the local registry can be used to run jobs by including the following in the .bbx/config.yaml file in your git repository:
runners:
centos-runner:
image: work1-virtualbox:5000/centos-generic:latest
The Ubuntu image in the online public registry can be used to run jobs by including the following in the .bbx/config.yaml file in your git repository:
runners:
ubuntu-runner:
image: public.ecr.aws/y2s4f3y9/ubuntu-generic
The Centos image in the online public registry can be used to run jobs by including the following in the .bbx/config.yaml file in your git repository:
runners:
centos-runner:
image: public.ecr.aws/y2s4f3y9/centos-generic
Adding Customised Images
The user may optionally create their own images and upload them to the local registry, or pull remote images and push them to the local registry if they want to save time on repeatedly pulling large images from remote registries. For the user to create their own images, we recommend using Docker, but they may use another tool if they wish.
Let's assume that the user is running their Kubernetes cluster on a machine named work1-virtualbox and they want to create a customised Ubuntu-based image with Python 3.11 on it. At the time of writing this guide, the latest available Ubuntu image had Python 3.10 installed on it, not Python 3.11.
Please note that the following commands need to be executed on the (virtual) machine where BeetleboxCI (hence the local container registry) is installed.
To create a customised image, the user can begin with the official Ubuntu image from Dockerhub.
sudo systemctl start docker # ensures that the Docker service is running
docker pull ubuntu:latest
docker images
The Image ID that is displayed may be different from the example shown here:
REPOSITORY TAG IMAGE ID CREATED SIZE
ubuntu latest 58db3edaf2be 4 weeks ago 77.8MB
We can see that the Ubuntu image has been pulled. The image ID may be different from the one shown here.
We can then start a container using this image. The following command creates and starts a new container:
docker run --privileged \
-it 58db3edaf2be
root@f03835aa459a:/#
Docker will assign an ID to the container, which is distinct from the ID of the image. In this case, the assigned container ID is f03835aa459a.
You can now run the following commands to install Python 3.11:
apt update
apt install software-properties-common -y
add-apt-repository ppa:deadsnakes/ppa -y
apt install python3.11 -y
Afterwards, we can exit the container:
root@f03835aa459a:/# exit
We can check the status of the container(s) that are on the machine. Docker assigns a random name to the container (in this case, "elastic_boyd"):
docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
f03835aa459a 58db3edaf2be "/bin/bash" 9 minutes ago Exited (0) 59 seconds ago elastic_boyd
The user can then create a new image from the container using the following command:
docker commit f03835aa459a
We can see the image that we just created using:
docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
<none> <none> 3f3526212bcf 20 seconds ago 339MB
ubuntu latest 58db3edaf2be 2 weeks ago 77.8MB
This image then needs to be tagged. The tag shows the repository where the image will be stored ("work1-virtualbox:5000"), the image name ("ubuntu_python"), and the image version ("latest").
docker tag 3f3526212bcf work1-virtualbox:5000/ubuntu_python:latest
Finally, the tagged image can be pushed. Docker will push to the registry specified in the tag.
docker push work1-virtualbox:5000/ubuntu_python:latest
The image work1-virtualbox:5000/ubuntu_python:latest can now be used to create containers for users to run jobs in BeetleboxCI, by specifying this in the config file included within the user's codebase.
Adding Images from Remote Registries
The user can manually pull images from a remote registry using docker, change the tag and push it to the local registry.
If they prefer, they can use the web interface of BeetleboxCI to generate a script to do this for them by clicking the Add Image option.
They can enter the URL of the registry and image to pull the image from and select if this registry is public or not.
When pulling from a remote private registry, they may need to edit the docker login command in the script with their specific credentials to access a private registry.
They can either run the script or run the commands manually to copy the remote image to their local registry.
Removing Images
Removing images from the docker registry is a bit more involved than adding images. Clicking the delete button will open up this prompt.
Once you download the script, you can run it on the control node directly or your can copy and paste the commands into a terminal. It will mark the image for deletion and restart the registry pod.
Due to the mechanism by which docker registries operate, images may sometimes not be fully deleted. Images are built and stored in layers and those which were built from the same base image will share some layers. Such shared layers will not be deleted unless all the images which reference those layers are deleted.