zhongwei/gh-openshift-eng-ai-helpers-plugins-container-image
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:45:46 +08:00
commit 791b1a4c69
6 changed files with 981 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

315
commands/inspect.md Normal file
View File

@@ -0,0 +1,315 @@
---
description: Inspect and provide detailed breakdown of a container image
argument-hint: <image>
---
## Name
container-image:inspect
## Synopsis
```
/container-image:inspect <image>
```
## 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://<image>
```
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://<image>
```
- 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://<image>@<platform-digest>
```
- 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: <default>
WorkingDir: <default>
Entrypoint: ["/usr/bin/cluster-version-operator"]
Cmd: <none>
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:
<none>
LABELS:
io.openshift.release: 4.20.0
io.openshift.release.base-image-digest: sha256:6f58f521f51ae43617d2dead1efbe9690b605d646565892bb0f8c6030a742ba7
VOLUMES:
<none>
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 <registry>` or `podman login <registry>`
- 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...`