The build environment determines which software and tools are available in the environment when running build tasks, such as JDK, Node, Python, etc.

Cloud Native Build uses Docker containers as the build environment.

Compared to traditional virtual machine containers, Docker containers have significant advantages, and various CI vendors are also moving in this direction.

Having knowledge of Docker and container development experience helps in understanding and using Cloud Native Build.

Configuration Method

There are two ways to configure the pipeline build environment:

1. Specify an Image

   These images are previously created by others and pushed to the image repository.

   If it is a private image, you also need to configure the corresponding username and password to use it.

   Refer to the syntax pipeline.docker.image

2. Specify a Dockerfile

   At the beginning of the build, Cloud Native Build will first calculate the image version number based on some rules. If this version image exists in the current build node or remote image repository, it will be used directly. Otherwise, Cloud Native Build will use the Dockerfile to build the image through docker build, then use it, and push it to the Docker artifact repository of the pipeline for subsequent use.

   Refer to the syntax pipeline.docker.build

The build environment specified by the pipeline will be the default build environment for the script tasks under that pipeline.

Additionally, script tasks can also specify an Image separately as the build environment for that task, in which case a Dockerfile cannot be specified.

Refer to the syntax Script Task.

Examples

Specify Image

main:
  push:
    - docker:
        # Declare the build environment used by the pipeline by default.
        image: node:22
      stages:
        # The script task uses the declared build environment above to run the command
        - node -v # Outputs v22.xx.xx

Specify Dockerfile

image/Dockerfile

FROM node:20

.cnb.yml

main:
  push:
    - docker:
        # Declare the image built by the Dockerfile above as the default build environment for the pipeline.
        build: image/Dockerfile
      stages:
        - node -v # Outputs v20.xx.xx

Script Task Specifies Image

main:
  push:
    - docker:
        # Declare the build environment used by the pipeline by default.
        image: node:22
      stages:
        # This script task uses the declared build environment above to run the command
        - node -v # Outputs v22.xx.xx
        - name: Script Task Specifies Build Environment
          image: node:20
          # This script task uses the specified build environment
          script: node -v # Outputs v20.xx.xx

Default Image

When the pipeline does not specify an Image or Dockerfile, the default image for Cloud Native Build will be set to: cnbcool/default-build-env, and the default image for Cloud-Native Development will be set to: cnbcool/default-dev-env.

main:
  push:
    - stages:
        - stage1
        - stage2
        - stage3
      # Not specifying image and Dockerfile is equivalent to the following declaration
      # docker:
      #   image: cnbcool/default-build-env

main:
  vscode:
    - services:
        - vscode
      stages:
        - stage1
        - stage2
        - stage3
      # Cloud-Native Development not specifying image and Dockerfile is equivalent to the following declaration
      # docker:
      #   image: cnbcool/default-dev-env

VOLUME in Images

Images may contain the VOLUME command. When starting a container with a plugin task, these volumes will be shared with the plugin task using the --volumes-from parameter.

For example, if the Dockerfile prepares a file:

RUN mkdir /cache && echo 'hello world' > /cache/data.txt

VOLUME /cache

It can be accessed in subsequent image-commands.

- name: Accessing pipeline volume in image-commands
  image: alpine
  script:
    - cat /cache/data.txt