Store digest of latest image in ImagePolicy status

api/v1beta2/imagepolicy_types.go

@@ -1,5 +1,5 @@
 /*
-Copyright 2022 The Flux authors
+Copyright 2023 The Flux authors
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -42,8 +42,26 @@ type ImagePolicySpec struct {
 	// ordered and compared.
 	// +optional
 	FilterTags *TagFilter `json:"filterTags,omitempty"`
+	// DigestReflectionPolicy governs the setting of the `.status.latestRef.digest` field.
+	// +kubebuilder:default:=Never
+	DigestReflectionPolicy ReflectionPolicy `json:"digestReflectionPolicy,omitempty"`
 }
 
+// ReflectionPolicy describes a policy for if/when to reflect a value from the registry in a certain resource field.
+// +kubebuilder:validation:Enum=Always;IfNotPresent;Never
+type ReflectionPolicy string
+
+const (
+	// ReflectAlways means that a value is always reflected with the latest value from the registry even if this would
+	// overwrite an existing value in the object.
+	ReflectAlways ReflectionPolicy = "Always"
+	// ReflectIfNotPresent means that the target value is only reflected from the registry if it is empty. It will
+	// never be overwritten afterwards, even if it changes in the registry.
+	ReflectIfNotPresent ReflectionPolicy = "IfNotPresent"
+	// ReflectNever means that no reflection will happen at all.
+	ReflectNever ReflectionPolicy = "Never"
+)
+
 // ImagePolicyChoice is a union of all the types of policy that can be
 // supplied.
 type ImagePolicyChoice struct {
@@ -101,16 +119,45 @@ type TagFilter struct {
 	Extract string `json:"extract"`
 }
 
+// ImageRef represents an image reference.
+type ImageRef struct {
+	// Name is the bare image's name.
+	Name string `json:"image,omitempty"`
+	// Tag is the image's tag.
+	Tag string `json:"tag,omitempty"`
+	// Digest is the image's digest.
+	// +optional
+	Digest string `json:"digest,omitempty"`
+}
+
+func (r ImageRef) String() string {
+	res := r.Name + ":" + r.Tag
+	if r.Digest != "" {
+		res += "@" + r.Digest
+	}
+	return res
+}
+
 // ImagePolicyStatus defines the observed state of ImagePolicy
 type ImagePolicyStatus struct {
 	// LatestImage gives the first in the list of images scanned by
 	// the image repository, when filtered and ordered according to
 	// the policy.
+	// Deprecated: Replaced by the composite "latestRef" field.
 	LatestImage string `json:"latestImage,omitempty"`
 	// ObservedPreviousImage is the observed previous LatestImage. It is used
 	// to keep track of the previous and current images.
+	// Deprecated: Replaced by the composite "observedPreviousRef" field.
 	// +optional
 	ObservedPreviousImage string `json:"observedPreviousImage,omitempty"`
+	// LatestRef gives the first in the list of images scanned by
+	// the image repository, when filtered and ordered according
+	// to the policy.
+	LatestRef *ImageRef `json:"latestRef,omitempty"`
+	// ObservedPreviousRef is the observed previous LatestRef. It is used
+	// to keep track of the previous and current images.
+	// +optional
+	ObservedPreviousRef *ImageRef `json:"observedPreviousRef,omitempty"`
 	// +optional
 	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
 	// +optional
@@ -142,6 +189,13 @@ type ImagePolicy struct {
 	Status ImagePolicyStatus `json:"status,omitempty"`
 }
 
+func (p ImagePolicy) GetDigestReflectionPolicy() ReflectionPolicy {
+	if p.Spec.DigestReflectionPolicy != "" {
+		return p.Spec.DigestReflectionPolicy
+	}
+	return ReflectNever
+}
+
 //+kubebuilder:object:root=true
 
 // ImagePolicyList contains a list of ImagePolicy

config/crd/bases/image.toolkit.fluxcd.io_imagepolicies.yaml

@@ -230,6 +230,15 @@ spec:
             description: ImagePolicySpec defines the parameters for calculating the
               ImagePolicy.
             properties:
+              digestReflectionPolicy:
+                default: Never
+                description: DigestReflectionPolicy governs the setting of the `.status.latestRef.digest`
+                  field.
+                enum:
+                - Always
+                - IfNotPresent
+                - Never
+                type: string
               filterTags:
                 description: FilterTags enables filtering for only a subset of tags
                   based on a set of rules. If no rules are provided, all the tags
@@ -383,17 +392,47 @@ spec:
                   type: object
                 type: array
               latestImage:
-                description: LatestImage gives the first in the list of images scanned
+                description: 'LatestImage gives the first in the list of images scanned
                   by the image repository, when filtered and ordered according to
-                  the policy.
+                  the policy. Deprecated: Replaced by the composite "latestRef" field.'
                 type: string
+              latestRef:
+                description: LatestRef gives the first in the list of images scanned
+                  by the image repository, when filtered and ordered according to
+                  the policy.
+                properties:
+                  digest:
+                    description: Digest is the image's digest.
+                    type: string
+                  image:
+                    description: Name is the bare image's name.
+                    type: string
+                  tag:
+                    description: Tag is the image's tag.
+                    type: string
+                type: object
               observedGeneration:
                 format: int64
                 type: integer
               observedPreviousImage:
-                description: ObservedPreviousImage is the observed previous LatestImage.
-                  It is used to keep track of the previous and current images.
+                description: 'ObservedPreviousImage is the observed previous LatestImage.
+                  It is used to keep track of the previous and current images. Deprecated:
+                  Replaced by the composite "observedPreviousRef" field.'
                 type: string
+              observedPreviousRef:
+                description: ObservedPreviousRef is the observed previous LatestRef.
+                  It is used to keep track of the previous and current images.
+                properties:
+                  digest:
+                    description: Digest is the image's digest.
+                    type: string
+                  image:
+                    description: Name is the bare image's name.
+                    type: string
+                  tag:
+                    description: Tag is the image's tag.
+                    type: string
+                type: object
             type: object
         type: object
     served: true

docs/api/v1beta2/image-reflector.md

@@ -131,6 +131,19 @@ rules. If no rules are provided, all the tags from the repository will be
 ordered and compared.</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>digestReflectionPolicy</code><br>
+<em>
+<a href="#image.toolkit.fluxcd.io/v1beta2.ReflectionPolicy">
+ReflectionPolicy
+</a>
+</em>
+</td>
+<td>
+<p>DigestReflectionPolicy governs the setting of the <code>.status.latestRef.digest</code> field.</p>
+</td>
+</tr>
 </table>
 </td>
 </tr>
@@ -277,6 +290,19 @@ rules. If no rules are provided, all the tags from the repository will be
 ordered and compared.</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>digestReflectionPolicy</code><br>
+<em>
+<a href="#image.toolkit.fluxcd.io/v1beta2.ReflectionPolicy">
+ReflectionPolicy
+</a>
+</em>
+</td>
+<td>
+<p>DigestReflectionPolicy governs the setting of the <code>.status.latestRef.digest</code> field.</p>
+</td>
+</tr>
 </tbody>
 </table>
 </div>
@@ -308,7 +334,8 @@ string
 <td>
 <p>LatestImage gives the first in the list of images scanned by
 the image repository, when filtered and ordered according to
-the policy.</p>
+the policy.
+Deprecated: Replaced by the composite &ldquo;latestRef&rdquo; field.</p>
 </td>
 </tr>
 <tr>
@@ -321,6 +348,37 @@ string
 <td>
 <em>(Optional)</em>
 <p>ObservedPreviousImage is the observed previous LatestImage. It is used
+to keep track of the previous and current images.
+Deprecated: Replaced by the composite &ldquo;observedPreviousRef&rdquo; field.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>latestRef</code><br>
+<em>
+<a href="#image.toolkit.fluxcd.io/v1beta2.ImageRef">
+ImageRef
+</a>
+</em>
+</td>
+<td>
+<p>LatestRef gives the first in the list of images scanned by
+the image repository, when filtered and ordered according
+to the policy.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>observedPreviousRef</code><br>
+<em>
+<a href="#image.toolkit.fluxcd.io/v1beta2.ImageRef">
+ImageRef
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>ObservedPreviousRef is the observed previous LatestRef. It is used
 to keep track of the previous and current images.</p>
 </td>
 </tr>
@@ -352,6 +410,61 @@ int64
 </table>
 </div>
 </div>
+<h3 id="image.toolkit.fluxcd.io/v1beta2.ImageRef">ImageRef
+</h3>
+<p>
+(<em>Appears on:</em>
+<a href="#image.toolkit.fluxcd.io/v1beta2.ImagePolicyStatus">ImagePolicyStatus</a>)
+</p>
+<p>ImageRef represents an image reference.</p>
+<div class="md-typeset__scrollwrap">
+<div class="md-typeset__table">
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<code>image</code><br>
+<em>
+string
+</em>
+</td>
+<td>
+<p>Name is the bare image&rsquo;s name.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>tag</code><br>
+<em>
+string
+</em>
+</td>
+<td>
+<p>Tag is the image&rsquo;s tag.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>digest</code><br>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Digest is the image&rsquo;s digest.</p>
+</td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
 <h3 id="image.toolkit.fluxcd.io/v1beta2.ImageRepository">ImageRepository
 </h3>
 <p>ImageRepository is the Schema for the imagerepositories API</p>
@@ -872,6 +985,13 @@ would select 0.</p>
 </table>
 </div>
 </div>
+<h3 id="image.toolkit.fluxcd.io/v1beta2.ReflectionPolicy">ReflectionPolicy
+(<code>string</code> alias)</h3>
+<p>
+(<em>Appears on:</em>
+<a href="#image.toolkit.fluxcd.io/v1beta2.ImagePolicySpec">ImagePolicySpec</a>)
+</p>
+<p>ReflectionPolicy describes a policy for if/when to reflect a value from the registry in a certain resource field.</p>
 <h3 id="image.toolkit.fluxcd.io/v1beta2.ScanResult">ScanResult
 </h3>
 <p>