diff --git a/docs/apt-layer/skopeo.md b/docs/apt-layer/skopeo.md index 78b6ea5..3babe05 100644 --- a/docs/apt-layer/skopeo.md +++ b/docs/apt-layer/skopeo.md @@ -40,14 +40,20 @@ skopeo inspect docker://ubuntu:24.04 ## Overview -apt-layer uses [skopeo](https://github.com/containers/skopeo) for OCI (Open Container Initiative) container image operations, mirroring the approach used by rpm-ostree. Skopeo is a command line utility that performs various operations on container images and image repositories without requiring the user to run a container daemon. +apt-layer uses [skopeo](https://github.com/containers/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 primary OCI tool in apt-layer for: +**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 @@ -82,25 +88,43 @@ sudo dnf install -y skopeo ## Skopeo Usage in apt-layer -### 1. OCI Tool Priority +### 1. Tool Usage Strategy -apt-layer uses a priority-based approach for OCI operations: +apt-layer and rpm-ostree use a specialized approach for different types of operations: -1. **skopeo** (preferred) - For OCI operations only -2. **podman** (fallback) - For container runtime operations -3. **docker** (alternative) - For container runtime 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 ```bash -# apt-layer automatically detects and uses skopeo when available +# 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" "apt-layer" + log_info "Using podman for OCI operations (fallback)" "apt-layer" else OCI_TOOL="docker" - log_info "Using docker for OCI operations" "apt-layer" + 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 ``` @@ -159,11 +183,14 @@ apt-layer --oci-info ubuntu:24.04 **Authentication with registries:** ```bash -# Login to registry (handled by podman/docker) +# 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 ``` --- @@ -184,19 +211,29 @@ skopeo copy docker://myregistry.com/image:tag dir:/local/path - Cannot build images - Limited to OCI operations -### Container Runtimes (podman/docker) +### Podman (Primary Container Runtime) **Use Cases:** -- Running containers -- Building images +- Running containers for package installation +- Building and managing container images - Container lifecycle management -- Interactive development +- Interactive development and testing +- OCI operations (when skopeo unavailable) **Integration:** -- apt-layer uses container runtimes for package installation -- skopeo handles OCI operations +- 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 @@ -254,10 +291,10 @@ apt-layer ostree compose export my-deployment myregistry/deployment:latest ### 2. Container-based Package Installation ```bash -# Use OCI image as base for 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 +# Export result back to OCI (uses skopeo) apt-layer --oci-export my-dev/24.04 myregistry/dev:latest ``` @@ -302,6 +339,7 @@ fi 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 ``` @@ -367,7 +405,7 @@ insecure = true **1. Authentication Errors:** ```bash # Error: authentication required -# Solution: Login to registry +# Solution: Login to registry (podman and skopeo share auth) podman login myregistry.com ``` @@ -404,11 +442,12 @@ apt-layer --oci-import ubuntu:24.04 my-base/24.04 ## Integration Notes -- **OCI-First Approach:** apt-layer prioritizes skopeo for OCI operations, using container runtimes only when necessary +- **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 with podman/docker for consistent experience +- **Authentication:** Shared authentication between podman and skopeo for consistent experience - **Error Handling:** Comprehensive error handling with helpful diagnostic messages ---