Managing Tag Retention Rules

Introduction to Tag Retention in MSR

Tag retention rules are essential for maintaining an efficient and organized registry. They help manage storage by defining policies that determine which image tags to retain and which to remove. This process is crucial for preventing the accumulation of outdated or unused images, optimizing storage usage, and supporting organizational policies for image lifecycle management.

Key Concepts:

• Tag Retention Rules: Policies that specify criteria for keeping or deleting image tags in a registry.

• Policy Filters: Parameters such as tags, repositories, or labels used to control the application of rules.

• Priority: The order in which rules are executed, allowing granular control over tag retention or removal.

Understanding Tag Retention Rules

Tag retention rules are evaluated against repositories within a project to determine which tags to keep and which to remove. By utilizing a combination of filters—such as specific tag patterns or image age—administrators can fine-tune retention policies to meet their organization’s needs.

Example Use Cases:

• Development Projects: Retain only the latest five tags of a repository to keep the environment clean and manageable.

• Production Repositories: Retain tags with specific labels like stable or release to ensure critical versions are preserved.

• Cleanup Operations: Remove all tags older than 30 days to free up storage space and eliminate obsolete images.

Configuring Tag Retention Rules in MSR

1. Access the Tag Retention Panel

   1. Log in to the MSR web interface using your credentials.

   2. Navigate to Projects and select the specific project where you want to configure tag retention.

   3. Select Policy.

   4. Click on Tag Retention under the project settings.

2. Define a New Rule

   1. Click + New Rule to initiate the configuration process.

3. Select matching or excluding rule

   1. In the Repositories drop-down menu, select matching or excluding.

   2. Use the Repositories text box to specify the repositories to which the rule will apply. You can define the target repositories using any of the following formats:

      • A specific repository name, such as my_repo_1.

      • A comma-separated list of repository names, such as my_repo_1,my_repo_2,your_repo_3.

      • A partial repository name with wildcard characters (*), for example:

        • my_* to match repositories starting with my_.

        • *_3 to match repositories ending with _3.

        • *_repo_* to match repositories containing repo in their name.

      • ** to apply the rule to all repositories within the project.

4. Select by artifact count or number of days to define how many tags to retain or the period to retain tags.

   Option	Description
   retain the most recently pushed # artifacts	Enter the maximum number of artifacts to retain, keeping the ones that have been pushed most recently. There is no maximum age for an artifact.
   retain the most recently pulled # artifacts	Enter the maximum number of artifacts to retain, keeping only the ones that have been pulled recently. There is no maximum age for an artifact.
   retain the artifacts pushed within the last # days	Enter the number of days to retain artifacts, keeping only the ones that have been pushed during this period. There is no maximum number of artifacts.
   retain the artifacts pulled within the last # days	Enter the number of days to retain artifacts, keeping only the ones that have been pulled during this period. There is no maximum number of artifacts.
   retain always	Always retain the artifacts identified by this rule.

5. Specifying Tags for Rule Application

   Use the Tags text box to define the tags that the rule will target. You can specify tags using the following formats:

   1. A single tag name, such as my_tag_1.

   2. A comma-separated list of tag names, such as my_tag_1,my_tag_2,your_tag_3.

   3. A partial tag name with wildcards (*), such as:

      • my_* to match tags starting with my_.

      • *_3 to match tags ending with _3.

      • *_tag_* to match tags containing tag.

   4. ** to apply the rule to all tags within the project.

   The behavior of the rule depends on your selection:

   • If you select matching, the rule is applied only to the tags you specify.

   • If you select excluding, the rule is applied to all tags in the repository except the ones you specify.

6. Save and Activate the Rule

   1. Once all fields are complete, click Save. The rule will now appear in the Tag Retention Rules table.

Managing and Executing Retention Policies

Viewing and Managing Rules

1. Access the Tag Retention Policy page in your selected Project to view all configured rules.

2. To edit a rule, go to Retention rules, select ACTION, then Edit to make changes to the scope, filters, or priority.

3. To delete a rule, use the Delete option from ACTION to remove outdated or unnecessary rules.

Executing Retention Rules

1. Scheduled Execution:

   • Under Projects select the project you would like to adjust the retention runs for.

   • Select Policy

   • Under retention rules ensure there is a policy in place.

   • Under Schedule select Hourly, Daily, Weekly, or Custom.

     • Selecting Custom will have you modify a cron schedule.

2. Manual Execution:

   • Under Projects select the project you would like to adjust the retention runs for.

   • Select Policy

   • Under retention rules ensure there is a policy in place.

   • You can now select DRY RUN to ensure the run is successful without any adverse impact or RUN NOW.

3. Review Execution Logs:

   • After execution, view logs to confirm the outcome or troubleshoot issues. Logs display details on retained and deleted tags, along with any errors encountered.

   • Under Policy then Retention runs, select the job you would like to investigate, then select the > symbol.

   • You will see the policy for each repository in the project. To view the logs for each repository select the Log on the far right which shows a log per repository.

Interaction Between Tag Retention Rules and Project Quotas

The Harbor system administrator can configure project quotas to set limits on the number of tags a project can contain and the total amount of storage it can consume. For details about configuring project quotas, refer to Configure Project Quotas.

When a quota is applied to a project, it acts as a strict limit that cannot be exceeded. Even if you configure tag retention rules that would retain more tags than the quota allows, the quota takes precedence. Retention rules cannot override or bypass project quotas.