Image 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 registry to store images. This makes it simple for the local Kubernetes cluster to pull images. The registry takes the name of the machine where it was installed. For example, if the machine is named work1-virtualbox, then the registry will be named work1-virtualbox:5000 (where :5000 represents the port on which the registry is accessed). 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.

To check the name of the (virtual) machine where you are running the cluster, run the following command in a terminal:

kubectl get nodes

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

Creating 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.

Vitis Images

If you are creating an image with a particular version of Vitis on it, the name of the image must end in the version of Vitis that is on the image. For example, for an image with Vitis 2020.1, the name of the image must end in 2020-1.