chainguard-dev / apko

Configuration and File Format

This outline details the configuration and file format for the apko project (https://github.com/chainguard-dev/apko/). It outlines the YAML file format used for defining image build processes and configuring the environment and entrypoint.

YAML File Format

The apko project uses YAML files to define the build process. These files are used to specify the image’s environment, entrypoint, and other configuration options. Here’s the general structure of an apko YAML file:

image:
            name: "my-image"
            version: "1.0.0"
            labels:
              - name: "org.chainguard.build.date"
                value: "2023-12-27T13:50:45Z" 
              - name: "org.chainguard.build.version"
                value: "v1.0.0"
            entrypoint: ["/bin/sh"]
            environment:
              - name: "MY_ENV_VAR"
                value: "hello"
            packages: 
              - name: "bash"
            files:
              - source: "path/to/file"
                destination: "/path/on/image"
                mode: "0644"
            commands:
              - name: "install-dependencies"
                run: ["apt-get", "update", "-y"]
              - name: "copy-files"
                run: ["cp", "/path/to/file", "/path/on/image"] 
            # ...

Sections

  • image: Defines the image’s metadata, including name, version, labels, entrypoint, environment, packages, files, and commands.
  • name: Defines the name of the image.
  • version: Defines the version of the image.
  • labels: Specifies labels to be added to the image. Each label is defined with a name and a value.
  • entrypoint: Defines the entrypoint for the image. This is the command that will be executed when the image is run.
  • environment: Defines environment variables to be set in the image. Each environment variable is defined with a name and a value.
  • packages: Lists packages to be installed in the image. Each package is defined with a name.
  • files: Lists files to be copied into the image. Each file is defined with a source (path to the file on the host system), destination (path to the file in the image), and mode (optional, defines file permissions).
  • commands: Defines commands to be run during the build process. Each command is defined with a name and a run array specifying the command to execute.

Configuration Examples

  • Building a base image:

    image:
            name: "my-base-image"
            version: "1.0.0"
            entrypoint: ["/bin/sh"]
            packages:
              - name: "bash"
              - name: "curl"

  • Building an image with custom environment variables and files:

    image:
            name: "my-app-image"
            version: "1.0.0"
            entrypoint: ["/usr/bin/my-app"]
            environment:
              - name: "APP_CONFIG"
                value: "config.json"
            files:
              - source: "config.json"
                destination: "/etc/myapp/config.json"
              - source: "myapp"
                destination: "/usr/bin/my-app"

  • Building an image with a custom script to install dependencies:

    image:
            name: "my-image"
            version: "1.0.0"
            commands:
              - name: "install-dependencies"
                run: ["/bin/sh", "-c", "./install-dependencies.sh"]
            files:
              - source: "install-dependencies.sh"
                destination: "/tmp/install-dependencies.sh"

Running apko

To build an image using an apko configuration file, run the following command:

apko build -f apko.yaml

Replace apko.yaml with the name of your configuration file.

References