Linux hosted agents
Linux instances for Buildkite hosted agents are offered with two architectures:
- AMD64 (x64_86)
- ARM64 (AArch64)
To accommodate different workloads, instances are capable of running up to 8 hours. If you require longer running agents, please contact support at support@buildkite.com.
Sizes
Buildkite offers a selection of Linux instance types (each based on a different combination of size and architecture, known as an instance shape), allowing you to tailor your hosted agent resources to the demands of your jobs.
Instance shape | Size | Architecture | vCPU | Memory | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Instance shape | Instance shape |
LINUX_AMD64_2X4
|
Size | Size | Small | Architecture | Architecture | AMD64 | vCPU | vCPU | 2 | Memory | Memory | 4 GB |
Instance shape | Instance shape |
LINUX_AMD64_4X16
|
Size | Size | Medium | Architecture | Architecture | AMD64 | vCPU | vCPU | 4 | Memory | Memory | 16 GB |
Instance shape | Instance shape |
LINUX_AMD64_8X32
|
Size | Size | Large | Architecture | Architecture | AMD64 | vCPU | vCPU | 8 | Memory | Memory | 32 GB |
Instance shape | Instance shape |
LINUX_AMD64_16X64
|
Size | Size | Extra Large | Architecture | Architecture | AMD64 | vCPU | vCPU | 16 | Memory | Memory | 64 GB |
Instance shape | Instance shape |
LINUX_ARM64_2X4
|
Size | Size | Small | Architecture | Architecture | ARM64 | vCPU | vCPU | 2 | Memory | Memory | 4 GB |
Instance shape | Instance shape |
LINUX_ARM64_4X16
|
Size | Size | Medium | Architecture | Architecture | ARM64 | vCPU | vCPU | 4 | Memory | Memory | 16 GB |
Instance shape | Instance shape |
LINUX_ARM64_8X32
|
Size | Size | Large | Architecture | Architecture | ARM64 | vCPU | vCPU | 8 | Memory | Memory | 32 GB |
Instance shape | Instance shape |
LINUX_ARM64_16X64
|
Size | Size | Extra Large | Architecture | Architecture | ARM64 | vCPU | vCPU | 16 | Memory | Memory | 64 GB |
Extra large instances are available on request. Please contact support@buildkite.com to have them enabled for your account.
Agent images
Buildkite provides a Linux agent image pre-configured with common tools and utilities to help you get started quickly. This image also provides tools required for running jobs on hosted agents.
The image is based on Ubuntu 20.04 and includes the following tools:
- docker
- docker-compose
- docker-buildx
- git-lfs
- node
- aws-cli
You can customize the image that your hosted agents use by creating an agent image.
Create an agent image
Creating an agent image requires you to define a Dockerfile that installs the tools and utilities you require. This Dockerfile should be based on the Buildkite hosted agent base image.
An example Dockerfile that installs the awscli
and kubectl
:
# Set the environment variable to avoid interactive prompts during awscli installation
ENV DEBIAN_FRONTEND=noninteractive
# Install AWS CLI
RUN apt-get update && apt-get install -y awscli
# Install kubectl using pkgs.k8s.io
RUN curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl \
&& chmod +x kubectl \
&& mv kubectl /usr/local/bin/
You can create an agent image:
- Select Agents in the global navigation to access the Clusters page.
-
Select the cluster in which to create the new agent image.
Note: Before continuing, ensure you have created a Buildkite hosted queue (based on Linux architecture) within this cluster. Learn more about how to do this in Create a Buildkite hosted queue.
Select Agent Images to open the Agent Images page.
Select New Image to open the New Agent Image dialog.
Enter the Name for your agent image.
-
In the Dockerfile field, enter the contents of your Dockerfile.
Notes:
- The top of the Dockerfile contains the required
FROM
instruction, which cannot be changed. This instruction obtains the required Buildkite hosted agent base image. - Ensure any modifications you make to the existing Dockerfile content are correct before creating the agent image, since mistakes cannot be edited or corrected once the agent image is created.
- The top of the Dockerfile contains the required
Select Create Agent Image to create your new agent image.
Use an agent image
Once you have created an agent image, you can set it as the default image for any Buildkite hosted queues based on Linux architecture within this cluster. Once you do this for such a Buildkite hosted queue, any agents in the queue will use this agent image in new jobs.
To set a Buildkite hosted queue to use a custom Linux agent image:
- Select Agents in the global navigation to access the Clusters page.
- Select the cluster with the Linux architecture-based Buildkite hosted queue whose agent image requires configuring.
- On the Queues page, select the Buildkite hosted queue based on Linux architecture.
- Select the Base Image tab to open its settings.
- In the Agent image dropdown, select your agent image.
- Select Save settings to save this update.
Delete an agent image
To delete a previously created agent image, it must not be used by any Buildkite hosted queues.
To delete an agent image:
- Select Agents in the global navigation to access the Clusters page.
- Select the cluster in which to delete the agent image.
- Select Agent Images to open the Agent Images page.
-
Select the agent image to delete > Delete.
Note: If you are prompted that the agent image is currently in use, follow the link/s to each Buildkite hosted queue on the Delete Image message to change the queue's Agent image (from the Base Image tab) to another agent image.
On the Delete Image message, select Delete Image and the agent image is deleted.
Using agent hooks
You can create a custom agent image and modify its Dockerfile to embed the following types of job lifecycle hooks as agent hooks:
environment
, pre-checkout
, checkout
, post-checkout
, pre-command
, command
, post-command
, pre-artifact
, post-artifact
, and pre-exit
.
Be aware that the pre-bootstrap
job lifecycle hook and agent lifecycle hooks operate outside of a job's execution itself, and are therefore not supported within a Buildkite hosted agent context.
To embed hooks in your agent image's Dockerfile:
-
Follow the Create an agent image instructions to begin creating your hosted agent within its Linux architecture-based Buildkite hosted queue.
As part of this process, modify the agent image's Dockerfile to:
- Add the
BUILDKITE_ADDITIONAL_HOOKS_PATHS
environment variable whose value is the path to where the hooks will be located. - Add any specific hooks to the path defined by this variable.
An example excerpt from a
Dockerfile
that would include your own hooks:ENV BUILDKITE_ADDITIONAL_HOOKS_PATHS=/custom/hooks COPY ./hooks/*.sh /custom/hooks/
This results in an agent image with the directory
/custom/hooks
that includes any.sh
files located at./hooks/
from where the image is created. - Add the
Follow the Use an agent image to apply this new agent image to your Buildkite hosted queue.
Buildkite hosted agents run with the BUILDKITE_HOOKS_PATH
value of /buildkite/agent/hooks
, which is the global agent hooks location. This path is fixed and is read-only when a job starts. Therefore, avoid setting the value of BUILDKITE_ADDITIONAL_HOOKS_PATHS
to this path in your agent image's Dockerfile, as any files you copy across to this location will be overwritten when the job commences.