CRD Reference

All resources are cluster-scoped under drop.corewire.io/v1alpha1.

Quick Example

apiVersion: drop.corewire.io/v1alpha1
kind: CachedImage
metadata:
  name: nginx
spec:
  image: docker.io/library/nginx
  tag: latest
  nodeSelector:
    kubernetes.io/arch: amd64

CachedImage

CachedImage ensures a single container image is pre-cached on cluster nodes.

Controller: internal/controller/cachedimage_controller.go

Spec

Field	Type	Required	Default	Description
`image`	`string`	Yes	—	Image is the fully qualified image reference (registry/repository).
`tag`	`string`	No	—	Tag to pull. Mutually exclusive with Digest.
`digest`	`string`	No	—	Digest to pull (immutable reference). Mutually exclusive with Tag.
`imagePullPolicy`	`corev1.PullPolicy`	No	Always	ImagePullPolicy controls when kubelet pulls the image. Defaults to Always (checks upstream digest, only downloads if changed). Set to IfNotPresent to skip the registry check when the tag already exists locally. (`Always` \| `IfNotPresent` \| `Never`)
`imagePullSecrets`	`[]corev1.LocalObjectReference`	No	—	ImagePullSecrets are references to secrets for pulling from private registries.
`nodeSelector`	`map[string]string`	No	—	NodeSelector restricts which nodes to cache the image on.
`tolerations`	`[]corev1.Toleration`	No	—	Tolerations allow targeting tainted nodes.
`priority`	`*int32`	No	—	Priority is a pull ordering hint (lower values pulled first).
`policyRef`	`*PolicyReference`	No	—	PolicyRef references a PullPolicy for pacing controls.

Status

Field	Type	Description
`observedGeneration`	`int64`	ObservedGeneration is the last generation reconciled.
`phase`	`string`	Phase summarizes the overall state.
`ready`	`string`	Ready is a human-readable “nodesReady/nodesTargeted” fraction for display.
`resolvedDigest`	`string`	ResolvedDigest is the sha256 digest of the image as reported by the container runtime after pull.
`nodesTargeted`	`int32`	NodesTargeted is the number of nodes that should have this image.
`nodesReady`	`int32`	NodesReady is the number of nodes that have successfully pulled the image.
`nodesPulling`	`int32`	NodesPulling is the number of nodes currently pulling the image.
`cachedNodes`	`[]string`	CachedNodes is the list of node names that have successfully cached the image.
`consecutiveFailures`	`int32`	ConsecutiveFailures counts sequential reconcile failures for backoff calculation.
`lastPulledAt`	`*metav1.Time`	LastPulledAt is the timestamp of the most recent successful pull.
`lastAttemptedAt`	`*metav1.Time`	LastAttemptedAt is the timestamp of the most recent pull attempt (success or failure).
`conditions`	`[]metav1.Condition`	Conditions represent the latest available observations. Condition types: Ready, PullProgress.

CachedImageSet

CachedImageSet manages a group of images to cache, optionally backed by a DiscoveryPolicy.

Controller: internal/controller/cachedimageset_controller.go

Spec

Field	Type	Required	Default	Description
`policyRef`	`*PolicyReference`	No	—	PolicyRef references a PullPolicy for pacing controls.
`discoveryPolicyRef`	`*DiscoveryPolicyReference`	No	—	DiscoveryPolicyRef references a DiscoveryPolicy for dynamic image lists.
`imagePullPolicy`	`corev1.PullPolicy`	No	Always	ImagePullPolicy controls when kubelet pulls the image (propagated to children). (`Always` \| `IfNotPresent` \| `Never`)
`imagePullSecrets`	`[]corev1.LocalObjectReference`	No	—	ImagePullSecrets are references to secrets for pulling from private registries (propagated to children).
`nodeSelector`	`map[string]string`	No	—	NodeSelector restricts which nodes to cache images on (propagated to children).
`tolerations`	`[]corev1.Toleration`	No	—	Tolerations allow targeting tainted nodes (propagated to children).
`images`	`[]ImageEntry`	No	—	Images is a static list of images to cache.

Status

Field	Type	Description
`observedGeneration`	`int64`	ObservedGeneration is the last generation reconciled.
`phase`	`string`	Phase summarizes the overall state.
`imagesManaged`	`int32`	ImagesManaged is the number of CachedImage children managed by this set.
`imagesReady`	`int32`	ImagesReady is the number of children in Ready phase.
`conditions`	`[]metav1.Condition`	Conditions represent the latest available observations.

DiscoveryPolicy

DiscoveryPolicy automatically discovers images from registries or Prometheus metrics.

Controller: internal/controller/discoverypolicy_controller.go

Spec

Field	Type	Required	Default	Description
`sources`	`[]DiscoverySource`	Yes	—	Sources is the list of discovery backends to query.
`imageFilter`	`string`	No	—	ImageFilter is a regex to filter discovered images.
`syncInterval`	`metav1.Duration`	No	30m	SyncInterval is how often to re-query sources.
`maxImages`	`int32`	No	50	MaxImages caps the number of discovered images.

Status

Field	Type	Description
`lastSyncTime`	`*metav1.Time`	LastSyncTime is the timestamp of the last successful sync.
`discoveredImages`	`[]DiscoveredImage`	DiscoveredImages is the list of discovered images from all sources.
`imageCount`	`int32`	ImageCount is the number of discovered images.
`sourceCount`	`int32`	SourceCount is the number of configured sources.
`conditions`	`[]metav1.Condition`	Conditions represent the latest available observations.

PullPolicy

PullPolicy controls the pacing and retry behavior for image pulls across cluster nodes. It is a configuration-only resource with no status.

Spec

Field	Type	Required	Default	Description
`maxConcurrentNodes`	`int32`	No	1	MaxConcurrentNodes is the max nodes pulling simultaneously for this policy.
`minDelayBetweenPulls`	`metav1.Duration`	No	10s	MinDelayBetweenPulls is the minimum time between starting pulls on different nodes.
`failureBackoff`	`*BackoffConfig`	No	—	FailureBackoff configures retry delays on pull failures.
`repullInterval`	`*metav1.Duration`	No	—	RepullInterval is how often to re-pull cached images. Zero or unset means never re-pull.
`nodeSelector`	`map[string]string`	No	—	NodeSelector scopes this policy to a specific node pool.
`tolerations`	`[]corev1.Toleration`	No	—	Tolerations match tainted nodes in the pool.

Helper Types

BackoffConfig

BackoffConfig defines retry backoff behavior.

Field	Type	Required	Default	Description
`initial`	`metav1.Duration`	No	30s	Initial delay before first retry.
`max`	`metav1.Duration`	No	5m	Max delay cap for exponential backoff.

DiscoveredImage

DiscoveredImage represents a single discovered image with metadata.

Field	Type	Required	Default	Description
`image`	`string`	Yes	—	Image is the fully qualified image reference.
`score`	`int64`	Yes	—	Score is the ranking score from the source (higher = more relevant).
`source`	`string`	Yes	—	Source identifies which discovery source produced this image.

DiscoveryPolicyReference

DiscoveryPolicyReference is a reference to a DiscoveryPolicy resource.

Field	Type	Required	Default	Description
`name`	`string`	Yes	—	Name of the DiscoveryPolicy resource.

DiscoverySource

DiscoverySource defines a single discovery backend.

Field	Type	Required	Default	Description
`type`	`string`	Yes	—	Type identifies the backend.
`prometheus`	`*PrometheusSource`	No	—	Prometheus config (when type=prometheus).
`registry`	`*RegistrySource`	No	—	Registry config (when type=registry).
`secretRef`	`*corev1.LocalObjectReference`	No	—	SecretRef references a Secret for auth/TLS for this source.

ImageEntry

ImageEntry defines a single image to include in a set.

Field	Type	Required	Default	Description
`image`	`string`	Yes	—	Image is the fully qualified image reference (registry/repository).
`tag`	`string`	No	—	Tag to pull.
`digest`	`string`	No	—	Digest to pull.

PolicyReference

PolicyReference is a reference to a PullPolicy resource.

Field	Type	Required	Default	Description
`name`	`string`	Yes	—	Name of the PullPolicy resource.

PrometheusSource

PrometheusSource defines Prometheus query configuration.

Field	Type	Required	Default	Description
`endpoint`	`string`	Yes	—	Endpoint is the Prometheus API URL.
`query`	`string`	Yes	—	Query is the PromQL query that must return an ‘image’ label.
`lookback`	`*metav1.Duration`	No	—	Lookback is the time window to aggregate over (e.g. “7d”, “24h”). When set, uses query_range and sums values to rank by total usage. When unset, uses an instant query (point-in-time).
`step`	`string`	No	5m	Step is the query resolution step for range queries.

RegistrySource

RegistrySource defines OCI registry tag listing configuration.

Field	Type	Required	Default	Description
`url`	`string`	Yes	—	URL is the registry base URL.
`repositories`	`[]string`	Yes	—	Repositories is the list of repositories to query.
`tagFilter`	`string`	No	—	TagFilter is a regex to filter tags.
`topX`	`int32`	No	—	TopX limits the number of tags to fetch per repository.
`imageTemplate`	`string`	No	—	ImageTemplate is a Go text/template for constructing the full image reference. Available variables: .Registry, .Repository, .Tag

Last updated on May 26, 2026

Metrics