Skip to content

Latest commit

 

History

History
244 lines (216 loc) · 7.82 KB

recipe-structure.md

File metadata and controls

244 lines (216 loc) · 7.82 KB
Raw
Title Description PublicationDate Authors Tags
Structure of a Vib recipe
Learn about the structure of a Vib recipe.
2024-02-13
mirkobrombin
kbdharun
lambdaclan
modules
recipe

Note Stages were introduced in Vib v0.6.0, if you are using an older version, please keep in mind all the stage fields are at the top level of the recipe, so no multiple stages are supported.

A Vib recipe is a YAML file that contains the instructions to build a container image. It's composed of two blocks:

  • metadata
  • stages

The following is a complete example of a Vib recipe:

# metadata
name: My Image
id: my-image-id

# stages
stages:
  - id: build
    base: debian:sid-slim
    singlelayer: false
    labels:
      maintainer: My Awesome Team
    adds:
      - srcdst:
          /extra/path/to/add/1: /path/to/destination/1
    # multiple additions
    # adds:
    #  - srcdst:
    #      /extra/path/to/add/1: /path/to/destination/1
    #      /extra/path/to/add/2: /path/to/destination/2
    # specify working directory for destination
    # adds:
    #  - workdir: /tmp
    #    srcdst:
    #      /extra/path/to/add/1: .
    #      /extra/path/to/add/2: .
    args:
      - arg1: value1
      - arg2: value2
    runs:
      commands:
        - some-random-command --that-must-run --on-top-of-all modules
        - another-command --help
    # specify working directory for commands
    # runs:
    #  workdir: /app
    #  commands:
    #    - cp /tmp/start.sh .
    #    - start.sh
    # copy from host
    copy:
      - paths:
          - src: /app/awesome.txt
            dst: .
    # copy multiple
    # copy:
    #   - paths:
    #     - src: /app/awesome.txt
    #       dst: .
    #     - src: /tmp/test.txt
    #       dst: .
    # specify working directory for destination
    # copy:
    #   - workdir: /tmp
    #     paths:
    #       - src: /app/awesome.txt
    #         dst: .
    #       - src: /app/test.txt
    #         dst: .
    #   - workdir: /etc
    #     paths:
    #       - src: /app/hello.txt
    #         dst: .
    modules:
      - name: build
        type: go
        buildvars:
          GO_OUTPUT_BIN: "/path/to/output"
        source:
          url: https://github.com/my-awesome-team/my-awesome-repo
          type: git
          branch: main
          commit: sdb997f0eeb67deaa5940f7c31a19fe1101d3d49
        modules:
          - name: build-deps
            type: apt
            source:
              packages:
                - golang-go

  - id: dist
    base: debian:sid-slim
    singlelayer: false
    labels:
      maintainer: My Awesome Team
    expose:
      "8080": "tcp"
      "8081": ""
    entrypoint:
      exec:
        - /app
    # entrypoint command with params
    # entrypoint:
    #  exec:
    #    - npm
    #    - run
    # specify working directory for entrypoint command
    # entrypoint:
    #  workdir: /app
    #  exec:
    #    - npm
    #    - run
    # copy from previous stage
    copy:
      - from: build
        paths:
          - src: /path/to/output
            dst: /app
    # copy from previous stage with custom working directory for destination
    # copy:
    #   - workdir: /app
    #     from: build
    #     paths:
    #       - src: /path/to/output
    #         dst: .
    cmd:
      exec:
        - /app
    # command with params
    # cmd:
    #   exec:
    #     - npm
    #     - run
    # specify working directory for command
    # cmd:
    #   workdir: /app
    #   exec:
    #     - npm
    #     - run
    modules:
      - name: run
        type: shell
        commands:
          - ls -la /app
    # specify working directory for all module commands
    # modules:
    #   - name: run
    #     type: shell
    #     workdir: /app
    #     commands:
    #       - ls -la

Metadata

The metadata block contains the following mandatory fields:

  • base: the base image to start from, can be any Docker image from any registry or even scratch.
  • name: the name of the image.
  • id: the ID of the image is used to specify an image's unique identifier, it is used by platforms like Atlas to identify the image.
  • stages: a list of stages to build the image, useful to split the build process into multiple stages (e.g. to build the application in one stage and copy the artifacts into another one).

Stages

Stages are a list of instructions to build an image, useful to split the build process into multiple stages (e.g. to build the application in one stage and copy the artifacts into another one). Each stage is a YAML snippet that defines a set of instructions.

Each stage has the following fields:

  • singlelayer: a boolean value that indicates if the image should be built as a single layer. This is useful in some cases to reduce the size of the image (e.g. when building an image using a rootfs, an example here).
  • labels: a map of labels to apply to the image, useful to add metadata to the image that can be read by the container runtime.
  • adds: a list of files or directories to add to the image, useful to include files in the image that are not part of the source code (the preferred way to include files in the image is to use the includes.container/ directory, see Project Structure).
  • args: a list of environment variables to set in the image.
  • runs: a list of commands to run in the image (as an alternative to the shell module, useful for dividing the commands of your recipe from those needed to configure the image, for example, to disable the recommended packages in apt).
  • expose: a list of ports to expose in the image.
  • cmd: the command to run when the container starts.
  • entrypoint: the entry point for the container, it's similar to cmd but it's not overridden by the command passed to the container at runtime, useful to handle the container as an executable.
  • copy: a list of files or directories to copy from another stage (or copy from host), useful to copy files from one stage to another.
  • modules: a list of modules to use in the stage.

Modules

The modules block contains a list of modules to use in the recipe. Each module is a YAML snippet that defines a set of instructions. The common structure is:

- name: name-of-the-module
  type: type-of-the-module
  # specific fields for the module type

Refer to the Use Modules article for more information on how to use modules in a recipe and Built-in Modules for a list of the built-in modules and their specific fields.

You can also write your custom modules by making a Vib plugin, see the Making a Plugin article for more information.

Copying files between stages

You can copy files between stages using the copy field. This consists of a list of files or directories to copy from another stage. Each item in the list is a YAML snippet that defines the source and destination of the copy operation. The common structure is:

- from: stage-id-to-copy-from
  paths:
    - src: /path/to/source
      dst: /path/to/destination

For example, to copy the /path/to/output directory from the build stage to the /app directory in the dist stage, you can use the following snippet:

- from: build
  paths:
    - src: /path/to/output
      dst: /app

so it becomes available in the dist stage.

Using a custom working directory (workdir)

The following commads are supported:

  • adds
    • workdir sets destination path
  • copy
    • workdir sets destination path
  • runs
    • workdir changes directory (cd) before executing command
  • cmd
    • workdir changes directory (cd) before executing command
  • entrypoint
    • workdir changes directory (cd) before executing command
  • modules
    • workdir changes directory (cd) before executing command list