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.
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:
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:
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:
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:
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
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 \
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 install software-properties-common -y
add-apt-repository ppa:deadsnakes/ppa -y
apt install python3.11 -y
Afterwards, we can exit the container:
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:
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.
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.