Docker image Metadata
How to use custom metadata in your Docker images
Images built by Codefresh can be annotated with customized metadata. This article explains how to create advanced view of your images and enrich them with custom metadata which perfectly fits your flow and image management process.
We have since expanded this feature and now you are able to add custom annotations to pipelines and builds as well. Notice also that the syntax shown in this page is deprecated but still supported. For the new syntax see our hooks documentation.
Images built by Codefresh can be annotated with an array of key-value metadata. Metadata values may be of the following types:
|String||Use string||‘Example note’|
|Number||use numeric value to set this kind of annotation||9999|
|Boolean||Use true / false value||true|
|Percentage bar||use 0-100 value ending with %||85%|
You can also use Expression evaluations to set metadata.
Annotate your images using Codefresh YAML
You can annotate an image as part of it’s builds process and also on post build steps.
Build step Image Metadata Annotation
You can annotate an image as part of its build process by declaring the metadata value on the Build step:
- An array of key-value metadata
Adding annotations to Built images on post-build steps
Any step in the YAML workflow can annotate built images by using Post-Step Operations. To annotate a built image, configure any step with:
- The post-step operation
- A list of target images with the variable syntax of
- An array of key-value metadata
Example - Quality Image Metadata Annotation
You can set a quality indicator to images to show if they passed or failed tests. An image with the boolean annotation
CF_QUALITY set to true will have a quality indicator in the ‘Images’ view.
Image quality has 3 indicators:
- True - this image is considered a quality image (ex. passed tests),
- False - this image is not considered a quality image (ex. when tests failed but the image was already built).
- No value (nobody set the annotation) - this image has no quality indicator.
Viewing Image Metadata Annotations
You can view an image’s metadata annotation by:
- Navigating to the
- Selecting the target image
- Selecting the
In addition, you can add selected annotations to the images table on images page. To display an annotation in the image table, click on the gear icon at the top right corner of image page and then select all annotations you want to display.
Annotating images programmatically
It is also possible to annotate images with the Codefresh CLI.
First find the id of an image that you wish to annotate with the command
codefresh get images
You can also search for a specific image by name:
$ codefresh get images --image-name custom ID NAME TAG CREATED SIZE PULL b5f103a87856 my-custom-docker-image bla Fri Feb 01 2019 91.01 MB r.cfcr.io/kostis-codefresh/my-custom-docker-image:bla
Then once you have the ID of the image you can use the annotate command to add extra metadata:
codefresh annotate image b5f103a87856 -l coverage=75
Using custom metadata in Codefresh pipelines
You can also use the Codefresh CLI to fetch existing metadata from images. It is then very easy to extract and process specific fields with yq
Here is an example
$ codefresh get image b5f103a87856 --output=yaml | yq -r .annotations.coverage 75
You can then easily process the metadata (e.g. with scripts) and take decisions according to them. Here is an example step that will fail the build if test coverage on an image is less than 80%
The possibilities are endless as you can take any combination of image metadata and use any complex conditional in order to process them in a Codefresh pipeline.