Docker Build Executors and Docker Images

A Docker image defines the operating system and software packages your organization's members need to run builds on a Docker executor. You can either import a Docker image from an external Docker registry, such as DockerHub, or create it from a build executor template.

Unlike a VM executor, a Docker executor is not directly associated with any specific VM. When your organization's members create jobs, they simply associate a Docker image as a build template with the job. When the job's build triggers, VB Studio runs the build on any Docker deployment VM.

Some key points to remember about Docker images:

When you create an image from a build executor template, VB Studio creates a new Docker image by installing the software configured in that template. When you create an image from a registry, VB Studio pulls the image from the registry, adds a build agent, and creates a new image.
You can specify the maximum number of executors that can be created from the image.
You can create as many Docker images as you require, as long as the Management VM has enough space.

Docker Deployment VMs and Docker Executors

Docker executors run in a Docker deployment VM. Like a VM build executor, a Docker deployment VM is an OCI VM Compute instance dedicated to run builds.

To run builds in Docker executors, you add Docker deployment VMs. A Docker executor can run only one build at a time, but a Docker deployment VM can run multiple builds simultaneously, depending on how many Docker executors are configured for the deployment VM. The maximum number of Docker executors that can be run by a given Docker deployment VM is configurable between 1 and 10.

When a job's build is triggered, VB Studio starts a Docker deployment VM if it is in a stopped state, creates a Docker executor in it, and builds the job using the executor.

Remember, a Docker deployment VM costs you only when it's in a running state and actively building jobs. When the Docker deployment VM is idle and not building jobs, it'll be put to sleep. You can configure the number of minutes the deployment VM remains idle before it is put to sleep.

This table describes the Docker deployment VM states:

State	What does it mean?	Does it cost?
Pending	After you add a Docker deployment VM, it is in this state until the management VM finishes building, and then it will start automatically.	No
Starting	The Docker deployment VM is starting. If the Docker deployment VM starts from the Pending state, VB Studio installs the operating system and software packages on the Docker deployment VM's assigned boot volume. This takes time. If the Docker deployment VM starts from the Stopped state, VB Studio uses software packages and the operating system from the previous run's saved boot volume.	Yes
Ready	The operating system and Docker agent are installed and started. The VM is ready to deploy Docker executors.	Yes
Stopping	The Docker deployment VM is shutting down. Before shutting the Docker deployment VM down, VB Studio saves the operating system and software packages to the Docker deployment VM's assigned boot volume.	Yes
Stopped	The Docker deployment VM has shut down.	No
Error	There's a hardware or a software issue on the Docker deployment VM. Check the Docker deployment VM's log to find more about the cause.	No

Some key points to remember about Docker deployment VMs and Docker executors:

Once created, the Docker Management VM is always running and costs you 24-7. To keep your costs lower, if you are planning to run fewer builds with fewer images, select a smaller shape with fewer OCPUs.
To run builds in Docker executors, you add Docker deployment VMs and specify the number of Docker executors it can run, select the OCI region from the connected OCI account's subscribed regions, the OCI Compute VM's shape, and optionally the VCN.
Your OCI account may have some Compute instance limits set. When you add a Docker deployment VM, VB Studio looks into the specified OCI region's Availability Domains, finds available OCPUs with the specified shape, calculates the number of Compute instances, and displays the number of Compute VM instances you can add from your OCI account's set limit.
When you add your first Docker deployment VM, VB Studio adds one more VM, called the Docker Management VM, to manage Docker images.
The Docker Management VM is responsible for creating Docker images and Docker executors and for deploying images to Docker executors.
When you create your first Docker deployment VM, the Docker Management VM is also created with the same shape.
VB Studio provides a default shape selection for the management VM. This default is only a recommendation. Some things to consider:
- You could still choose a lower-end configuration for your specific purposes, but the default is what VB Studio determines to be the optimal powered VM for the management VM. Although a low-end VM (such as Standard 1.1 with 1 CPU and 8 GB of memory) could be used for Docker Image management in scenarios that have few Executor templates and create just a few Docker images, it is better to use the default recommendation. If you try to select a lower-powered VM than what is recommended, you'll see a warning.
- For scenarios that have several Executor templates and will create several Docker images, using a high-end VM (such as VM.Standard.E3.Flex with 4 OCPU and 32 GB RAM) instead is recommended. Using a low-end VM in demanding scenarios will severely hamper overall performance.
If a Docker deployment VM is not in use, it will eventually time out and enter the Stopped state, which has no associated cost to you.
The higher the number of Docker deployment VMs running Docker executors at any specific time, the higher the associated cost. To minimize the higher cost, you should configure the sleep timeout to stop inactive Docker deployment VMs after some period of time. The default timeout is 300 minutes. The sleep timeout setting will be applied to all your organization's Docker deployment VMs.

What Happens When a Build Runs on a Docker Executor?

VB Studio checks the Docker image that corresponds with the template configured in the job and finds whether a build of the image has run before.
If this is the Docker image's first build, it finds a Docker deployment VM to run the image in an executor, and then it downloads the image from the Docker Management VM if the image doesn't already exist in the VM.

If one or more Docker deployment VMs are found, VB Studio selects a Docker deployment VM to run the build in this order:
1. If a Docker deployment VM is in the Ready state and has at least one Docker executor that's not running, VB Studio runs the build on it. A Docker deployment VM is full if VB Studio has already deployed the maximum number of executors on that VM.
2. If no Docker deployment VMs are in the Ready state, VB Studio starts a Stopped Docker deployment VM and runs the build on one of its Docker executors.
3. If all Docker executors of all Docker deployment VMs are running builds, VB Studio waits for a Docker executor to complete its build, and then runs a build on it.
If this is not the Docker image's first build, VB Studio finds the Docker deployment VM that ran the image's Docker executor earlier and uses it to run the build again, unless the Docker deployment VM is full. If all Docker executors of the Docker deployment VM are busy running builds, VB Studio selects another Docker deployment VM to run the build in the above described order.
VB Studio checks the job's configuration and runs the commands in the specified order.
After the build is complete, VB Studio copies any generated artifacts to the configured OCI Object Storage bucket.
The Docker deployment VM waits for some time for any queued builds. If no builds run during the wait time period, the Docker deployment VM stops.
Before stopping the Docker deployment VM, VB Studio saves the Docker image to the Docker deployment VM's assigned boot volume.