From d18314c84c223381e5dad1f95bb791723ed8a70b Mon Sep 17 00:00:00 2001 From: robojerk Date: Tue, 15 Jul 2025 11:35:45 -0700 Subject: [PATCH] Documentation: Add comprehensive skopeo command reference based on official man pages --- docs/apt-layer/skopeo.md | 171 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 170 insertions(+), 1 deletion(-) diff --git a/docs/apt-layer/skopeo.md b/docs/apt-layer/skopeo.md index 3babe05..4f96fd2 100644 --- a/docs/apt-layer/skopeo.md +++ b/docs/apt-layer/skopeo.md @@ -24,6 +24,21 @@ skopeo copy docker://ubuntu:24.04 dir:/path/to/local/directory skopeo copy dir:/path/to/local/directory docker://myregistry/myimage:latest ``` +**List available tags:** +```sh +skopeo list-tags docker://ubuntu +``` + +**Login to registry:** +```sh +skopeo login --username username myregistry.com +``` + +**Delete image from registry:** +```sh +skopeo delete docker://myregistry/image:tag +``` + ### Quick Example ```sh # Import OCI image to apt-layer @@ -38,6 +53,53 @@ skopeo inspect docker://ubuntu:24.04 --- +## Skopeo Commands Reference + +Based on the [official skopeo documentation](https://www.mankier.com/1/skopeo), skopeo provides the following commands: + +### Core Commands + +| Command | Purpose | Usage Example | +|---------|---------|---------------| +| `skopeo copy` | Copy images between locations | `skopeo copy docker://src docker://dest` | +| `skopeo inspect` | Inspect image metadata | `skopeo inspect docker://ubuntu:24.04` | +| `skopeo list-tags` | List available tags | `skopeo list-tags docker://ubuntu` | +| `skopeo delete` | Delete image from registry | `skopeo delete docker://registry/image:tag` | + +### Authentication Commands + +| Command | Purpose | Usage Example | +|---------|---------|---------------| +| `skopeo login` | Login to registry | `skopeo login --username user registry.com` | +| `skopeo logout` | Logout from registry | `skopeo logout registry.com` | + +### Signature Commands + +| Command | Purpose | Usage Example | +|---------|---------|---------------| +| `skopeo standalone-sign` | Sign image without daemon | `skopeo standalone-sign --key key.pem image` | +| `skopeo standalone-verify` | Verify image signature | `skopeo standalone-verify --key key.pem image` | +| `skopeo generate-sigstore-key` | Generate Sigstore key | `skopeo generate-sigstore-key --output key.pem` | + +### Utility Commands + +| Command | Purpose | Usage Example | +|---------|---------|---------------| +| `skopeo manifest-digest` | Get manifest digest | `skopeo manifest-digest manifest.json` | +| `skopeo sync` | Sync images between registries | `skopeo sync --src docker --dest dir registry` | + +### Transport Types + +Skopeo supports various transport types: +- `docker://` - Docker registry +- `dir://` - Local directory +- `oci://` - OCI directory +- `containers-storage://` - Podman storage +- `docker-archive://` - Docker tar archive +- `oci-archive://` - OCI tar archive + +--- + ## 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. Both rpm-ostree and apt-layer use **podman as their primary container runtime** and **skopeo specifically for OCI operations**. @@ -162,7 +224,7 @@ skopeo copy dir:/tmp/oci-export-12345 docker://myregistry/gaming:latest 3. `skopeo copy` uploads the OCI directory to the registry 4. The image is available in the container registry -### 4. Image Inspection +### 4. Image Inspection and Validation **Inspect container images:** ```bash @@ -173,11 +235,33 @@ skopeo inspect docker://ubuntu:24.04 apt-layer --oci-info ubuntu:24.04 ``` +**List available tags:** +```bash +# Direct skopeo usage +skopeo list-tags docker://ubuntu + +# apt-layer integration +apt-layer --oci-list-tags ubuntu +``` + +**Validate image before import:** +```bash +# Check if image exists and is accessible +if ! skopeo inspect "docker://$image_name" >/dev/null 2>&1; then + log_error "Invalid OCI image: $image_name" "apt-layer" + return 1 +fi + +# Check available tags +skopeo list-tags "docker://$registry/$image" | grep -q "$tag" +``` + **Returns:** - Image metadata (layers, architecture, OS) - Labels and annotations - Creation date and size information - Digest and signature information +- Available tags for the image ### 5. Registry Authentication @@ -193,6 +277,64 @@ skopeo copy docker://myregistry.com/image:tag dir:/local/path # from ~/.docker/config.json or ~/.config/containers/auth.json ``` +### 6. Image Signing and Verification + +**Generate Sigstore key:** +```bash +# Generate signing key +skopeo generate-sigstore-key --output signing-key.pem +``` + +**Sign image:** +```bash +# Sign image with standalone signing +skopeo standalone-sign --key signing-key.pem docker://myregistry/image:tag +``` + +**Verify image signature:** +```bash +# Verify image signature +skopeo standalone-verify --key signing-key.pem docker://myregistry/image:tag +``` + +**apt-layer integration:** +```bash +# Sign apt-layer image before export +apt-layer --oci-sign my-gaming/24.04 signing-key.pem + +# Verify imported image +apt-layer --oci-verify ubuntu:24.04 signing-key.pem +``` + +### 7. Advanced Operations + +**Get manifest digest:** +```bash +# Get digest for verification +skopeo manifest-digest manifest.json +``` + +**Sync images between registries:** +```bash +# Sync all tags from one registry to another +skopeo sync --src docker --dest docker registry1.com registry2.com +``` + +**Delete images from registry:** +```bash +# Remove image from registry +skopeo delete docker://myregistry/image:tag +``` + +**apt-layer integration:** +```bash +# Sync apt-layer images to backup registry +apt-layer --oci-sync myregistry.com backup-registry.com + +# Clean up old images +apt-layer --oci-cleanup myregistry.com --older-than 30d +``` + --- ## Skopeo vs Container Runtimes @@ -407,6 +549,8 @@ insecure = true # Error: authentication required # Solution: Login to registry (podman and skopeo share auth) podman login myregistry.com +# or use skopeo directly +skopeo login --username username myregistry.com ``` **2. Network Connectivity:** @@ -430,6 +574,21 @@ skopeo list-tags docker://ubuntu skopeo inspect docker://myregistry/private-image ``` +**5. Signature Verification Errors:** +```bash +# Error: signature verification failed +# Solution: Check signing key and policy +skopeo standalone-verify --key key.pem docker://image:tag +``` + +**6. Transport Type Errors:** +```bash +# Error: unsupported transport type +# Solution: Use correct transport prefix +skopeo copy docker://image:tag dir:/local/path +skopeo copy oci://image:tag docker://registry/image:tag +``` + ### Debug Mode ```bash @@ -456,6 +615,16 @@ apt-layer --oci-import ubuntu:24.04 my-base/24.04 - [Skopeo GitHub Repository](https://github.com/containers/skopeo) - [Skopeo Documentation](https://github.com/containers/skopeo/blob/main/README.md) +- [Skopeo Man Page](https://www.mankier.com/1/skopeo) +- [Skopeo Copy Man Page](https://www.mankier.com/1/skopeo-copy) +- [Skopeo Inspect Man Page](https://www.mankier.com/1/skopeo-inspect) +- [Skopeo List-Tags Man Page](https://www.mankier.com/1/skopeo-list-tags) +- [Skopeo Login Man Page](https://www.mankier.com/1/skopeo-login) +- [Skopeo Delete Man Page](https://www.mankier.com/1/skopeo-delete) +- [Skopeo Standalone-Sign Man Page](https://www.mankier.com/1/skopeo-standalone-sign) +- [Skopeo Standalone-Verify Man Page](https://www.mankier.com/1/skopeo-standalone-verify) +- [Skopeo Generate-Sigstore-Key Man Page](https://www.mankier.com/1/skopeo-generate-sigstore-key) +- [Skopeo Sync Man Page](https://www.mankier.com/1/skopeo-sync) - [OCI Specification](https://github.com/opencontainers/image-spec) - [Container Tools Documentation](https://github.com/containers/toolbox) - [rpm-ostree Skopeo Integration](https://github.com/coreos/rpm-ostree)