Top Related Projects
🥑 Language focused docker images, minus the operating system.
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:
- Install Apko:
go install chainguard.dev/apko@latest
- 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
- Build the image:
apko build example.yaml myimage:latest myimage.tar
- Load the image into your local Docker daemon:
docker load < myimage.tar
- 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.
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 designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
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).
Top Related Projects
🥑 Language focused docker images, minus the operating system.
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
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot