Skip to content

docs(QOV-2094): document ECR pull through cache #183

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pggb25 merged 1 commit into from
Sep 3, 2026
Merged

docs(QOV-2094): document ECR pull through cache #183

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions docs/configuration/cluster-advanced-settings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -520,6 +520,35 @@ Changing this setting will only affect new ECR repositories created after the ch

**Default Value:** `31536000` (1 year)

<a id="aws-ecr-enable-pull-through-cache"></a>

### aws.ecr.enable_pull_through_cache

@cubic-dev-ai cubic-dev-ai Bot Aug 27, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: This entry advertises aws.ecr.enable_pull_through_cache as a supported cluster setting, but the current public ClusterAdvancedSettings schema does not define it. Update the API source before advertising this setting for API use, or state the configuration surface that actually supports it.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At docs/configuration/cluster-advanced-settings.mdx, line 525:

<comment>This entry advertises `aws.ecr.enable_pull_through_cache` as a supported cluster setting, but the current public `ClusterAdvancedSettings` schema does not define it. Update the API source before advertising this setting for API use, or state the configuration surface that actually supports it.</comment>

<file context>
@@ -520,6 +520,35 @@ Changing this setting will only affect new ECR repositories created after the ch
 
+<a id="aws-ecr-enable-pull-through-cache"></a>
+
+### aws.ecr.enable_pull_through_cache
+
+**Cloud Provider:** <img src="/images/logos/cloud-providers/aws-icon.svg" alt="AWS" width="20"  style={{display: "inline", verticalAlign: "middle", marginRight: "4px"}} />
</file context>
Fix with cubic


**Cloud Provider:** <img src="/images/logos/cloud-providers/aws-icon.svg" alt="AWS" width="20" style={{display: "inline", verticalAlign: "middle", marginRight: "4px"}} />

**Type:** `boolean`

**Description:** Cache the public ECR images used by Qovery-managed infrastructure components in the private ECR registry of the cluster's AWS account and region. This reduces NAT Gateway traffic generated when nodes pull system images from `public.ecr.aws`.

When enabled, Qovery:

- Configures an Amazon ECR pull through cache rule for `public.ecr.aws` under the `qovery-ecr-public` repository prefix.
- Rewrites public ECR image references in Qovery-managed infrastructure Helm charts to use the private regional ECR registry.
- Grants EKS worker and Karpenter node roles the permissions required to populate the cache on the first pull.
- Creates the `ecr.api` and `ecr.dkr` interface VPC endpoints. Image layers use the S3 gateway endpoint.

<Warning>
This setting is available only for Qovery-managed EKS clusters that use Karpenter and a Qovery-managed VPC with NAT Gateways. It is not supported for clusters without NAT Gateways or clusters using a user-provided network. Availability is currently limited to organizations enabled by Qovery.
</Warning>

<Info>
Cached images expire 90 days after they are imported into the private ECR registry. If an expired image is requested again, Amazon ECR imports it again from the public registry. Enabling this setting adds private ECR storage and VPC interface endpoint charges to the AWS account, while reducing NAT Gateway processing charges for public ECR pulls.

@cubic-dev-ai cubic-dev-ai Bot Aug 27, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Amazon ECR does not give pull-through-cache repositories a 90-day expiry by default; the linked AWS documentation says the default lifecycle policy is omitted. If Qovery applies a 90-day lifecycle policy, identify it as Qovery's policy; otherwise remove this expiry claim and describe lifecycle-policy-controlled retention.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At docs/configuration/cluster-advanced-settings.mdx, line 545:

<comment>Amazon ECR does not give pull-through-cache repositories a 90-day expiry by default; the linked AWS documentation says the default lifecycle policy is omitted. If Qovery applies a 90-day lifecycle policy, identify it as Qovery's policy; otherwise remove this expiry claim and describe lifecycle-policy-controlled retention.</comment>

<file context>
@@ -520,6 +520,35 @@ Changing this setting will only affect new ECR repositories created after the ch
+</Warning>
+
+<Info>
+Cached images expire 90 days after they are imported into the private ECR registry. If an expired image is requested again, Amazon ECR imports it again from the public registry. Enabling this setting adds private ECR storage and VPC interface endpoint charges to the AWS account, while reducing NAT Gateway processing charges for public ECR pulls.
+</Info>
+
</file context>
Suggested change
Cached images expire 90 days after they are imported into the private ECR registry. If an expired image is requested again, Amazon ECR imports it again from the public registry. Enabling this setting adds private ECR storage and VPC interface endpoint charges to the AWS account, while reducing NAT Gateway processing charges for public ECR pulls.
Cached images are revalidated against the public registry at least once every 24 hours; retention is controlled by the lifecycle policy applied to the cache repositories.
Fix with cubic

</Info>

See [Amazon ECR pull through cache rules](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache.html) for details about how Amazon ECR populates and refreshes cached images.

**Default Value:** `false`

<a id="registry-mirroring-mode"></a>

### registry.mirroring_mode
Expand Down
Loading