Overview

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

Cloud Native Build utilizes Docker containers as the runtime for the build environment. Compared to traditional virtual machines, Docker containers offer significant advantages including faster startup times, lower resource overhead, and superior environment consistency, making them the industry standard for modern CI/CD.

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

Configuration Methods

You can configure the build environment for your pipeline in the following two ways:

1. Use an Existing Image (image) Directly use a pre-built image that has been pushed to a container registry (e.g., Docker Hub, private registry). This is the fastest method.

   • Use Case: Using official images (e.g., node:18) or pre-configured team-internal tool images.
   • Permissions: If using a private image, corresponding registry authentication credentials (username/password) must be configured in the system.
   • Syntax Reference: pipeline.docker.image

2. Build an Image Dynamically (dockerfile) Specify a Dockerfile within your project. At the start of the build, the system will dynamically build an image based on this file for use in subsequent steps.

   • Mechanism: The system first calculates a hash value for the image version. If an image with this hash already exists in the local cache or remote registry, it is used directly, significantly speeding up the build process. Otherwise, it executes docker build to create the image, automatically pushes it to the artifact repository associated with the pipeline project, and reuses it in subsequent builds.
   • Use Case: Complex projects requiring highly customized environments, specific dependencies, or tools.
   • Syntax Reference: pipeline.docker.build

The build environment declared at the pipeline level serves as the default runtime environment for all its script tasks.

Furthermore, individual script tasks can override this and specify their own image environment (Note: Task-level configuration supports only image, not dockerfile). Syntax Reference: Script Task

Examples

Example 1: Using an Existing Image (image)

main:
  push:
    - docker:
        # Declare the official Node.js 22 image as the default build environment for the pipeline
        image: node:22
      stages:
        # The following script tasks will run in the node:22 environment
        - node -v # Output: v22.x.x

Example 2: Building an Image with Dockerfile (build)

1. Create a Dockerfile

image/Dockerfile

# Build a custom environment based on Node.js 20
FROM node:20
# You can install more project-specific global dependencies here
# RUN npm install -g yarn

2. Configure the pipeline to use this Dockerfile

.cnb.yml

main:
  push:
    - docker:
        # Declare to use the project's Dockerfile to build the environment image
        build: image/Dockerfile
      stages:
        # The following script tasks will run in the custom-built environment
        - node -v # Output: v20.x.x

Example 3: Overriding Environment at Task Level

main:
  push:
    - docker:
        # Pipeline default environment
        image: node:22
      stages:
        - node -v # Output: v22.x.x (Uses default environment)
        - name: Task using a specific image version
          image: node:20 # This task overrides and uses Node.js 20
          script:
            - node -v # Output: v20.x.x

Example 4: Using Default Images

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

• Cloud Native Build Default Image: cnbcool/default-build-env
• Workspace Default Image: cnbcool/default-dev-env

main:
  push:
    - stages:
        - stage1
        - stage2
# The above configuration is equivalent to:
# docker:
#   image: cnbcool/default-build-env

main:
  vscode:
    - services:
        - vscode
      stages:
        - stage1
        - stage2
# For Workspace without a specified environment, equivalent to:
# docker:
#   image: cnbcool/default-dev-env

Volume Sharing

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.

Usage Example:

1. Prepare shared data in the Dockerfile:

   FROM alpine
   RUN mkdir /cache && echo 'Initial data' > /cache/data.txt
   VOLUME /cache # Declare /cache as a data volume

2. Access the shared data in a subsequent task:

   - name: Read data from the shared volume
     image: alpine # A task using a different image
     script:
       - cat /cache/data.txt # Successfully outputs: Initial data