Convert Figma logo to code with AI

chainguard-dev logoapko

Build OCI images from APK packages directly without Dockerfile

1,157
113
1,157
96

Top Related Projects

🥑 Language focused docker images, minus the operating system.

19,214

Slim(toolkit): Don't change anything in your container image and minify it by up to 30x (and for compiled languages even more) making it secure too! (free and open source)

A toolkit for building secure, portable and lean operating systems for containers

An operating system designed for hosting containers

Quick Overview

Apko is an open-source tool for building OCI (Open Container Initiative) images using declarative YAML configurations. It focuses on creating minimal, secure container images by leveraging Alpine Linux packages and applying best practices for container security.

Pros

  • Produces minimal and secure container images
  • Uses declarative YAML configurations for reproducible builds
  • Integrates well with CI/CD pipelines
  • Supports multi-architecture builds

Cons

  • Limited to Alpine Linux packages
  • Steeper learning curve compared to traditional Dockerfiles
  • May require additional effort to customize images for specific use cases
  • Documentation could be more comprehensive for advanced use cases

Getting Started

To get started with Apko, follow these steps:

  1. Install Apko:
go install chainguard.dev/apko@latest
  1. Create a YAML configuration file (e.g., example.yaml):
contents:
  repositories:
    - https://dl-cdn.alpinelinux.org/alpine/edge/main
  packages:
    - alpine-base

entrypoint:
  command: /bin/sh -l

archs:
  - x86_64
  1. Build the image:
apko build example.yaml myimage:latest myimage.tar
  1. Load the image into your local Docker daemon:
docker load < myimage.tar
  1. Run the container:
docker run --rm -it myimage:latest

This will create a minimal Alpine Linux-based container image and run it using Docker.

Competitor Comparisons

🥑 Language focused docker images, minus the operating system.

Pros of distroless

  • Well-established project with a large user base and community support
  • Provides a variety of pre-built base images for different languages and runtimes
  • Extensive documentation and examples for various use cases

Cons of distroless

  • Limited customization options for base images
  • Larger image sizes compared to apko-built images
  • Less flexibility in terms of package selection and configuration

Code Comparison

distroless Dockerfile:

FROM gcr.io/distroless/static-debian11
COPY myapp /
CMD ["/myapp"]

apko build command:

apko build apko.yaml myapp:latest myapp.tar

Key Differences

  • apko focuses on building minimal, from-scratch images with precise control over included packages
  • distroless provides ready-to-use base images for common scenarios
  • apko allows for more granular customization of the resulting image
  • distroless offers a simpler approach for users who don't need extensive customization

Both projects aim to improve container security and reduce image size, but they take different approaches to achieve these goals. apko provides more flexibility and control, while distroless offers a more straightforward solution for common use cases.

19,214

Slim(toolkit): Don't change anything in your container image and minify it by up to 30x (and for compiled languages even more) making it secure too! (free and open source)

Pros of Slim

  • Supports multiple container runtimes (Docker, containerd, etc.)
  • Offers a user-friendly CLI and web UI for easier operation
  • Provides advanced features like HTTP probing and reverse engineering

Cons of Slim

  • May require more setup and configuration compared to apko
  • Can potentially over-optimize, leading to unexpected behavior in some cases
  • Slower image creation process due to its analysis and optimization steps

Code Comparison

apko:

contents:
  repositories:
    - https://dl-cdn.alpinelinux.org/alpine/edge/main
  packages:
    - alpine-base
    - python3

Slim:

slim build --target my-image:latest --tag my-slim-image:latest

Key Differences

apko focuses on building minimal, secure images from scratch using declarative configurations, while Slim optimizes existing container images by analyzing and removing unnecessary components. apko is more suited for creating purpose-built, minimal images, whereas Slim excels at reducing the size of existing images across various container runtimes.

Both tools aim to improve container security and reduce image size, but they approach the problem from different angles. apko is ideal for organizations looking to build secure images from the ground up, while Slim is better for those wanting to optimize existing images or integrate image slimming into their CI/CD pipelines.

A toolkit for building secure, portable and lean operating systems for containers

Pros of LinuxKit

  • More comprehensive system-building approach, allowing for the creation of complete, customized Linux distributions
  • Supports multiple architectures and platforms, including cloud and virtualization environments
  • Offers a modular design, enabling easy customization and extension of the base system

Cons of LinuxKit

  • Steeper learning curve due to its more complex architecture and broader scope
  • May be overkill for simpler container image creation tasks
  • Requires more resources and time to build complete systems compared to lightweight alternatives

Code Comparison

LinuxKit example (YAML configuration):

kernel:
  image: linuxkit/kernel:5.10.76
  cmdline: "console=tty0 console=ttyS0 console=ttyAMA0"
init:
  - linuxkit/init:v0.8
  - linuxkit/runc:v0.8
  - linuxkit/containerd:v0.8

apko example (YAML configuration):

contents:
  repositories:
    - https://dl-cdn.alpinelinux.org/alpine/edge/main
  packages:
    - alpine-base
    - busybox
entrypoint:
  command: /bin/sh

While both tools use YAML for configuration, LinuxKit's approach is more comprehensive, defining kernel, init system, and runtime components. apko focuses on package selection and basic container configuration, making it simpler for straightforward container image creation tasks.

An operating system designed for hosting containers

Pros of Bottlerocket

  • Comprehensive container-optimized OS with a full Linux distribution
  • Designed for production use in cloud environments
  • Includes advanced security features like automatic updates and immutable root filesystem

Cons of Bottlerocket

  • Larger footprint and more complex than apko
  • Less flexible for custom configurations
  • Slower build times due to its comprehensive nature

Code Comparison

Bottlerocket (example of update configuration):

[updates]
metadata-base-url = "https://updates.bottlerocket.aws"
targets-base-url = "https://updates.bottlerocket.aws"
seed = "0123456789abcdef0123456789abcdef"

apko (example of image configuration):

contents:
  repositories:
    - https://dl-cdn.alpinelinux.org/alpine/edge/main
  packages:
    - alpine-base
    - busybox

While Bottlerocket provides a full OS configuration, apko focuses on minimal container image creation. Bottlerocket's code examples often involve system-level configurations, whereas apko's typically center around package and repository management for building lightweight container images.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

apko: apk-based OCI image builder

Build and publish OCI container images built from apk packages.

apko has the following key features:

  • Fully reproducible by default. Run apko twice and you will get exactly the same binary.
  • Fast. apko aims to build images in ms.
  • Small. apko generated images only contain what's needed by the application, in the style of distroless.
  • SBOM Support. apko produces a Software Bill of Materials (SBOM) for images, detailing all the packages inside.
  • Services. apko supports using the s6 supervision suite to run multiple processes in a container without reaping or signalling issues.

Please note that apko is a work in progress and details are subject to change!

Installation

You can install apko from Homebrew:

brew install apko

You can also install apko from source:

go install chainguard.dev/apko@latest

You can also use the apko container image:

docker run cgr.dev/chainguard/apko version

To use the examples, you'll generally want to mount your current directory into the container, e.g.:

docker run -v "$PWD":/work cgr.dev/chainguard/apko build examples/alpine-base.yaml apko-alpine:edge apko-alpine.tar

Alternatively, if you're on a Mac, you can use Lima to run an Alpine Linux VM.

Quickstart

An apko file for building an Alpine base image looks like this:

contents:
  repositories:
    - https://dl-cdn.alpinelinux.org/alpine/edge/main
  packages:
    - alpine-base

entrypoint:
  command: /bin/sh -l

# optional environment configuration
environment:
  PATH: /usr/sbin:/sbin:/usr/bin:/bin

We can build this with apko from any environment with apk tooling:

apko build examples/alpine-base.yaml apko-alpine:test apko-alpine.tar
...
2022/04/08 13:22:31 apko (aarch64): generating SBOM
2022/04/08 13:22:31 building OCI image from layer '/tmp/apko-3027985148.tar.gz'
2022/04/08 13:22:31 OCI layer digest: sha256:ba034c07d0945abf6caa46fe05268d2375e4209e169ff7fdd34d40cf4e5f2dd6
2022/04/08 13:22:31 OCI layer diffID: sha256:9b4ab6bb8831352b25c4bd21ee8259d1f3b2776deec573733291d71a390157bb
2022/04/08 13:22:31 output OCI image file to apko-alpine.tar

or, with Docker:

docker run -v "$PWD":/work cgr.dev/chainguard/apko build examples/alpine-base.yaml apko-alpine:test apko-alpine.tar

You can then load the generated tar image into a Docker environment:

docker load < apko-alpine.tar
Loaded image: apko-alpine:test
docker run -it apko-alpine:test
e289dc84c4ad:/# echo boo!
boo!

You can also publish the image directly to a registry:

apko publish examples/alpine-base.yaml myrepo/alpine-apko:test

See the docs for details of the file format and the examples directory for more, err, examples!

Why

apko was created by Chainguard, who require secure and reproducible container images for their tooling. Speed is also a critical factor; Chainguard require images to be rebuilt constantly in response to new versions and patches.

The design of apko is heavily influenced by the ko and distroless projects.

Declarative Nature

By design, apko doesn't support an equivalent of RUN statements in Dockerfiles. This means apko files are fully declarative and allows apko to make stronger statements about the contents of images. In particular, apko images are fully bitwise reproducible and can generate SBOMs covering their complete contents.

In order to install bespoke tooling or applications into an image, they must first be packaged into an apk. This can be done with apko's sister tool melange.

The combination of melange and apko cover the vast majority of use cases when building container images. In the cases where they are not a good fit, our recommendation is to build a base image with apko and melange, then use traditional tooling such as Dockerfiles for the final step.

Support and Further Reading

Tutorials and guides for apko can be found at the Chainguard Academy.

For support, please find us on the Kubernetes Slack in the #apko channel or open an issue.

Related Work and Resources

The melange project is designed to produce apk packages to be used in apko.

The ko project builds Go projects from source in a similar manner to apko.

The kontain.me service creates fresh container images on demand using different forms of declarative configuration (including ko and apko).