---
title: "Container Image Inventory Unification"
slug: "container-image-inventory-unification"
updated: 2026-10-22T15:02:28Z
published: 2026-10-22T15:02:28Z
canonical: "docs.safe.security/container-image-inventory-unification"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safe.security/llms.txt
> Use this file to discover all available pages before exploring further.

# Container Image Inventory Unification

#### **1. Container Image Inventory Unification**

**1.1 Overview**

Managing container images in complex, multi-cluster environments requires a unified and normalized approach. Container image metadata is distributed across clusters, registries, and running containers, often leading to visibility gaps and duplication. This document outlines the structure of container-related assets, key concepts around container images, the methodology for unifying image inventory, and the common challenges encountered during this process.

![](https://cdn.document360.io/23dc20b8-a989-48c0-8653-f1d3e4abc734/Images/Documentation/diagram.png)

---

#### **2. Container Ecosystem Asset Types**

Container assets are categorized into four subtypes: Cluster, Image, Workload, and Instance.

**2.1 Cluster**

Clusters represent persistent orchestration environments where containers run. They are foundational infrastructure components.

**Examples:**

- AWS Elastic Kubernetes Service (EKS)
- Azure Kubernetes Service (AKS)
- Google Kubernetes Engine (GKE)
- On-premises Kubernetes clusters
- Docker Swarm clusters
- Red Hat OpenShift clusters

**2.2 Image**

Images are packaged application code and dependencies. They are persistent artifacts stored in registries.

**Examples:**

- Application images (e.g., web servers, APIs, databases)
- Infrastructure images (e.g., proxies, monitoring agents)
- Utility images (e.g., backup tools, CI/CD components)

**2.3 Workload**

Workloads are configurations that define how container images should be deployed and managed within clusters. These definitions are persistent.

**Examples:**

- Kubernetes Deployments
- StatefulSets
- DaemonSets
- CronJobs
- Jobs
- ReplicaSets

**2.4 Instance**

Instances refer to the actual running containers instantiated from images, based on workload definitions. These are ephemeral and short-lived depending on workload type, scaling policies, and infrastructure conditions.

**Examples:**

- Kubernetes Pods
- Individual containers within pods
- Docker containers

---

#### **3. Container Image Concepts**

**3.1 Registry**

A registry is a service that stores and distributes container images. Registries may be public or private and typically support access control features such as authentication and authorization.

**Examples:**

- Docker Hub
- Amazon Elastic Container Registry (ECR)
- Google Container Registry
- Azure Container Registry
- GitHub Container Registry

**3.2 Namespace**

A namespace is a logical grouping within a registry, usually representing an organization, user, or project.

**Example:** In docker.io/nginx, nginx is the namespace in Docker Hub.

**3.3 Image Name**

The image name identifies a specific container image within a namespace.

**Example:** In docker.io/bitnami/postgresql, postgresql is the image name.

Note that the namespace and the image name together are referred to as the repository.

**3.4 Image Tags**

Tags are human-readable labels pointing to specific versions of an image.

**Examples:** latest, v1.2.3, stable, alpine

**Note:** Image tags are not part of the asset names or identifiers:

- **Tags are mutable pointers, not identifiers** — The same tag (even version tags like v1.0) can point to different image content over time: on Monday app:v1.0 might refer to digest sha256:abc123..., but after a rebuild on Wednesday, the same app:v1.0 tag points to completely different content with digest sha256:def456....

  

- **Digests provide guaranteed immutability** — A digest reference like registry/app@sha256:abc123... always refers to exactly the same image content, ensuring consistent tracking and eliminating potential confusion when the same tag gets reused.

  

- **Accurate audit trails require immutable references** — In security incidents, knowing precisely which image ran is critical. With tag-based tracking, logs showing app:v1.0 become ambiguous (was it the vulnerable Monday build or Wednesday's fixed version?), while digest-based records provide forensic certainty.

  

- **Reliable deduplication depends on content addressing** — The same image content can have multiple tags, and tags can point to different content over time, making them unsuitable for deduplication. Digest-based tracking ensures each unique image is tracked exactly once.

  

- **Time-series analysis becomes more meaningful** — Daily ingestion with digest-based tracking shows clear transitions in image content:

| Date | Image | CVEs | Comments |
| --- | --- | --- | --- |
| 2025-03-01 | app@sha256:abc123... | 3 |  |
| 2025-03-02 | app@sha256:abc123... | 3 |  |
| 2025-03-03 | app@sha256:def456... | 0 | Clearly shows a different image |

  

- **Tag information isn't lost** — Using digest-based primary keys doesn't mean discarding tag information. We maintain a temporal mapping of which digests had which tags on which dates, preserving tag history while using digests as stable identifiers.

  

- **Industry best practices favor digest references** — For production deployments, security-conscious organizations increasingly specify images by digest rather than tag to eliminate the risk of "tag sliding" and ensure reproducible deployments.

**3.5 Digest and Repo Digest**

- **Digest:** A SHA-256 hash that uniquely identifies the content of an image.
  - **Example:** sha256:a4f493d8f76bd9eed9c20293eecb0390be62e789c6e21140e7f6ae3baf9162d6
- **Repo Digest:** A combination of the image reference and the digest, typically as returned by container runtimes or registries.
  - **Example:** docker.io/nginx@sha256:a4f493d8f76bd9eed9c20293eecb0390be62e789c6e21140e7f6ae3baf9162d6

**3.6 Digest Variability and Inconsistencies**

The hash in a repo digest may differ from the image digest. This can occur due to:

- Registry-specific processing or normalization
- Differences between manifest and image digests as per OCI specifications
- Multi-architecture images with different digests for manifest lists and platform-specific images
- Format conversions between OCI and Docker manifests

---

#### **4. Image Inventory Unification Approach**

The goal of image inventory unification is to provide a single, normalized view of all container images in use, including metadata correlations and usage mappings across workloads and clusters.

**4.1 Correlation Process**

1. **Collect** image references from all available clusters and sources.
2. **Resolve** each reference into its canonical components:
  - Registry
  - Namespace
  - Image Name
  - Repo Digest
  - Image Digest

**Deduplicate** based on the canonical full image name: php-template CopyEdit <registry>/<namespace>/<image_name>@<repo_digest or image_digest>

1. **Example:** docker.io/library/nginx@sha256:a4f493d8f76bd9eed9...

Tags are not used for deduplication due to their mutable and non-unique nature.

**4.2 Mapping Process**

Once deduplicated, images are mapped to workloads and instances using a consistent tagging and tracking strategy:

| **Mapping Type** | **Description** |
| --- | --- |
| Asset Name | Set as <registry>/<namespace>/<image_name> |
| Container Name Tag | Format: Container name: <workload> – allows correlation between images and the workloads using them |
| Instance Count Mapping | Maps each image to the number of container instances currently or historically deployed from it |
| Running Instance Tag | Adds Has Running Containers tag if there is at least one active container using the image |

  

#### **5. Challenges in Container Image Inventory**

**5.1 Partial Observability**

Some environments and tools do not expose complete metadata for images.

**Examples:**

- Cluster APIs may omit registry URLs or credentials
- Air-gapped environments may rely on internal registries with rewritten paths
- Proxies may mask original source
- Scanners may detect digests only, without tags

**Impact:** Limited observability leads to gaps in lineage tracking and reduces the accuracy of inventory unification.

**5.2 Tag Non-Uniqueness**

Tags are not reliable identifiers because they can:

- Be overwritten to point to different content (e.g., latest)
- Be reused across different registries for unrelated content
- Represent moving targets over time (e.g., patched versions under the same tag)

**Impact:** Reliance on tags for deduplication or tracking results in errors and inconsistencies.

**5.3 Digest Inconsistencies**

Multiple digests may be associated with the same image depending on:

- Manifest types (e.g., manifest list vs. image manifest)
- Registry processing and normalization
- Multi-architecture packaging
- Format translation between OCI and Docker v2 schemas

**Impact:** Digest mismatches can lead to duplicate counting or missed correlations across tools.

---

#### **6. Summary**

This container image inventory unification approach enables organizations to:

- Normalize and deduplicate images across clusters and registries
- Track image-to-workload and image-to-instance mappings
- Gain visibility into actual usage and active container instances
- Address security, compliance, and operational requirements more effectively