kubelet: add the ImagePullManager interface

Author: stlaz

pkg/kubelet/images/types.go

@@ -19,9 +19,11 @@ package images
 import (
 	"context"
 	"errors"
+	"time"
 
 	v1 "k8s.io/api/core/v1"
 	runtimeapi "k8s.io/cri-api/pkg/apis/runtime/v1"
+	kubeletconfiginternal "k8s.io/kubernetes/pkg/kubelet/apis/config"
 )
 
 var (
@@ -52,3 +54,52 @@ type ImageManager interface {
 
 	// TODO(ronl): consolidating image managing and deleting operation in this interface
 }
+
+// ImagePullManager keeps the state of images that were pulled and which are
+// currently still being pulled.
+// It should keep an internal state of images currently being pulled by the kubelet
+// in order to determine whether to destroy a "pulling" record should an image
+// pull fail.
+type ImagePullManager interface {
+	// RecordPullIntent records an intent to pull an image and should be called
+	// before a pull of the image occurs.
+	//
+	// RecordPullIntent() should be called before every image pull. Each call of
+	// RecordPullIntent() must match exactly one call of RecordImagePulled()/RecordImagePullFailed().
+	//
+	// `image` is the content of the pod's container `image` field.
+	RecordPullIntent(image string) error
+	// RecordImagePulled writes a record of an image being successfully pulled
+	// with ImagePullCredentials.
+	//
+	// `credentials` must not be nil and must contain either exactly one Kubernetes
+	// Secret coordinates in the `.KubernetesSecrets` slice or set `.NodePodsAccessible`
+	// to `true`.
+	//
+	// `image` is the content of the pod's container `image` field.
+	RecordImagePulled(image, imageRef string, credentials *kubeletconfiginternal.ImagePullCredentials)
+	// RecordImagePullFailed should be called if an image failed to pull.
+	//
+	// Internally, it lowers its reference counter for the given image. If the
+	// counter reaches zero, the pull intent record for the image is removed.
+	//
+	// `image` is the content of the pod's container `image` field.
+	RecordImagePullFailed(image string)
+	// MustAttemptImagePull evaluates the policy for the image specified in
+	// `image` and if the policy demands verification, it checks the internal
+	// cache to see if there's a record of pulling the image with the presented
+	// set of credentials or if the image can be accessed by any of the node's pods.
+	//
+	// Returns true if the policy demands verification and no record of the pull
+	// was found in the cache.
+	//
+	// `image` is the content of the pod's container `image` field.
+	MustAttemptImagePull(image, imageRef string, credentials []kubeletconfiginternal.ImagePullSecret) bool
+	// PruneUnknownRecords deletes all of the cache ImagePulledRecords for each of the images
+	// whose imageRef does not appear in the `imageList` iff such an record was last updated
+	// _before_ the `until` timestamp.
+	//
+	// This method is only expected to be called by the kubelet's image garbage collector.
+	// `until` is a timestamp created _before_ the `imageList` was requested from the CRI.
+	PruneUnknownRecords(imageList []string, until time.Time)
+}