Image Retention

As you continuously build and update your golden images, the number of stored images in your cloud accounts can grow rapidly. To help manage storage costs and maintain a clean environment, Klarity ImageFactory provides automated image retention and cleanup features.

How Image Retention Works

Image retention is configured at the template level. By defining a retention policy, you instruct ImageFactory to automatically remove older versions of an image when new ones are successfully distributed.

The imageRetainCount Setting

The primary configuration for retention is the imageRetainCount property. This integer value defines the maximum number of image versions to keep for a specific template in each of your target cloud accounts.

• Default Behavior: If imageRetainCount is not set (or set to 0), ImageFactory will not perform any automatic deletion. This results in unlimited retention.
• Cleanup Trigger: When a new image is successfully built and distributed to an account, ImageFactory checks the total number of existing images for that template. If the count exceeds the imageRetainCount, the platform automatically identifies and deletes the oldest versions.

Required Permissions for Cleanup

For the automatic cleanup to function, the credentials provided during account onboarding must have the necessary permissions to delete or deregister images:

Provider	Required Action	Purpose
AWS	ec2:DeregisterImage, ec2:DeleteSnapshot	Remove AMIs and their associated EBS snapshots.
Azure	Microsoft.Compute/galleries/images/versions/delete	Delete specific image versions from the gallery.
GCP	compute.images.delete	Remove custom images from the project.
Exoscale	compute.templates.delete	Delete private templates.
IBM Cloud	is.image.delete	Remove custom images from the VPC registry.

Scope and Limitations

• China Regions: Please note that automatic image retention is currently not available for accounts operating within the AWS China or Azure China scopes.
• Distribution Success: Cleanup is only triggered after a new image is successfully distributed. If a build fails, no existing images are removed.
• Manual Deletion: You can always manually delete a specific image version through the ImageFactory API using the DELETE endpoint for images.

Tracking Deletions

ImageFactory tracks the lifecycle of every distributed image. You can monitor deletions through the following mechanisms:

• Deleted Flag: The cloud_distributions object for an image includes a deleted boolean flag. This flag is set to true once the image has been successfully removed from the target cloud account.
• Error Status: If an automatic cleanup attempt fails (e.g., due to missing permissions), the distribution status for that specific cleanup operation is set to DELETE_ERROR. You can view the error details in the console to take corrective action.

Best Practices for Retention

1. Set a Reasonable Limit: For most production environments, keeping 3 to 5 versions of a golden image is sufficient for rollback purposes while keeping storage costs under control.
2. Monitor Cleanup Errors: Periodically check for DELETE_ERROR statuses to ensure that your cloud accounts are not accumulating orphaned images due to permission issues.
3. Use Tags: Ensure your images are correctly tagged so you can easily identify which versions are currently in use by your running instances before they are deleted by the retention policy.

Configuring Retention

You can configure image retention in the Basic Settings step when creating a new template, or by editing an existing template's settings. Set the Image Retention field to the desired number of images to keep.

For a step-by-step walkthrough, see the Creating a Template guide.

Via API

You can also set the retention count programmatically when creating or updating a template:

mutation UpdateTemplateRetention {
  updateTemplate(id: "your-template-id", input: {
    imageRetainCount: 3
  }) {
    id
    imageRetainCount
  }
}

By implementing a clear retention policy, you can automate the maintenance of your image library and ensure that only the most relevant and secure versions are available for deployment.