apko YAML Reference

A reference guide for writing YAML for apko

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.

DirectiveDescription
repositoriesDefines a list of repositories to look in for packages. These can be either URLs or file paths. File paths should start with a label like @local e.g: @local /github/workspace/packages.
packagesA list containing all packages that should be installed as part of a given image’s requirements.
keyringPGP keys to add to the keyring for verifying packages.

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.

DirectiveDescription
typeWhen this is set to service-bundle, the s6 supervisor will be used to start commands listed in services.
commandSpecifies a command to run when the container starts. Note that this sets the image entrypoint, not the cmd top level element. Only valid when type is not service-bundle.
shell-fragmentBehaves like command, except that the command is a shell fragment. Only valid when type is not service-bundle.
servicesMaps service names to commands that should be started by the s6 supervisor when the container starts. This option is only valid when type is set to service-bundle.

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.

DirectiveDescription
groupsA list with the groups that should be present in this image.
usersA list with the user accounts that should be present in this image.
run-asThe default user to run the entrypoint command.

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.

DirectiveDescription
pathFilesystem path to handle.
typeThe type of file operation to perform. This can be one of the following:
- directory: create an empty directory at the path
- empty-file: create an empty file at the path
- hardlink: create a hardlink (ln) at the path, linking to the value specified in source
- symlink: create a symbolic link (ln -s) at the path, linking to the value specified in source
- permissions: sets file permissions on the file or directory at the path.
run-asThe default user to run the entrypoint command.
uidUID to associate with the file
gidGID to associate with the file
permissionsFile permissions to set. Permissions should be specified in octal e.g. 0o755 (see man chmod for details).
sourceUsed in hardlink and symlink, this represents the path to link to.

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

Last updated: 2023-03-15 11:07