> ## Documentation Index
> Fetch the complete documentation index at: https://www.qovery.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Image Mirroring
> Optimize deployments with local image caching
When Qovery manages applications on your systems, it stores all generated container images in a registry on your cloud infrastructure. This feature is called image mirroring.
## Why Image Mirroring?
Image mirroring serves two main purposes:
1. **Speed up deployments**: By caching built images, Qovery avoids rebuilding identical images, significantly accelerating the deployment process
2. **Secure scale-up operations**: When Kubernetes needs to scale up your application and create additional instances, having images stored locally ensures the operation succeeds even if the third-party registry is unavailable
## How It Works
The mirroring registry is accessible and configurable through the Qovery interface under the "Mirroring registry" section of your cluster.
### For Applications Built by Qovery CI
When Qovery builds your application from Git:
1. After building, Qovery CI pushes the generated image to the mirroring registry
2. Images are organized by Git repository with naming: `z-git_repo_name`
3. Image tags are derived from: commit ID, repository path, Dockerfile path, content, and ARGS variables
4. Before building, Qovery checks if a matching image already exists
5. If found, the build is skipped and the cached image is used
6. Unused images are automatically deleted when no longer referenced
7. Remote cache functionality (AWS, GCP, Scaleway) rebuilds only changed layers
### For Applications from Third-Party Registries
The behavior depends on the configured mirroring mode:
#### Service Mode (Default)
Each service maintains its own mirroring repository.
**Characteristics:**
* Images are organized per Qovery service (isolated processes)
* Automatic cleanup when images become unnecessary
* Downside: Identical images across services are mirrored multiple times
#### Cluster Mode
All applications on the same cluster share one mirroring repository.
**Characteristics:**
* Reduces duplication for shared images across environments
* Requires manual image management via TTL settings
* Not available on Scaleway
## Important: Use Unique Image Tags
Image tags must be unique. Both Qovery's mirroring system and Kubernetes employ caching mechanisms. Using the same tag for different image versions prevents new versions from deploying, causing applications to run outdated code.
Using tags like `latest` or other mutable tags can cause serious issues because the cached image in the mirroring registry may not be updated when you push a new version with the same tag.
**Best practices:**
* Use specific version tags: `myapp:v1.2.3`, `myapp:commit-abc123`
* Use immutable digests: `myapp@sha256:abc123...`
* Avoid mutable tags like `latest`, `stable`, or `prod`
## Disabling Mirroring
To skip mirroring operations, you can push your built images directly into the mirroring registry within repositories that match your image names.
Alternatively, if the source registry URL matches the cluster registry URL, mirroring is automatically skipped.
**Example for AWS:**
For an image `nginx` with cluster registry `https://32432542.dkr.ecr.eu-west-3.amazonaws.com`:
Push to: `https://32432542.dkr.ecr.eu-west-3.amazonaws.com/nginx`
## Image Retention Policy
Configurable TTL (Time To Live) settings control image retention duration via the advanced setting `image_retention_time`.
Modifications to the retention policy only affect newly created repositories. Existing repositories remain unchanged.
## Next Steps
Configure deployment stages
Choose deployment strategy
Configure container registries
Manage deployment lifecycle