apko YAML Reference

Apko files are a YAML based declarative definition of an image to be built by apko. Unlike Dockerfiles, there is no support for running arbitrary Unix commands (i.e. there is no equivalent of RUN statements). This means apko can guarantee the contents and reproducibility of the final image, as well as produce extra metadata such as SBOMs.

This page provides a reference for apko’s YAML specification.

contents

This section defines sources and packages you want to include in your image.

Example

contents:
  keyring:
    - https://packages.wolfi.dev/os/wolfi-signing.rsa.pub
  repositories:
    - https://packages.wolfi.dev/os
  packages:
    - wolfi-base
    - nginx

entrypoint

This section defines the default commands and/or services to be executed by the container at runtime.

Services are monitored with the s6 supervisor.

Examples

Example 1: Command entrypoint

entrypoint:
  command: /usr/bin/php81

Example 2: Service entrypoint

entrypoint:
  type: service-bundle
  services:
    php-fpm: /usr/sbin/php-fpm

cmd

Defines a command to run when the container starts up. If entrypoint.command is not set, it will be executed with /bin/sh -c. If entrypoint.command is set, cmd will be passed as arguments to entrypoint.command. This sets the “cmd” value on OCI images.

Example

cmd: help

stop-signal

Configures the shutdown signal sent to the main process in the container by the runtime. By default, this is SIGTERM. Be mindful when using this alongside a service-bundle entrypoint, which will intercept and potentially reinterpret the signal.

Example

stop-signal: SIGQUIT

work-dir

Sets the working directory for the image. Commands defined within the image entrypoint are taken as relative to this path. Equivalent to WORKDIR in Dockerfile syntax.

Example

work-dir: /app

archs

The architectures to build. This top-level directive expects a list with all architectures that should be a target for the build. By default, apko will try to build for all architectures that are currently supported.

Example

archs:
  - x86_64

environment

This section defines environment variables that will be set for this image.

Example

environment:
  PATH: /usr/sbin:/sbin:/usr/bin:/bin
  myVAR: "test"

accounts

This section defines users and groups that should be added to this image.

Example

  users:
    - username: php
      uid: 65532
      gid: 65532
    - username: laravel
      uid: 1000
      gid: 1000
  run-as: 65532

Paths

Defines filesystem operations that can be applied to the image. This includes setting permissions on files or directories as well as creating empty files, directories, and links.

Example

paths:
  - path: /app
    type: directory
    permissions: 0o777
    uid: 65532
    gid: 65532

Includes

Defines a path to a configuration file which should be used as the base config. By default, there is no base config used.

The path can be either a local file, or a file in a remote git repository, in the same style as Go package names and GitHub Actions.

Example

include: github.com/chainguard-dev/apko/examples/alpine-base.yaml@main

This would reference the file examples/alpine-base.yaml in the main branch of the apko git repository.

At present, the path structure assumes that the git repository lives on a site similar to GitHub, GitLab, or Gitea. In other words, given an include path like the above, it will parse as:

host: github.com
repository: chainguard-dev/apko
path: examples/alpine-base.yaml
reference: main

Annotations

annotations defines the set of annotations that should be applied to images and indexes.

Example

annotations:
  image-author: Chainguard
  image-source: http://gihub.com/chainguard-images/images