commit 791b1a4c6988a4ccbb8000a112a09afd05cd69b3 Author: Zhongwei Li Date: Sun Nov 30 08:45:46 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..a3cbc57 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,11 @@ +{ + "name": "container-image", + "description": "Container image inspection and analysis using skopeo and podman", + "version": "0.0.1", + "author": { + "name": "github.com/openshift-eng" + }, + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..c8e9f62 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# container-image + +Container image inspection and analysis using skopeo and podman diff --git a/commands/compare.md b/commands/compare.md new file mode 100644 index 0000000..0cf29d8 --- /dev/null +++ b/commands/compare.md @@ -0,0 +1,289 @@ +--- +description: Compare two container images to identify differences +argument-hint: +--- + +## Name +container-image:compare + +## Synopsis +``` +/container-image:compare +``` + +## Description + +The `container-image:compare` command compares two container images and identifies their differences. This is useful for understanding what changed between image versions, comparing images from different registries, or verifying image rebuilds. + +The command analyzes and compares: +- Image metadata (digests, creation dates) +- Layer differences (added, removed, modified) +- Size differences +- Configuration changes (environment variables, labels, entrypoints) +- Platform/architecture support +- Security and vulnerability differences (if scanning tools available) + +This command is useful for: +- Understanding changes between image versions +- Verifying image rebuilds match expectations +- Comparing images across registries (e.g., production vs staging) +- Identifying what layers changed in an update +- Troubleshooting deployment issues +- Security auditing and change tracking + +## Prerequisites + +**Required Tools:** + +1. **skopeo** - For image inspection and comparison + - Check if installed: `which skopeo` + - Installation: + - RHEL/Fedora: `sudo dnf install skopeo` + - Ubuntu/Debian: `sudo apt-get install skopeo` + - macOS: `brew install skopeo` + - Documentation: https://github.com/containers/skopeo + +**Optional Tools:** + +2. **podman** - For additional image analysis + - Useful for layer-by-layer comparison + - Installation: See `/container-image:inspect` prerequisites + +3. **dive** - For detailed layer analysis + - Check if installed: `which dive` + - Installation: https://github.com/wagoodman/dive + - Provides interactive layer comparison + +**Registry Authentication:** + +For private registries: +```bash +skopeo login registry.example.com +``` + +## Implementation + +The command performs the following comparison: + +1. **Check Tool Availability**: + - Verify `skopeo` is installed + - Check for optional tools (`podman`, `dive`) + +2. **Inspect Both Images**: + ```bash + skopeo inspect docker:// + skopeo inspect docker:// + ``` + +3. **Compare Basic Metadata**: + - Digests (are they the same image?) + - Creation timestamps + - Architecture and OS + - Manifest type (single vs manifest list) + +4. **Analyze Layer Differences**: + - Extract layer digests from both images + - Identify: + - **Common layers**: Layers shared between images + - **Added layers**: New layers in image2 + - **Removed layers**: Layers from image1 not in image2 + - **Modified layers**: Layers with same position but different content + - Calculate size differences + +5. **Compare Configuration**: + - Environment variables (added, removed, changed) + - Labels and annotations + - Exposed ports + - Entrypoint and command + - Working directory + - User/UID + - Volume mount points + +6. **Calculate Size Impact**: + - Total size difference + - Size added by new layers + - Size saved by removed layers + +7. **Present Structured Comparison**: + - Summary of differences + - Detailed breakdown by category + - Highlight significant changes + - Provide recommendations + +## Return Value + +The command outputs a structured comparison report: + +``` +================================================================================ +CONTAINER IMAGE COMPARISON +================================================================================ +Image 1: quay.io/openshift-release-dev/ocp-release:4.16.0 +Image 2: quay.io/openshift-release-dev/ocp-release:4.17.0 + +COMPARISON SUMMARY: + Images are: DIFFERENT + Digest match: NO + Architecture: Both linux/amd64 + +METADATA COMPARISON: + Attribute Image 1 Image 2 Change + ──────────────────────────────────────────────────────────────────────────────────────── + Digest sha256:abc123... sha256:def456... CHANGED + Created 2023-11-15T10:30:45Z 2024-01-15T10:30:45Z +61 days + Size 1.15 GB 1.22 GB +70 MB + +LAYER ANALYSIS: + Total Layers (Image 1): 15 + Total Layers (Image 2): 17 + + Common Layers: 12 layers (850 MB) + Added Layers: 5 layers (220 MB) + Removed Layers: 3 layers (150 MB) + + Layer Breakdown: + ✓ Layer 1-8: IDENTICAL (base layers) + + Layer 9: ADDED in Image 2 (45 MB) - New component added + - Layer 10: REMOVED from Image 1 (30 MB) - Old dependency removed + ✓ Layer 11-15: IDENTICAL + + Layer 16-17: ADDED in Image 2 (25 MB) - Updates + +CONFIGURATION DIFFERENCES: + + Environment Variables: + + OPENSHIFT_VERSION=4.17.0 (was: 4.16.0) + + NEW_FEATURE_FLAG=enabled (added) + - DEPRECATED_FLAG=true (removed) + + Labels: + + io.openshift.release=4.17.0 (was: 4.16.0) + + io.openshift.build-date=2024-01-15 (was: 2023-11-15) + + Exposed Ports: + ✓ 8080/tcp (unchanged) + ✓ 8443/tcp (unchanged) + + Entrypoint: + ✓ ["/usr/bin/entrypoint.sh"] (unchanged) + + Command: + - ["--legacy-mode"] (removed) + + ["--v2-mode"] (added) + +SIGNIFICANT CHANGES: + • Version upgrade: 4.16.0 → 4.17.0 + • Size increase: +70 MB (+6%) + • 5 new layers added + • 3 old layers removed + • Command-line arguments changed + • New feature flag enabled + +RECOMMENDATIONS: + • Review changelog for 4.16.0 → 4.17.0 upgrade + • Test with new command-line arguments (--v2-mode) + • Verify NEW_FEATURE_FLAG behavior in your environment + • Consider size impact (+70 MB) in constrained environments +================================================================================ +``` + +**For Identical Images:** +``` +================================================================================ +CONTAINER IMAGE COMPARISON +================================================================================ +Image 1: quay.io/myapp:v1.0.0 +Image 2: registry.example.com/myapp:v1.0.0 + +COMPARISON SUMMARY: + Images are: IDENTICAL + Digest match: YES (sha256:abc123...) + +These images are the same, just referenced from different registries. +No differences found. +================================================================================ +``` + +## Examples + +1. **Compare two versions of the same image**: + ``` + /container-image:compare quay.io/openshift-release-dev/ocp-release:4.16.0 quay.io/openshift-release-dev/ocp-release:4.17.0 + ``` + Shows what changed between OpenShift 4.16 and 4.17. + +2. **Compare production vs staging**: + ``` + /container-image:compare registry.prod.example.com/myapp:latest registry.staging.example.com/myapp:latest + ``` + Verifies staging matches production. + +3. **Compare images across registries**: + ``` + /container-image:compare docker.io/library/nginx:1.25 quay.io/nginx/nginx:1.25 + ``` + Checks if images from different registries are identical. + +4. **Verify image rebuild**: + ``` + /container-image:compare myapp:v1.0.0-original myapp:v1.0.0-rebuilt + ``` + Confirms rebuild produced the same image. + +5. **Compare by digest**: + ``` + /container-image:compare quay.io/myapp@sha256:abc123... quay.io/myapp@sha256:def456... + ``` + Compares specific image versions by digest. + +## Error Handling + +- **Image not found**: Verify both image references are correct +- **Authentication required**: Ensure you're logged into both registries +- **Network errors**: Check connectivity to both registries +- **Tool not available**: Provide installation instructions for `skopeo` +- **Different architectures**: Note when comparing images for different platforms + +## Notes + +- **Digest Comparison**: If digests match, images are identical +- **Layer Sharing**: Base layers are often shared between versions +- **Size Calculation**: Sizes shown are compressed (as stored in registry) +- **Semantic Versioning**: Helps identify major vs minor changes +- **Build Reproducibility**: Identical source should produce identical digests +- **Registry Metadata**: Some metadata may differ even if image content is identical + +## Advanced Usage + +**Compare Specific Architectures:** + +For manifest lists, you can compare specific platform variants: +```bash +# Compare amd64 variants +/container-image:compare quay.io/myapp:v1@sha256: quay.io/myapp:v2@sha256: +``` + +**Layer-by-Layer Analysis:** + +If `dive` is installed, the command can provide interactive layer comparison: +```bash +dive --compare +``` + +## Use Cases + +1. **Version Upgrades**: Understand what changed before upgrading +2. **Security Auditing**: Track changes to identify security implications +3. **Deployment Verification**: Confirm correct image is deployed +4. **Registry Migration**: Verify images copied between registries +5. **Build Debugging**: Identify why builds differ +6. **Compliance**: Document and track image changes + +## Arguments + +- **$1** (image1): Required. First image reference. + - Format: `[registry/]repository[:tag|@digest]` + +- **$2** (image2): Required. Second image reference. + - Format: `[registry/]repository[:tag|@digest]` + +**Note**: Images can be from the same or different registries. diff --git a/commands/inspect.md b/commands/inspect.md new file mode 100644 index 0000000..b8ef92c --- /dev/null +++ b/commands/inspect.md @@ -0,0 +1,315 @@ +--- +description: Inspect and provide detailed breakdown of a container image +argument-hint: +--- + +## Name +container-image:inspect + +## Synopsis +``` +/container-image:inspect +``` + +## Description + +The `container-image:inspect` command provides a comprehensive breakdown of a container image using `skopeo` and `podman`. It analyzes the image metadata, configuration, and layers to give you detailed information about the image structure, size, architecture, and contents. + +This command is useful for: +- Understanding image composition and layers +- Verifying image architecture and OS +- Checking image size and disk usage +- Inspecting image labels and annotations +- Validating image configuration +- Troubleshooting image-related issues +- Verifying multi-architecture image support +- Checking which platforms are available for an image +- Comparing platform-specific image differences +- Planning multi-arch image builds + +The command works with images from any registry (quay.io, docker.io, registry.redhat.io, etc.) and automatically detects whether an image is a manifest list (multi-architecture) or a single image, providing detailed analysis for both cases. + +## Prerequisites + +**Required Tools:** + +1. **skopeo** - For image inspection without pulling + - Check if installed: `which skopeo` + - Installation: + - RHEL/Fedora: `sudo dnf install skopeo` + - Ubuntu/Debian: `sudo apt-get install skopeo` + - macOS: `brew install skopeo` + - Documentation: https://github.com/containers/skopeo + +2. **podman** (Optional) - For additional image analysis + - Check if installed: `which podman` + - Installation: + - RHEL/Fedora: `sudo dnf install podman` + - Ubuntu/Debian: `sudo apt-get install podman` + - macOS: `brew install podman` + - Documentation: https://podman.io/ + +**Registry Authentication:** + +For private registries, ensure you're authenticated: +```bash +# Using skopeo +skopeo login registry.example.com + +# Using podman +podman login registry.example.com +``` + +## Implementation + +The command performs the following analysis steps: + +1. **Check Tool Availability**: + - Verify `skopeo` is installed + - Check for `podman` (optional but recommended) + - If tools are missing, provide installation instructions + +2. **Inspect Image Metadata with skopeo**: + ```bash + skopeo inspect docker:// + ``` + + This provides: + - Image digest and tags + - Architecture and OS + - Layer information + - Creation timestamp + - Labels and annotations + - Environment variables + - Exposed ports + - Entrypoint and command + +3. **Determine Image Type**: + - Check if the image is a **manifest list** (multi-arch) or a **single image** + - Fetch raw manifest to determine type: + ```bash + skopeo inspect --raw docker:// + ``` + - Parse `schemaVersion` and `mediaType` to identify: + - **Manifest List** (OCI Index): `application/vnd.oci.image.index.v1+json` + - **Manifest List** (Docker): `application/vnd.docker.distribution.manifest.list.v2+json` + - **Single Image** (OCI): `application/vnd.oci.image.manifest.v1+json` + - **Single Image** (Docker): `application/vnd.docker.distribution.manifest.v2+json` + +4. **Extract Manifest List Details** (if applicable): + - For manifest lists, extract platform information for each variant: + - Architecture (amd64, arm64, ppc64le, s390x, etc.) + - OS (linux, windows) + - Variant (v7, v8 for ARM) + - Digest of platform-specific image + - Size of platform-specific image + - Optionally inspect each platform variant: + ```bash + skopeo inspect docker://@ + ``` + - Compare platform differences: + - Image sizes across platforms + - Layer counts + - Creation timestamps + - Configuration differences + +5. **Analyze Image Layers**: + - List all layers with their sizes + - Calculate total image size + - Identify the largest layers + - Show layer history (if available) + +6. **Extract Configuration Details**: + - Operating system and distribution + - Architecture (amd64, arm64, ppc64le, s390x, etc.) + - Environment variables + - Working directory + - User/UID + - Exposed ports + - Volume mount points + - Labels (including OpenShift/Kubernetes metadata) + +7. **Infer Image Purpose**: + - Analyze image metadata to determine the likely purpose: + - Image name and repository patterns (e.g., "nginx", "postgres", "ocp-release") + - Labels (especially `io.openshift.*`, `io.k8s.*`, `org.opencontainers.*`) + - Entrypoint and command (what executable is being run) + - Exposed ports (common service ports) + - Environment variables (framework indicators, version info) + - Provide context about: + - What the image is (e.g., "web server", "database", "operator", "release payload") + - Common use cases + - Notable characteristics based on configuration + +8. **Present Organized Summary**: + - Image identity (digest, tags) + - Inferred purpose and context + - Basic information (OS, architecture, created date) + - Size breakdown + - Configuration summary + - Manifest list details (if applicable) + - Notable labels and annotations + +## Return Value + +The command outputs a structured breakdown of the image: + +``` +================================================================================ +CONTAINER IMAGE INSPECTION +================================================================================ +Image: quay.io/openshift-release-dev/ocp-release:4.20.0-multi + +IMAGE PURPOSE: + This is an OpenShift release image containing the cluster-version-operator + for OpenShift 4.20.0. It's part of the OpenShift release payload used to + manage cluster upgrades and version management. + +BASIC INFORMATION: + Manifest Digest: sha256:4f1e772349a20f2eb69e8cf70d73b4fcc299c15cb6e4f027696eb469e66d4080 + Type: Manifest List (Multi-Architecture) + Manifest Type: Docker Distribution Manifest List v2 + Created: 2025-10-16T13:35:26Z + +MANIFEST LIST DETAILS: + This is a multi-architecture manifest list containing 4 platform variants. + + AVAILABLE PLATFORMS (4): + -------------------------------------------------------------------------------- + 1. linux/amd64 + Digest: sha256:b4bd68afe0fb47bf9876f51e33d88e9dd218fed2dcf41b025740591746dda5c9 + Size: 167.6 MB (175,762,648 bytes) + Layers: 6 + Created: 2025-10-16T13:35:26Z + + 2. linux/arm64 + Digest: sha256:eec6b0e6ff1c4cf5edc158c41a171ac8b02d7e0389715b663528a4ec0931b1f2 + Size: 161.6 MB (169,501,175 bytes) + Layers: 6 + Created: 2025-10-16T13:35:26Z + + 3. linux/ppc64le + Digest: sha256:4bb9eb125d4d35c100699617ec8278691a9cee771ebacb113173b75f0707df56 + Size: 174.4 MB (182,863,818 bytes) + Layers: 6 + Created: 2025-10-16T13:35:26Z + + 4. linux/s390x + Digest: sha256:5e852c796f2d3b83b3bd4506973a455a521b6933e3944740b32c1ed483b2174e + Size: 163.2 MB (171,055,271 bytes) + Layers: 6 + Created: 2025-10-16T13:35:26Z + + PLATFORM COMPARISON: + Size Range: 161.6 MB - 174.4 MB (arm64 smallest, ppc64le largest) + Size Variance: ~12.8 MB difference between smallest and largest + Architectures: 4 platforms (amd64, arm64, ppc64le, s390x) + OS: linux (all) + Layer Count: 6 (all platforms) + Build Time: All platforms built simultaneously + + USAGE: + To pull a specific platform: + podman pull --platform=linux/amd64 quay.io/openshift-release-dev/ocp-release:4.20.0-multi + podman pull quay.io/openshift-release-dev/ocp-release@sha256:b4bd68afe0fb... # amd64 + +CONFIGURATION (amd64 example): + User: + WorkingDir: + Entrypoint: ["/usr/bin/cluster-version-operator"] + Cmd: + Env: + - PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin + - BUILD_VERSION=v4.20.0 + - OS_GIT_VERSION=4.20.0-202509230726.p2.g9de00ba.assembly.stream.el9-9de00ba + +EXPOSED PORTS: + + +LABELS: + io.openshift.release: 4.20.0 + io.openshift.release.base-image-digest: sha256:6f58f521f51ae43617d2dead1efbe9690b605d646565892bb0f8c6030a742ba7 + +VOLUMES: + + +LAYER DETAILS (amd64): + Total Layers: 6 + Total Size: 167.6 MB (compressed) +================================================================================ +``` + +## Examples + +1. **Inspect a public image**: + ``` + /container-image:inspect quay.io/openshift-release-dev/ocp-release:4.17.0-x86_64 + ``` + Provides full breakdown of the OpenShift release image. + +2. **Inspect a manifest list**: + ``` + /container-image:inspect registry.redhat.io/ubi9/ubi:latest + ``` + Shows available architectures and platform-specific details. + +3. **Inspect with specific tag**: + ``` + /container-image:inspect docker.io/library/nginx:1.25 + ``` + Analyzes the nginx image with tag 1.25. + +4. **Inspect by digest**: + ``` + /container-image:inspect quay.io/prometheus/prometheus@sha256:abc123... + ``` + Inspects a specific image version by its digest. + +5. **Inspect a private registry image**: + ``` + /container-image:inspect registry.example.com/myorg/myapp:v1.0.0 + ``` + Analyzes an image from a private registry (requires authentication). + +## Error Handling + +- **Image not found**: If the image doesn't exist or the name is incorrect: + - Verify the image name and tag + - Check registry accessibility + - Ensure authentication is set up for private registries + +- **Tool not available**: If `skopeo` is not installed: + - Display installation instructions for the user's platform + - Suggest using `podman inspect` as an alternative (if podman is available) + +- **Authentication errors**: If registry requires authentication: + - Prompt user to run `skopeo login ` or `podman login ` + - Provide documentation link for registry authentication + +- **Network errors**: If registry is unreachable: + - Check internet connectivity + - Verify registry URL is correct + - Check for proxy/firewall issues + +## Notes + +- **No Image Pull Required**: `skopeo inspect` fetches metadata without downloading the entire image +- **Manifest Lists**: For multi-arch images, the command automatically detects and shows detailed platform information including per-platform digests, sizes, and configurations +- **Manifest List vs Single Image**: The command clearly distinguishes between manifest lists and single-architecture images +- **Platform Selection**: Container runtimes automatically select the correct platform from a manifest list +- **Digest Pinning**: Always displays the image digest for reproducible deployments +- **Label Standards**: Highlights important labels like OpenShift/Kubernetes metadata +- **Size Accuracy**: Layer sizes are compressed sizes as stored in the registry +- **Size Variations**: Platform-specific images may have different sizes due to architecture differences +- **OCI vs Docker**: Supports both OCI and Docker manifest formats +- **Variant Field**: ARM images may have variants (v7, v8) for different ARM versions +- **Registry Support**: Works with any OCI-compliant registry + +## Arguments + +- **$1** (image): Required. The full image reference including registry, repository, and tag/digest. + - Format: `[registry/]repository[:tag|@digest]` + - Examples: + - `quay.io/openshift/origin-node:latest` + - `docker.io/library/alpine:3.18` + - `registry.redhat.io/ubi9/ubi@sha256:abc123...` diff --git a/commands/tags.md b/commands/tags.md new file mode 100644 index 0000000..02fbd93 --- /dev/null +++ b/commands/tags.md @@ -0,0 +1,310 @@ +--- +description: List and analyze available tags for a container image repository +argument-hint: +--- + +## Name +container-image:tags + +## Synopsis +``` +/container-image:tags +``` + +## Description + +The `container-image:tags` command lists and analyzes all available tags for a container image repository. It provides detailed information about each tag including creation date, size, architecture support, and digest. + +This command helps you: +- Discover available image versions +- Identify the latest stable releases +- Find images for specific architectures +- Track image update frequency +- Identify deprecated or outdated tags +- Plan image upgrades +- Understand tagging conventions + +The command works with any OCI-compliant registry and can filter, sort, and analyze tags based on various criteria. + +## Prerequisites + +**Required Tools:** + +1. **skopeo** - For listing and inspecting tags + - Check if installed: `which skopeo` + - Installation: + - RHEL/Fedora: `sudo dnf install skopeo` + - Ubuntu/Debian: `sudo apt-get install skopeo` + - macOS: `brew install skopeo` + - Documentation: https://github.com/containers/skopeo + +**Registry Authentication:** + +For private registries: +```bash +skopeo login registry.example.com +``` + +## Implementation + +The command performs the following analysis: + +1. **Check Tool Availability**: + - Verify `skopeo` is installed + - If missing, provide installation instructions + +2. **List All Tags**: + ```bash + skopeo list-tags docker:// + ``` + + This returns all available tags for the repository. + +3. **Inspect Each Tag** (for detailed analysis): + For each tag (or a sample of tags for large repositories): + ```bash + skopeo inspect docker://: + ``` + + Extract: + - Image digest + - Creation date + - Size + - Architecture(s) + - Labels + - Manifest type + +4. **Categorize Tags**: + - **Version tags**: Semantic versions (v1.0.0, 2.1.3) + - **Latest tags**: Tags like `latest`, `stable`, `production` + - **Date-based tags**: Tags with dates (20240115, 2024-01-15) + - **Branch tags**: Development branches (main, develop) + - **SHA tags**: Git commit SHAs + - **Custom tags**: Other tagging schemes + +5. **Sort and Filter**: + - Sort by creation date (newest first) + - Sort by semantic version + - Filter by pattern (e.g., only `v4.*` tags) + - Filter by architecture support + - Show only recent tags (e.g., last 30 days) + +6. **Identify Key Tags**: + - Current `latest` tag + - Most recent version tag + - Long-term support (LTS) tags + - Deprecated tags + - Duplicate tags (same digest, different names) + +7. **Present Organized Analysis**: + - Summary of tag categories + - Detailed tag list with metadata + - Recommendations for tag selection + - Notable patterns or issues + +## Return Value + +The command outputs a structured tag listing: + +``` +================================================================================ +CONTAINER IMAGE TAGS +================================================================================ +Repository: quay.io/openshift-release-dev/ocp-release + +Total Tags: 487 + +TAG SUMMARY: + Version Tags: 312 (e.g., 4.17.0, 4.16.1) + Date Tags: 150 (e.g., 2024-01-15) + Latest Tags: 3 (latest, stable, production) + Other Tags: 22 + +RECENT TAGS (Last 30 days): +-------------------------------------------------------------------------------- +TAG CREATED SIZE ARCH DIGEST +4.17.0 2024-01-15 10:30 1.2 GB multi sha256:abc123... +4.17.0-rc.1 2024-01-10 08:15 1.2 GB multi sha256:def456... +4.16.2 2024-01-08 14:22 1.1 GB multi sha256:ghi789... +latest 2024-01-15 10:30 1.2 GB multi sha256:abc123... +stable 2024-01-08 14:22 1.1 GB multi sha256:ghi789... + +VERSION TAGS (Semantic): +-------------------------------------------------------------------------------- +4.17.0 2024-01-15 1.2 GB multi sha256:abc123... [LATEST] +4.17.0-rc.1 2024-01-10 1.2 GB multi sha256:def456... +4.16.2 2024-01-08 1.1 GB multi sha256:ghi789... +4.16.1 2023-12-20 1.1 GB multi sha256:jkl012... +4.16.0 2023-12-01 1.1 GB multi sha256:mno345... +4.15.18 2023-11-28 1.0 GB multi sha256:pqr678... +... + +SPECIAL TAGS: +-------------------------------------------------------------------------------- +latest → 4.17.0 (sha256:abc123...) +stable → 4.16.2 (sha256:ghi789...) +lts → 4.15.18 (sha256:pqr678...) + +ARCHITECTURE SUPPORT: + Multi-arch tags: 465 (linux/amd64, linux/arm64, linux/ppc64le, linux/s390x) + Single-arch: 22 (linux/amd64 only) + +DUPLICATE TAGS (same image, multiple tags): + 4.17.0 = latest = 2024-01-15 (sha256:abc123...) + 4.16.2 = stable (sha256:ghi789...) + +TAG PATTERNS: + • Semantic versioning (4.x.y) + • Release candidates (-rc.x) + • Date-based snapshots (YYYY-MM-DD) + • Architecture-specific suffixes (-amd64, -arm64) + +RECOMMENDATIONS: + • For production: Use stable (4.16.2) or specific version tag + • For testing: Use latest (4.17.0) + • For LTS: Use lts (4.15.18) + • Avoid: Using generic tags like 'latest' in production + • Pin by digest: Use @sha256:abc123... for reproducibility + +NOTABLE: + • 3 tags updated in the last 7 days + • 15 release candidates available + • Average tag age: 45 days + • Update frequency: ~2 tags per week +================================================================================ +``` + +**For Small Repositories:** +``` +================================================================================ +CONTAINER IMAGE TAGS +================================================================================ +Repository: docker.io/library/alpine + +Total Tags: 47 + +ALL TAGS: +-------------------------------------------------------------------------------- +TAG CREATED SIZE ARCH DIGEST +latest 2024-01-20 12:00 7.3 MB multi sha256:abc123... +3.19 2024-01-20 12:00 7.3 MB multi sha256:abc123... +3.18 2023-11-15 09:30 7.0 MB multi sha256:def456... +3.17 2023-08-10 14:15 6.8 MB multi sha256:ghi789... +edge 2024-01-22 08:00 7.5 MB multi sha256:jkl012... +... + +RECOMMENDATIONS: + • For production: Use 3.19 (latest stable) + • For edge features: Use edge + • For compatibility: Use 3.18 or 3.17 +================================================================================ +``` + +## Examples + +1. **List tags for OpenShift release images**: + ``` + /container-image:tags quay.io/openshift-release-dev/ocp-release + ``` + Shows all available OpenShift release versions. + +2. **Check available UBI tags**: + ``` + /container-image:tags registry.redhat.io/ubi9/ubi + ``` + Lists all UBI 9 image tags. + +3. **Explore nginx versions**: + ``` + /container-image:tags docker.io/library/nginx + ``` + Shows available nginx versions and variants. + +4. **Check private repository tags**: + ``` + /container-image:tags registry.example.com/myorg/myapp + ``` + Lists tags from a private registry (requires authentication). + +5. **Analyze Prometheus tags**: + ``` + /container-image:tags quay.io/prometheus/prometheus + ``` + Shows Prometheus versions and release patterns. + +## Advanced Options + +The command can support optional filters and sorting: + +**Filter by Pattern:** +``` +/container-image:tags quay.io/openshift-release-dev/ocp-release --filter "4.17.*" +``` +Shows only 4.17.x tags. + +**Limit Results:** +``` +/container-image:tags docker.io/library/alpine --limit 10 +``` +Shows only the 10 most recent tags. + +**Sort Options:** +``` +/container-image:tags quay.io/myapp --sort version # Semantic version sort +/container-image:tags quay.io/myapp --sort date # Creation date sort +/container-image:tags quay.io/myapp --sort size # Size sort +``` + +**Architecture Filter:** +``` +/container-image:tags registry.example.com/myapp --arch arm64 +``` +Shows only tags that support arm64. + +## Error Handling + +- **Repository not found**: Verify repository name and registry +- **Authentication required**: Guide user to login with `skopeo login` +- **Network errors**: Check connectivity and registry availability +- **Tool not available**: Provide installation instructions for `skopeo` +- **Rate limiting**: Handle registry rate limits gracefully +- **Large repositories**: For repositories with 1000+ tags, sample or paginate results + +## Notes + +- **Tag Mutability**: Tags (except digests) can be reassigned to different images +- **Latest Tag**: "latest" doesn't always mean newest; it's just a convention +- **Digest Pinning**: For reproducible deployments, always use digest (@sha256:...) +- **Semantic Versioning**: Many projects follow semver (MAJOR.MINOR.PATCH) +- **Multi-arch Support**: Check which tags support your target architecture +- **Deprecation**: Older tags may be removed; check registry retention policies + +## Performance Considerations + +For repositories with many tags: +- The command samples tags rather than inspecting all +- Full inspection can be requested with `--full` flag +- Results can be cached for repeated queries +- Pagination is used for very large tag lists + +## Use Cases + +1. **Version Discovery**: Find the latest stable version before deployment +2. **Update Planning**: Identify available updates for current images +3. **Architecture Planning**: Verify multi-arch support before migration +4. **Cleanup Planning**: Identify old/unused tags for cleanup +5. **Compliance**: Document available versions for audit trails +6. **CI/CD Integration**: Automate image version selection +7. **Troubleshooting**: Compare production tag with available versions + +## Arguments + +- **$1** (repository): Required. The repository path (without tag). + - Format: `[registry/]repository` + - Examples: + - `quay.io/openshift-release-dev/ocp-release` + - `docker.io/library/nginx` + - `registry.redhat.io/ubi9/ubi` + - `registry.example.com/myorg/myapp` + +**Note**: Do NOT include the tag (`:tagname`) in the repository argument. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..d64bdc6 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,53 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:openshift-eng/ai-helpers:plugins/container-image", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "33defc343079aea7a3081186ca5fb6afad61a078", + "treeHash": "e9ab918676584c954b2ffe17a4fcf50a19ffb88da3dee776e887968e0d71661e", + "generatedAt": "2025-11-28T10:27:31.758237Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "container-image", + "description": "Container image inspection and analysis using skopeo and podman", + "version": "0.0.1" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "5bf7d2838a788ff7f70fedd95b1e5ce8af418df8560bf4401a6ada238e75373a" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "27e440c3f12db8cdc296f6378af7731c1a9fd840706ded7730f8312ae097c6d0" + }, + { + "path": "commands/inspect.md", + "sha256": "81c4af48deeb145346fc9a91ba7b8e289e8d21380be54f800ecc1f1f0edd42cf" + }, + { + "path": "commands/compare.md", + "sha256": "b2c6890bcd9e4b62b8b001e20945639ca7f3e996fb9bdece9ccbb3b972a57a85" + }, + { + "path": "commands/tags.md", + "sha256": "0ca5a76d2ae41990b1f55642c7cc357b17e1cf5ab3f980ec1871b886e00d3f88" + } + ], + "dirSha256": "e9ab918676584c954b2ffe17a4fcf50a19ffb88da3dee776e887968e0d71661e" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file