How apptainer/apptainer works
Project type and purpose
• Apptainer is an open-source, full-stack container platform (formerly Singularity) implemented primarily in Go (with a small C “starter” component).
• It provides a CLI for building, pulling, signing, running, and managing single-file SIF container images, plus a runtime engine (OCI/Apptainer engines), security integrations (seccomp, AppArmor, SELinux), and support for HPC use cases.
File structure
• Top-level “cmd/” holds the Go CLI commands (cmd/apptainer) and a C-based SUID “starter”.
• “internal/” and “pkg/” contain core libraries for building images, managing caches, clients (OCI, library, Shub, ORAS), runtime engines, security, checkpointing, and plugins.
• “e2e/” and “test/” are the end-to-end and unit/integration test suites.
• “dist/” and “makeit/”, “scripts/” support packaging (Debian, RPM, Docker) and release.
• “etc/” provides configuration templates (networks, seccomp, remotes).
• “docs/” and “examples/” supply user/admin documentation and sample definitions.
Key README insights
• Emphasizes: single-file SIF image format, cryptographic signing/encryption, isolation via namespaces/cgroups rather than VMs, HPC focus, mobility, and simplicity.
• References admin and user guides explaining architecture (runtime, security, config).
Main components and interactions
a. Components
• CLI front-end (Go, cmd/apptainer)
• Starter helper (C, SUID, cmd/starter)
• Core libraries (internal/pkg & pkg/*):
– Build subsystem (assemblers, conveyor, sources, SIF packer)
– Client subsystem (OCI, Docker library pulls/pushes, ORAS, Shub)
– Runtime engine (OCI & Apptainer engines, RPC between CLI and starter)
– Security modules (seccomp, AppArmor, SELinux)
– Cgroups, network configuration
– Checkpoint/restore (DMTCP)
– Plugin framework (CLI and runtime callbacks)
• External services: container registry endpoints, keyserver
• Packaging & deployment: “dist/”, “scripts/”
b. Relationships & data flow
1. User invokes CLI → parsed by cmd/apptainer → calls into core libraries.
2. To run containers: CLI communicates with the starter via RPC (starter handles namespace setup, privilege transitions).
3. Runtime engine loads image (SIF) via image/unpacker, applies security profile (seccomp/AppArmor), sets up cgroups/network, launches container process.
4. To build images: CLI calls build subsystem → conveyor pulls sources (registry or local) → assembler layers → SIF packer → output image.
5. Client subsystem handles pulls/pushes to/from external registries, signs/verifies images (signature subsystem).
c. Architectural patterns & principles
• Layered modular design: CLI layer → facade libraries → deep subsystems (build, runtime, client).
• Plugin architecture: callbacks for CLI commands and runtime hooks.
• Clear separation: user-level Go code vs privileged C “starter”
• Reuse of OCI standards (images, runtime config) where possible.
d. Key technologies
• Go modules (internal/ and pkg/), gRPC/RPC between Go and C components
• C starter for SUID privilege separation
• SIF image format
• OCI image/client transports (registry, ORAS, Docker)
• Seccomp/AppArmor/SELinux integrations
• DMTCP checkpointing
Essential details to capture
• The RPC boundary between the Go CLI and the C starter
• The layered build and runtime subsystems within internal/pkg and pkg/
• Integration points for security (seccomp/AppArmor/SELinux) and cgroups
• External service interactions (OCI registries, keyservers)
• The plugin callback mechanism