Build Environment

About 662 wordsAbout 2 min

Overview

The build environment defines the runtime environment for pipeline jobs, containing all the software and tools required for execution, such as JDK, Node.js, Python, and other specific versions.

Cloud Native Build uses Docker containers as the build runtime. Compared to traditional virtual machines, Docker containers offer faster startup, lower resource overhead, and better environment consistency, making them the standard choice in the CI/CD industry.

Tips

Having a basic understanding of Docker will help you better comprehend and utilize Cloud Native Build.

Configuration Methods

You can configure the build environment in the following two ways:

Use Existing Image (image): Directly use a pre-built image that has been pushed to a container registry. Suitable for using official images or team-internal pre-configured public tool images. Private images require registry authentication configuration.
Build Image Dynamically (build): Specify a Dockerfile in the project to dynamically build an image. Suitable for complex projects requiring highly customized environments, specific dependencies, or tools. No special permission requirements.

Use Existing Image (image)

Directly use a pre-built image pushed to a container registry, which is the quickest method.

Syntax Reference: pipeline.docker.image

Build Image Dynamically (build)

Specify a Dockerfile in the project to dynamically build an image at the start of the build, and use it for subsequent pipeline stages.

Mechanism:

The system calculates a hash for the image version
If the image exists in the local cache or remote registry, it is used directly to speed up the build
Otherwise, docker build is executed to create the image, which is automatically pushed to the project's artifact registry for reuse by subsequent builds

Syntax Reference: pipeline.docker.build

Environment Scope

The build environment declared at the pipeline level serves as the default runtime environment for all script tasks. Each script task can also specify its own image environment.

Warning

Task-level configuration only supports image, not dockerfile.

Syntax Reference: Script Task | Script Tasks vs Plugin Tasks

Examples

Example 1: Using Existing Image (image)

.cnb.yml
main:
  push:
    - docker:
        image: node:22
      stages:
        - node -v

Example 2: Building Image with Dockerfile (build)

Step 1: Create a Dockerfile

image/Dockerfile
FROM node:20

Step 2: Configure the pipeline to use this Dockerfile

.cnb.yml
main:
  push:
    - docker:
        build: image/Dockerfile
      stages:
        - node -v

Example 3: Job-Level Override + Default Image

.cnb.yml
main:
  push:
    - docker:
        image: node:22
      stages:
        - node -v
        - name: Using a specific image version
          image: node:20
          script:
            - node -v

Example 4: Using Default Images

When a pipeline does not explicitly specify an image or build configuration, the system automatically uses a default image to ensure a basic environment is available.

Build Type	Default Image Variable
Cloud Native Build	`cnbcool/default-build-env`
Cloud Native Development	`cnbcool/default-dev-env`

.cnb.yml
main:
  push:
    - stages:
        - stage1
        - stage2
# Without explicit environment, equivalent to using cnbcool/default-build-env

Cloud native development works similarly — the default dev image is used when no image is declared:

.cnb.yml
$:
  vscode:
    - services:
        - vscode
      stages:
        - stage1
# Without explicit environment, equivalent to using cnbcool/default-dev-env

If your custom image declares data volumes using the VOLUME instruction (e.g., VOLUME /cache), these volumes are automatically shared with containers started by subsequent plugin tasks.

Application Example

Step 1: Prepare shared data in the Dockerfile

FROM alpine
RUN mkdir /cache && echo 'Initial data' > /cache/data.txt
VOLUME /cache

Step 2: Access the shared data in a subsequent task

- name: Read data from the shared volume
  image: alpine
  script:
    - cat /cache/data.txt

Tips

Volume sharing allows different image tasks to share data, making it ideal for scenarios like caching dependencies and sharing build artifacts.