Image Naming and Tagging Conventions
What you'll learn: How to properly name and tag container images so they're organized, discoverable, and versioned correctly in registries.
When you push images to a registry, you need a clear naming scheme—like organizing books in a library. A poorly named image is like a book with no title or author: impossible to find later.
Image Naming Structure
Container images follow this pattern:
[registry-host]/[namespace]/[repository]:[tag]
- Registry host: Where the image lives (e.g.,
docker.io,gcr.io) - Namespace: Organization or user (e.g.,
mycompany,johndoe) - Repository: The application name (e.g.,
webapp,api-service) - Tag: Version identifier (e.g.,
v1.2.3,latest)
Example: docker.io/mycompany/webapp:v1.2.3
Tagging Best Practices
Tags are like version labels on software boxes. Common conventions:
- Semantic versions:
1.0.0,2.1.5(clear, production-ready) - Environment tags:
dev,staging,prod - Git commit SHAs:
abc123f(traceable to source code) - Date stamps:
2024-01-15(time-based snapshots)
Avoid relying on latest—it's ambiguous and changes frequently. Think of it as "newest book" rather than "this specific edition."
Naming Rules
- Use lowercase letters, numbers, hyphens, and underscores
- Separate words with hyphens:
user-service, notuserservice - Keep names descriptive but concise:
payment-apibeatsp-a - Be consistent across your organization
Key Takeaway: Use structured, meaningful names with specific version tags—this makes images traceable, deployable, and manageable across environments and teams.