• Stars
    star
    747
  • Rank 60,741 (Top 2 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created almost 3 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Build OCI images from APK packages directly without Dockerfile

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

The quickest way to get apko running is to use the OCI Container (Docker) image:

docker run cgr.dev/chainguard/apko version
     _      ____    _  __   ___
    / \    |  _ \  | |/ /  / _ \
   / _ \   | |_) | | ' /  | | | |
  / ___ \  |  __/  | . \  | |_| |
 /_/   \_\ |_|     |_|\_\  \___/
apko

GitVersion:    v0.5.0-67-g9084217
GitCommit:     9084217c907232b8c0bb87fd99c3e65eaa581a5b
GitTreeState:  clean
BuildDate:     '1970-01-01T00:00:00Z'
GoVersion:     go1.18.5
Compiler:      gc
Platform:      linux/amd64

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

These examples use Docker, but should also work with other runtimes such as podman.

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!

Debugging apko Builds

To include debug-level information on apko builds, add --debug to your build command:

docker run --rm -v ${PWD}:/work cgr.dev/chainguard/apko build --debug \
  apko.yaml hello-minicli:test hello-minicli.tar \
  -k melange.rsa.pub

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).

More Repositories

1

osquery-defense-kit

Production-ready detection & response queries for osquery
Makefile
412
star
2

bincapz

detect malicious program behaviors
YARA
401
star
3

ssc-reading-list

A reading list for software supply-chain security.
327
star
4

melange

build APKs from source code
Go
227
star
5

incert

Add CA certificates into containers
Go
121
star
6

edu

Educational Resources for Software Supply Chain Security
HTML
76
star
7

actions

A collection of reusable Github Actions workflows.
65
star
8

justtrustme

Go
50
star
9

bomshell

An SBOM query language and associated utilities
Go
49
star
10

digestabot

Github Action to automatically update digests for container images.
Dockerfile
43
star
11

vex

vexctl is a tool to attest VEX impact statements
Go
43
star
12

bom-shelter

A place to systematically store software bill of materials (SBOM) documents.
Python
42
star
13

darkfiles

Darkfiles finds orphaned files in container images and makes them to bad deeds
Go
39
star
14

osqtool

Automated testing, generation & manipulation of #osquery packs
Go
36
star
15

go-apk

native go library for installation and management of apk packages
Go
29
star
16

registry-redirect

Go
29
star
17

cosign-ecs-verify

Lambda function for verifying signed images in ECS
Go
24
star
18

rules_apko

Bazel rules for apko
Starlark
23
star
19

crow-registry

TypeScript
21
star
20

clank

Simple tool that allows you to detect imposter commits in GitHub Actions workflows.
Go
21
star
21

yam

A sweet little formatter for YAML
Go
20
star
22

hakn

A High-Availability distribution of Knative.
Go
20
star
23

policy-catalog

Go
19
star
24

hello-melange-apko

Demo app duplicated in 5 languages (Go/JavaScript/Python/Ruby/Rust) showing how to go from source code to container image using melange+apko
Rust
19
star
25

tlogistry

Transparenty Immutable Container Image Tags
Go
19
star
26

clog

Context aware slog
Go
17
star
27

maxcve

Go
17
star
28

terraform-provider-apko

Go
14
star
29

image-comparison

Comparison of Chainguard Images to others
HTML
14
star
30

terraform-provider-oci

Terraform provider to perform OCI image operations
Go
12
star
31

exitdir

Common packages.
Go
8
star
32

go-oidctest

Library for creating fake OIDC providers in tests
Go
8
star
33

nginx-image-demo

nginx image demo
8
star
34

terraform-provider-cosign

Terraform provider for Sigstore Cosign
Go
8
star
35

yoloc

YOLO-level verifier
Go
7
star
36

admission-sidecar

Generic webhook controller / proxy for ease of integration with Styra in particular.
Go
7
star
37

terraform-infra-common

A repository containing a collection of "glue" modules for encapsulating common Cloud Run patterns.
HCL
7
star
38

pull-secret-updater

Go
6
star
39

vulnerability-scanner-support

Resources to help vulnerability scanners
6
star
40

stigs

HTML
6
star
41

platform-examples

Example apps demonstrating Chainguard platform integrations
Go
6
star
42

go-grpc-kit

Utility methods for gRPC.
Go
6
star
43

kolide-google-matcher

Unearth host mismatches between Kolide & Google Workspace
Go
6
star
44

learning-labs-static

Base code for Learning Labs: "Build Secure and Minimal Images with Chainguard Static Images"
Go
6
star
45

tekton-demo

Tekton and Sigstore Demo
HCL
5
star
46

terraform-publisher-apko

An experimental module for publishing images with tf-apko
HCL
5
star
47

images-autodocs

This project is now retired 👋
PHP
5
star
48

cve-bliss

Use this repo to submit your final project for the Painless Vulnerability Management With Chainguard course.
Dockerfile
5
star
49

text4shell-policy

ClusterImagePolicy demo for cve-2022-42889 text4shell
Java
4
star
50

melange-php-demos

PHP demos for Melange + Apko
PHP
4
star
51

gobump

Go tool to declaratively bump dependencies.
Go
4
star
52

homebrew-tap

Chainguard Homebrew Tap
Ruby
3
star
53

source-integrity-demo

Shell
3
star
54

tekton-helm-charts

Helm charts for deploying Tekton Pipelines, Dashboard and Chains
Smarty
3
star
55

rumble

Data collection for base image CVEs etc.
Go
3
star
56

sigstore-custom-policies

Repo to contain files demo'd on the CNCF Webinar on the Sigstore Policy Controller
CUE
3
star
57

terraform-google-cron

Terraform module for deploying cron jobs that run on a defined schedule
HCL
3
star
58

go-workqueue

Go
3
star
59

fixfilter

Filter scanner results by applying data from the Wolfi secdb
Go
2
star
60

edu-images-demos

Sample education demos for Chainguard Images
Dockerfile
2
star
61

secureframe-issue-sync

Sync Secureframe tests to GitHub issues (unofficial)
Go
2
star
62

terraform-aws-chainguard-account-association

Terraform module to connect Chainguard Enforce to your AWS Account
HCL
2
star
63

deved-autodocs

DEPRECATED. Moved to chainguard-dev/images-autodocs
PHP
2
star
64

terraform-google-chainguard-account-association

Terraform module to connect Chainguard Enforce to your Google Cloud project
HCL
2
star
65

hello-wolfi-demo

Demo for the Hello Wolfi workshop
PHP
2
star
66

terraform-provider-imagetest

Go
2
star
67

.github

Default files to be used for any public repository under the chainguard-dev organization.
2
star
68

chainguard-weaveworks-gitops-demo

End to End Security & Operations with Chainguard & Weave GitOps
Makefile
2
star
69

terraform-cloudrun-dashboard

THIS HAS MOVED
HCL
2
star
70

openssl-fips-test

Test that OpenSSL is configured to be FIPS-compliant
C
1
star
71

ldso-cache

reading and writing of glibc /etc/ld.so.cache files
Go
1
star
72

terraform-google-prober

A terraform module and Go library for deploying probers to Google Cloud Run
HCL
1
star
73

acls-in-yaml

Collect ACLs from SaaS platforms for periodic user access reviews
Go
1
star
74

field-demos

Public repository of field demos and collaboration and other goodness - it's not pretty, but it's shared ❤️
Dockerfile
1
star
75

go-pkgconfig

Go package for wrangling pkg-config data
Go
1
star
76

go-demo

go demo app
Go
1
star
77

cg-images-python-migration

Sample Flask application migrated to Chainguard Images
Dockerfile
1
star
78

trusted-cert

Un-forked clone of Trusted Cert operator so we can test github actions workflows
Go
1
star