OCI Image Building

Overview

The apko project builds OCI container images. It uses a declarative approach to image construction, where users define the image’s content through configuration files. Apko then translates this configuration into a series of actions, producing a fully compliant OCI image.

This outline will cover the process of building OCI container images using apko, including:

• Configuration Files: Defining the image’s content.
• Layer Generation: How apko creates the individual layers of an OCI image.
• SBOM Generation: How apko creates Software Bill of Materials (SBOMs) for the built images.
• Final Image Assembly: How apko combines the layers and metadata to produce the final OCI image.

Configuration Files

Apko leverages a configuration file, typically named apko.yaml, to define the image’s structure and content. This file follows a YAML structure and includes essential directives like:

• Image Name and Tag: Defining the name and tag of the resulting image.
• Base Image: Specifying the base image used as a starting point.
• Packages: Defining the packages to be installed in the image.
• Files: Specifying files to be copied into the image.
• Commands: Defining commands to execute during the image build process.
• Environment Variables: Setting environment variables within the image.

Example:

name: my-image
          tag: latest
          base: alpine:latest
          packages:
            - curl
            - bash
          files:
            - source: .
              dest: /app
          commands:
            - ["apk", "update"]
            - ["apk", "add", "python3"]
          

Layer Generation

Apko generates individual layers to construct the final OCI image. Each layer represents a specific set of modifications to the image, providing a more efficient and granular approach to image building. Layers are generated based on the directives defined in the apko.yaml file. For example, installing packages, copying files, and executing commands will each create a distinct layer.

SBOM Generation

Apko supports generating Software Bill of Materials (SBOMs) for built images. SBOMs provide a structured representation of the software components included in the image, facilitating vulnerability analysis and supply chain security. Apko leverages the syft tool to generate SBOMs in various formats, including SPDX and CycloneDX.

Example:

apko build --sbom
          

Final Image Assembly

Once all the individual layers are generated, apko assembles them into a single OCI image. This involves creating the image manifest, which describes the layers and their relationships, and combining them into a tar archive conforming to the OCI image specification. The final image is ready for distribution and deployment.

Additional Features

Apko offers various features to enhance the image building process:

• Multi-stage Builds: Allows for creating more efficient images by using separate stages for different tasks.
• Custom Layers: Enables users to define their own custom layers for specific tasks.
• Caching: Reuses previously built layers to speed up the build process.
• Integration with CI/CD Pipelines: Provides seamless integration with popular CI/CD pipelines for automated image building.

References:

• apko Documentation
• apko Configuration File
• apko Build Command
• syft Tool