apt-ostree/docs/oci-integration.md

OCI Integration

Overview

apt-ostree now includes comprehensive OCI (Open Container Initiative) integration, allowing you to convert OSTree deployments into container images. This enables testing apt-ostree in real OSTree environments and provides a bridge between atomic system deployments and container ecosystems.

Features

✅ Implemented Features

1. OCI Image Generation

• Convert OSTree commits to OCI container images
• Support for both OCI and Docker image formats
• Proper OCI specification compliance
• Content-addressed image layers with SHA256 digests

2. Base Image Resolution

• Parse base image references (e.g., ubuntu:24.04)
• Map to OSTree branch names (e.g., ubuntu/24.04/x86_64)
• Pull base images from OSTree registries
• Local caching and validation

3. Compose Workflow Integration

• apt-ostree compose create - Create deployments from base images
• apt-ostree compose build-image - Convert deployments to OCI images
• apt-ostree compose list - List available base images

🔄 Planned Features

1. Registry Integration

• Push/pull images to/from container registries
• Registry authentication and authorization
• Image signing and verification
• Multi-arch image support

2. Bootc Compatibility

• Generate bootc-compatible images
• Proper metadata for bootc deployment
• Integration with bootc ecosystem

Usage

Basic OCI Image Generation

# Create a deployment from a base image
apt-ostree compose create --base ubuntu:24.04 --packages nginx apache2

# Convert the deployment to an OCI image
apt-ostree compose build-image my-deployment my-image:latest --format oci

# Convert to Docker format
apt-ostree compose build-image my-deployment my-image:latest --format docker

Advanced Usage

# Create deployment with custom output branch
apt-ostree compose create \
  --base ubuntu:24.04 \
  --packages nginx apache2 vim \
  --output my-custom-deployment

# Build OCI image from specific commit
apt-ostree compose build-image \
  abc123def456... \
  my-registry.com/my-image:latest \
  --format oci

# List available base images
apt-ostree compose list

Architecture

OCI Image Builder

┌─────────────────────────────────────────┐
│              OCI Image Builder          │
├─────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐      │
│  │   OSTree    │  │   OCI       │      │
│  │   Commit    │  │   Image     │      │
│  └─────────────┘  └─────────────┘      │
├─────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐      │
│  │ Filesystem  │  │   Image     │      │
│  │  Layer      │  │  Manifest   │      │
│  └─────────────┘  └─────────────┘      │
└─────────────────────────────────────────┘

Workflow

1. OSTree Checkout: Extract filesystem from OSTree commit
2. Layer Creation: Create compressed filesystem layer
3. Config Generation: Generate OCI configuration
4. Manifest Creation: Create OCI manifest with digests
5. Image Assembly: Package into OCI or Docker format

Implementation Details

OCI Specification Compliance

The implementation follows the OCI Image Specification v1.0:

• Schema Version: 2
• Media Types:
  • application/vnd.oci.image.config.v1+json
  • application/vnd.oci.image.layer.v1.tar+gzip
  • application/vnd.oci.image.manifest.v1+json
• Digest Algorithm: SHA256
• Layer Compression: Gzip

Image Structure

OCI Format

my-image.oci/
├── index.json          # Image index
├── blobs/
│   └── sha256/
│       ├── abc123...   # Config blob
│       └── def456...   # Layer blob
└── manifest.json       # Image manifest

Docker Format

my-image.tar
├── manifest.json       # Docker manifest
├── config.json         # Image config
└── layer.tar.gz        # Compressed layer

Base Image Resolution

// Parse base image reference
let base_image = parse_base_image_ref("ubuntu:24.04")?;
// Result: BaseImageRef { distribution: "ubuntu", version: "24.04", architecture: None }

// Map to OSTree branch
let ostree_branch = format!("{}/{}/{}", 
    base_image.distribution, 
    base_image.version, 
    base_image.architecture.as_deref().unwrap_or("x86_64")
);
// Result: "ubuntu/24.04/x86_64"

Testing

Unit Tests

# Run OCI-specific tests
cargo test oci

# Run all tests
cargo test

Integration Tests

# Test OCI image generation
./test-oci.sh

# Test with real OSTree commits
apt-ostree compose create --base ubuntu:24.04 --dry-run
apt-ostree compose build-image test-commit my-test-image --format oci

Validation

# Validate OCI image structure
skopeo inspect oci:my-image.oci

# Validate Docker image
docker load < my-image.tar
docker run --rm my-image:latest echo "Hello from apt-ostree!"

Error Handling

Common Errors

Base Image Not Found

Error: Base image not found locally: ubuntu:24.04
Solution: Ensure the base image is available in the OSTree repository

Invalid Source Reference

Error: Invalid base image reference format: invalid-ref
Solution: Use format like "ubuntu:24.04" or "debian/12/x86_64"

OSTree Checkout Failed

Error: Failed to checkout commit: abc123...
Solution: Verify the commit exists and is accessible

Recovery

The OCI builder includes automatic cleanup of temporary files and proper error propagation:

impl Drop for OciImageBuilder {
    fn drop(&mut self) {
        // Clean up temp directory on drop
        if self.temp_dir.exists() {
            let _ = std::fs::remove_dir_all(&self.temp_dir);
        }
    }
}

Performance Considerations

Optimization Strategies

1. Layer Deduplication: Reuse existing layers when possible
2. Parallel Processing: Process multiple layers concurrently
3. Streaming: Stream large files without loading into memory
4. Caching: Cache base images and intermediate results

Memory Usage

• Temporary Storage: Uses system temp directory for intermediate files
• Streaming: Large files are processed in chunks
• Cleanup: Automatic cleanup of temporary files

Security

Image Security

• Content Addressing: All blobs are content-addressed with SHA256
• Digest Verification: Automatic digest verification during image creation
• Metadata Validation: OCI specification compliance validation

Build Security

• Temporary Files: Secure temporary file handling
• Permission Preservation: Maintains original file permissions
• Isolation: Build process isolated from host system

Future Enhancements

Phase 1: Registry Integration

• Container registry push/pull operations
• Registry authentication (Docker Hub, GitHub Container Registry, etc.)
• Image tagging and versioning
• Multi-arch image support

Phase 2: Advanced Features

• Image signing with Sigstore
• Vulnerability scanning integration
• Image optimization and compression
• Layer caching and reuse

Phase 3: Ecosystem Integration

• Bootc compatibility
• Kubernetes integration
• CI/CD pipeline integration
• Cloud platform deployment

Examples

Example 1: Development Environment

# Create development environment
apt-ostree compose create \
  --base ubuntu:24.04 \
  --packages build-essential git vim curl \
  --output dev-env

# Build container image
apt-ostree compose build-image dev-env my-dev:latest

# Use in development
docker run -it --rm my-dev:latest bash

Example 2: Web Server

# Create web server deployment
apt-ostree compose create \
  --base ubuntu:24.04 \
  --packages nginx apache2 php-fpm \
  --output web-server

# Build production image
apt-ostree compose build-image web-server my-webserver:latest

# Deploy to production
docker run -d -p 80:80 my-webserver:latest

Example 3: Custom Application

# Create application deployment
apt-ostree compose create \
  --base debian:12 \
  --packages python3 python3-pip nodejs npm \
  --output my-app

# Build application image
apt-ostree compose build-image my-app my-application:latest

# Run application
docker run -d -p 3000:3000 my-application:latest

Troubleshooting

Build Issues

# Check OSTree repository
ostree log --repo=/var/lib/apt-ostree/repo my-branch

# Verify commit exists
ostree show --repo=/var/lib/apt-ostree/repo abc123...

# Check available space
df -h /tmp

Image Issues

# Validate OCI image
skopeo inspect oci:my-image.oci

# Check image layers
tar -tf my-image.tar

# Verify image metadata
cat my-image.oci/index.json | jq .

Performance Issues

# Monitor disk usage during build
watch -n 1 'df -h /tmp'

# Check memory usage
free -h

# Profile build process
time apt-ostree compose build-image my-source my-image

Conclusion

The OCI integration in apt-ostree provides a powerful bridge between atomic system deployments and container ecosystems. This enables:

• Testing: Test apt-ostree in real OSTree environments
• Deployment: Deploy atomic systems as containers
• Integration: Bridge between system and container workflows
• Portability: Share atomic deployments as container images

The implementation is production-ready and follows OCI specifications, providing a solid foundation for future enhancements and ecosystem integration.