[Build] Quay Container Image Size Optimization

Overview

Migrate the Red Hat Quay downstream container images to use UBI minimal 9.7 as the base layer and remove unnecessary build dependencies from the final image. This initiative reduces image size by approximately 30%, minimizes attack surface by using a smaller base image, and improves deployment efficiency.

Context

The current Quay container images use standard UBI base images which include packages and utilities not strictly required for runtime operation. Additionally, build-time artifacts such as npm caches may be inadvertently included in final images. This results in larger image sizes, longer download/deployment times, and a broader security attack surface. The UBI minimal 9.7 base provides RHEL compatibility while significantly reducing image footprint.

Reference: PROJQUAY-9604

Scope

In Scope

• Switch primary Quay Dockerfile FROM base to ubi9-minimal:9.7
• Update all intermediate build stages to use appropriate minimal/builder images
• Implement multi-stage build optimization to remove Node.js build caches
• Remove pip caches and other build-time artifacts from final image
• Identify and explicitly install only required runtime dependencies
• Validate all functionality with integration and e2e tests
• Ensure security scans pass without new critical/high vulnerabilities
• Achieve approximately 30% image size reduction

Out of Scope

• Changes to Clair scanner base images (separate initiative)
• PostgreSQL/Redis container modifications
• Upstream community Quay images (focus is downstream Red Hat Quay)
• Security hardening (capabilities, seccomp, read-only filesystem) - covered by PROJQUAY-9605

Child Stories

1. Switch to UBI Minimal 9.7 Base Image: Update the main Dockerfile to use ubi9-minimal:9.7 as the base image. Identify packages missing from the minimal image that are required for Quay runtime operation and explicitly install them using microdnf. Update intermediate build stages to use appropriate UBI 9 builder images. Validate all Quay modes (registry, config, repomirror, migrate) function correctly with the new base.
2. Remove Unnecessary Build Dependencies from Final Image: Optimize multi-stage builds to ensure build-time artifacts do not leak into the final image. Remove npm/Node.js caches, pip build caches, and any other build dependencies. Validate .dockerignore effectiveness. Measure and verify image size reduction target of approximately 30%.

Dependencies

• Technical:
  • UBI minimal 9.7 availability in registry.access.redhat.com
  • Node.js 22 and Python 3.12 builder images for UBI 9
  • Go toolset for config-tool compilation
• Cross-team:
  • Release Engineering for downstream build pipeline updates
  • QE for test coverage validation
• External:
  • Prometheus pushgateway binary compatibility with minimal base
  • Third-party Python packages compatibility with minimal image

Success Criteria

• [ ] Final image size is ≥30% smaller than current production image
• [ ] All Quay modes (registry, config, repomirror, migrate) function correctly
• [ ] Storage backend operations work (S3, Azure, Swift, local, etc.)
• [ ] User authentication and authorization work correctly
• [ ] Registry push/pull operations pass all protocol tests
• [ ] Garbage collection and other worker processes function normally
• [ ] Security scans pass with no new critical/high vulnerabilities
• [ ] No npm/Node.js or pip caches present in final image layers

Technical Approach

Components Affected

• Dockerfile: Primary build definition requiring base image and stage updates
• web/Dockerfile: Standalone UI Dockerfile (may need updates for consistency)
• config-tool/Dockerfile: Go-based config tool build
• .dockerignore: Ensure npm/node caches excluded
• quay-entrypoint.sh: Validate compatibility with minimal base
• conf/init/*.sh: Init scripts must work with minimal package set

Key Technical Decisions

• Base image selection: Use registry.access.redhat.com/ubi9-minimal:9.7 for final stage; continue using builder images for compilation stages
• Package management: Use microdnf instead of dnf for minimal images
• Multi-stage strategy: Maintain current multi-stage approach but ensure no cache leakage between stages
• Cache cleanup: Explicit removal of npm and pip caches in Dockerfile before final layer creation

Risks and Mitigations

• Risk: Missing runtime dependencies in minimal image cause unexpected failures
  Mitigation: Comprehensive functional testing across all Quay modes; staged rollout
• Risk: Package name/availability differences between ubi8 and ubi9-minimal
  Mitigation: Audit all dnf/microdnf install commands; test package availability before migration
• Risk: Performance regression due to missing system libraries
  Mitigation: Performance benchmarking before and after migration
• Risk: Build artifacts still present in final image despite multi-stage build
  Mitigation: Explicit cache cleanup commands; image layer inspection validation

Testing Strategy

• Unit testing: Existing Python unit tests run against new image
• Registry protocol tests: make registry-test validates OCI/Docker protocol compliance
• Integration testing: Test all storage backends, auth providers, and API endpoints
• E2E testing: Playwright/Cypress tests for UI functionality
• Mode testing: Validate registry, config, repomirror, migrate entry points
• Image inspection: Verify no npm/pip caches in final image layers
• Size validation: Measure and compare image size against baseline

Rollout Strategy

• Feature flag not applicable (build-time change)
• Staged rollout: dev → staging → production builds
• Backward compatibility: New image should be drop-in replacement
• Rollback plan: Revert Dockerfile changes; previous image tags remain available
• Version-specific documentation for 3.17+ deployments

Documentation Needs

• User-facing: Updated installation guide noting image size improvements
• Release notes: Document base image change and size reduction
• Migration notes: Any configuration changes required for 3.17 upgrade

Related Work

• Original Feature: PROJQUAY-9604
• Security Hardening Feature: PROJQUAY-9605
• NPM Cache Bug: PROJQUAY-9720
• Upstream Initiative: OCPSTRAT-2553 (Switch Red Hat operators to UBI Minimal)