robojerk/particle-os-tools
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Documentation: Add comprehensive skopeo command reference based on official man pages

Browse source
This commit is contained in:
robojerk 2025-07-15 11:35:45 -07:00
parent 8cb3e71c59
commit d18314c84c
1 changed files with 170 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

171
docs/apt-layer/skopeo.md
View file

@ -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)