robojerk/particle-os-tools
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
particle-os-tools/docs/apt-layer/skopeo.md

11 KiB
Raw Blame History

Skopeo Integration in apt-layer

TLDR - Quick Reference

Basic Commands

Inspect a container image:

skopeo inspect docker://ubuntu:24.04

Copy image between registries:

skopeo copy docker://ubuntu:24.04 docker://myregistry/ubuntu:24.04

Copy image to local directory:

skopeo copy docker://ubuntu:24.04 dir:/path/to/local/directory

Copy local directory to registry:

skopeo copy dir:/path/to/local/directory docker://myregistry/myimage:latest

Quick Example

# Import OCI image to apt-layer
apt-layer --oci-import ubuntu:24.04 my-base/24.04

# Export apt-layer image to OCI
apt-layer --oci-export my-gaming/24.04 myregistry/gaming:latest

# Inspect image before import
skopeo inspect docker://ubuntu:24.04

Overview

apt-layer uses skopeo for OCI (Open Container Initiative) container image operations, mirroring the approach used by rpm-ostree. Both rpm-ostree and apt-layer use podman as their primary container runtime and skopeo specifically for OCI operations.

Key Role: Skopeo serves as the specialized OCI tool in apt-layer for:

  • Container image inspection and validation
  • Image copying between registries and local storage
  • Image format conversion (OCI ↔ ComposeFS)
  • Registry authentication and signature verification

Container Runtime: Podman serves as the primary container runtime for:

  • Running containers for package installation
  • Building and managing container images
  • Container lifecycle management
  • Interactive development and testing

Package Structure

Debian/Ubuntu Package

Package Name: skopeo
Purpose: OCI container image operations
Contains:

  • /usr/bin/skopeo - Main skopeo executable
  • /usr/share/man/man1/skopeo.1.gz - Manual page
  • /usr/share/doc/skopeo/ - Documentation

Dependencies:

  • libgpgme11 - GPG Made Easy library
  • libostree-1-1 - OSTree library
  • containers-common - Container utilities

Installation

Debian/Ubuntu:

sudo apt install -y skopeo

Fedora/RHEL:

sudo dnf install -y skopeo

Skopeo Usage in apt-layer

1. Tool Usage Strategy

apt-layer and rpm-ostree use a specialized approach for different types of operations:

OCI Operations (skopeo):

  • Image inspection and validation
  • Image copying between registries
  • Image format conversion
  • Signature verification
  • Registry operations without running containers

Container Runtime Operations (podman):

  • Running containers for package installation
  • Building and managing container images
  • Container lifecycle management
  • Interactive development and testing
# apt-layer automatically detects and uses the appropriate tool
if command -v skopeo &> /dev/null; then
    OCI_TOOL="skopeo"
    log_info "Using skopeo for OCI operations" "apt-layer"
elif command -v podman &> /dev/null; then
    OCI_TOOL="podman"
    log_info "Using podman for OCI operations (fallback)" "apt-layer"
else
    OCI_TOOL="docker"
    log_info "Using docker for OCI operations (fallback)" "apt-layer"
fi

# Container runtime is always podman when available
if command -v podman &> /dev/null; then
    CONTAINER_RUNTIME="podman"
    log_info "Using podman as container runtime" "apt-layer"
else
    CONTAINER_RUNTIME="docker"
    log_info "Using docker as container runtime" "apt-layer"
fi

2. Image Import Operations

Import OCI image as ComposeFS:

# apt-layer command
apt-layer --oci-import ubuntu:24.04 my-base/24.04

# Underlying skopeo operation
skopeo copy docker://ubuntu:24.04 dir:/tmp/oci-import-12345

Process:

  1. skopeo copy downloads the OCI image to a local directory
  2. apt-layer extracts the filesystem from the OCI structure
  3. apt-layer creates a ComposeFS image from the extracted filesystem
  4. The ComposeFS image is stored in apt-layer's image workspace

3. Image Export Operations

Export ComposeFS image to OCI:

# apt-layer command
apt-layer --oci-export my-gaming/24.04 myregistry/gaming:latest

# Underlying skopeo operation
skopeo copy dir:/tmp/oci-export-12345 docker://myregistry/gaming:latest

Process:

  1. apt-layer mounts the ComposeFS image
  2. apt-layer creates an OCI directory structure from the mounted filesystem
  3. skopeo copy uploads the OCI directory to the registry
  4. The image is available in the container registry

4. Image Inspection

Inspect container images:

# Direct skopeo usage
skopeo inspect docker://ubuntu:24.04

# apt-layer integration
apt-layer --oci-info ubuntu:24.04

Returns:

  • Image metadata (layers, architecture, OS)
  • Labels and annotations
  • Creation date and size information
  • Digest and signature information

5. Registry Authentication

Authentication with registries:

# Login to registry (handled by podman)
podman login myregistry.com

# skopeo uses the same authentication
skopeo copy docker://myregistry.com/image:tag dir:/local/path

# Both podman and skopeo share authentication configuration
# from ~/.docker/config.json or ~/.config/containers/auth.json

Skopeo vs Container Runtimes

Skopeo (OCI Operations Only)

Use Cases:

  • Image inspection and validation
  • Image copying between registries
  • Image format conversion
  • Signature verification
  • Registry operations without running containers

Limitations:

  • Cannot run containers
  • Cannot build images
  • Limited to OCI operations

Podman (Primary Container Runtime)

Use Cases:

  • Running containers for package installation
  • Building and managing container images
  • Container lifecycle management
  • Interactive development and testing
  • OCI operations (when skopeo unavailable)

Integration:

  • apt-layer uses podman as the primary container runtime (like rpm-ostree)
  • skopeo handles specialized OCI operations
  • Both work together in the apt-layer ecosystem

Docker (Fallback Container Runtime)

Use Cases:

  • Running containers when podman unavailable
  • Building images when podman unavailable
  • Container operations in environments without podman

Note: apt-layer and rpm-ostree prefer podman over docker for container operations

OCI Integration Workflow

1. Import Workflow

# Step 1: Inspect the image
skopeo inspect docker://ubuntu:24.04

# Step 2: Copy image to local directory
skopeo copy docker://ubuntu:24.04 dir:/tmp/oci-import

# Step 3: Extract filesystem
# apt-layer extracts the root filesystem from the OCI structure

# Step 4: Create ComposeFS image
mkcomposefs /tmp/extracted-rootfs my-base/24.04 --digest-store=/path/to/objects

# Step 5: Cleanup
rm -rf /tmp/oci-import

2. Export Workflow

# Step 1: Mount ComposeFS image
mount -t composefs -o basedir=/path/to/objects my-gaming/24.04 /mnt/composefs

# Step 2: Create OCI directory structure
# apt-layer creates manifest.json, config.json, and layer files

# Step 3: Copy to registry
skopeo copy dir:/tmp/oci-export docker://myregistry/gaming:latest

# Step 4: Unmount and cleanup
umount /mnt/composefs
rm -rf /tmp/oci-export

Integration with apt-layer Features

1. OSTree Atomic Operations

# Import OCI image and create OSTree commit
apt-layer ostree compose install --from-oci ubuntu:24.04

# Export OSTree deployment as OCI image
apt-layer ostree compose export my-deployment myregistry/deployment:latest

2. Container-based Package Installation

# Use OCI image as base for package installation (uses podman)
apt-layer --container ubuntu:24.04 my-dev/24.04 vscode git

# Export result back to OCI (uses skopeo)
apt-layer --oci-export my-dev/24.04 myregistry/dev:latest

3. Live System Integration

# Import OCI image for live system base
apt-layer --live-import ubuntu:24.04

# Export live system changes as OCI image
apt-layer --live-export myregistry/live-changes:latest

Error Handling and Validation

1. Image Validation

# Validate image before import
if ! skopeo inspect "docker://$image_name" >/dev/null 2>&1; then
    log_error "Invalid OCI image: $image_name" "apt-layer"
    return 1
fi

2. Registry Connectivity

# Test registry connectivity
if ! skopeo inspect "docker://$registry/$image" >/dev/null 2>&1; then
    log_error "Cannot access registry: $registry" "apt-layer"
    return 1
fi

3. Authentication Errors

# Handle authentication failures
if ! skopeo copy "docker://$source" "docker://$destination"; then
    log_error "Authentication failed or insufficient permissions" "apt-layer"
    log_info "Try: podman login $registry" "apt-layer"
    log_info "Note: podman and skopeo share authentication configuration" "apt-layer"
    return 1
fi

Configuration

1. Registry Configuration

File: /etc/containers/registries.conf
Purpose: Configure registry mirrors, authentication, and security

[[registry]]
prefix = "docker.io"
location = "docker.io"
insecure = false
blocked = false

[[registry]]
prefix = "myregistry.com"
location = "myregistry.com"
insecure = true

2. Authentication

File: ~/.docker/config.json (shared with podman/docker)
Purpose: Store registry credentials

{
  "auths": {
    "myregistry.com": {
      "auth": "base64-encoded-credentials"
    }
  }
}

3. Policy Configuration

File: /etc/containers/policy.json
Purpose: Define signature verification policies

{
  "default": [
    {
      "type": "insecureAcceptAnything"
    }
  ]
}

Troubleshooting

Common Issues

1. Authentication Errors:

# Error: authentication required
# Solution: Login to registry (podman and skopeo share auth)
podman login myregistry.com

2. Network Connectivity:

# Error: connection refused
# Solution: Check network and firewall
curl -I https://registry-1.docker.io/v2/

3. Image Not Found:

# Error: manifest unknown
# Solution: Verify image name and tag
skopeo list-tags docker://ubuntu

4. Insufficient Permissions:

# Error: permission denied
# Solution: Check registry permissions
skopeo inspect docker://myregistry/private-image

Debug Mode

# Enable debug output
export SKOPEO_DEBUG=1
apt-layer --oci-import ubuntu:24.04 my-base/24.04

Integration Notes

  • Podman-First Approach: apt-layer uses podman as the primary container runtime (like rpm-ostree)
  • Skopeo for OCI: skopeo handles specialized OCI operations (inspection, copying, conversion)
  • ComposeFS Integration: Seamless conversion between OCI and ComposeFS formats
  • Registry Support: Full support for Docker Hub, private registries, and local storage
  • Signature Verification: Built-in support for image signatures and verification
  • Authentication: Shared authentication between podman and skopeo for consistent experience
  • Error Handling: Comprehensive error handling with helpful diagnostic messages

References