fix: require explicit image tag or digest instead of defaulting to :latest (#54)

Drops the `+kubebuilder:default="latest"` from Instance.spec.image.tag and
adds a CEL validation rule requiring at least one of `tag` or `digest` to be
set. Removes the matching Go fallbacks in the StatefulSet builder and the
auto-update reconciler.

Fresh installs that relied on the default now fail admission with a clear
message instead of silently pulling `ghcr.io/paperclipinc/paperclip:latest`,
which ships a broken export map and crashes on startup with
ERR_MODULE_NOT_FOUND.

Samples and the envtest suite are updated to pin an explicit tag.

Fixes #52

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: stubbi

api/v1alpha1/paperclipinstance_types.go

@@ -135,14 +135,16 @@ type InstanceSpec struct {
 }
 
 // ImageSpec configures the container image.
+// +kubebuilder:validation:XValidation:rule="size(self.tag) > 0 || size(self.digest) > 0",message="spec.image: one of tag or digest must be set (pinning to :latest is not supported, pick a specific upstream release tag)"
 type ImageSpec struct {
 	// Repository is the container image repository.
 	// +kubebuilder:default="ghcr.io/paperclipinc/paperclip"
 	// +optional
 	Repository string `json:"repository,omitempty"`
 
-	// Tag is the container image tag.
-	// +kubebuilder:default="latest"
+	// Tag is the container image tag. Either tag or digest must be set; there is
+	// no default, because pinning to a mutable tag like :latest can silently pull
+	// a broken upstream build.
 	// +optional
 	Tag string `json:"tag,omitempty"`
 

charts/paperclip-operator/templates/crds/paperclip.inc_instances.yaml

@@ -3998,10 +3998,17 @@ spec:
                     description: Repository is the container image repository.
                     type: string
                   tag:
-                    default: latest
-                    description: Tag is the container image tag.
+                    description: |-
+                      Tag is the container image tag. Either tag or digest must be set; there is
+                      no default, because pinning to a mutable tag like :latest can silently pull
+                      a broken upstream build.
                     type: string
                 type: object
+                x-kubernetes-validations:
+                - message: 'spec.image: one of tag or digest must be set (pinning
+                    to :latest is not supported, pick a specific upstream release
+                    tag)'
+                  rule: size(self.tag) > 0 || size(self.digest) > 0
               initContainers:
                 description: InitContainers specifies additional init containers.
                 items:

config/crd/bases/paperclip.inc_instances.yaml

@@ -3992,10 +3992,17 @@ spec:
                     description: Repository is the container image repository.
                     type: string
                   tag:
-                    default: latest
-                    description: Tag is the container image tag.
+                    description: |-
+                      Tag is the container image tag. Either tag or digest must be set; there is
+                      no default, because pinning to a mutable tag like :latest can silently pull
+                      a broken upstream build.
                     type: string
                 type: object
+                x-kubernetes-validations:
+                - message: 'spec.image: one of tag or digest must be set (pinning
+                    to :latest is not supported, pick a specific upstream release
+                    tag)'
+                  rule: size(self.tag) > 0 || size(self.digest) > 0
               initContainers:
                 description: InitContainers specifies additional init containers.
                 items:

config/samples/paperclip_v1alpha1_instance.yaml

@@ -6,7 +6,10 @@ metadata:
 spec:
   image:
     repository: ghcr.io/paperclipinc/paperclip
-    tag: latest
+    # Pick a specific upstream release tag. The operator rejects Instances
+    # without a tag (or digest), since :latest can silently pull a broken build.
+    # See the tags list at https://github.com/paperclipinc/paperclip/pkgs/container/paperclip
+    tag: "2026.0403"
 
   deployment:
     mode: authenticated

config/samples/paperclip_v1alpha1_instance_public.yaml

@@ -6,7 +6,10 @@ metadata:
 spec:
   image:
     repository: ghcr.io/paperclipinc/paperclip
-    tag: latest
+    # Pick a specific upstream release tag. The operator rejects Instances
+    # without a tag (or digest), since :latest can silently pull a broken build.
+    # See the tags list at https://github.com/paperclipinc/paperclip/pkgs/container/paperclip
+    tag: "2026.0403"
 
   deployment:
     mode: authenticated

internal/controller/instance_controller.go

@@ -1105,7 +1105,9 @@ func (r *InstanceReconciler) reconcileAutoUpdate(ctx context.Context, instance *
 	}
 	tag := instance.Spec.Image.Tag
 	if tag == "" {
-		tag = "latest"
+		instance.Status.AutoUpdate.LastError = "auto-update requires spec.image.tag to be set; cannot poll a digest-pinned image"
+		instance.Status.AutoUpdate.LastCheckTime = &now
+		return ctrl.Result{RequeueAfter: interval}
 	}
 
 	digest, err := r.RegistryClient.ResolveDigest(ctx, repo, tag, dockerConfigJSON)

internal/controller/instance_controller_test.go

@@ -51,7 +51,11 @@ var _ = Describe("Instance Controller", func() {
 						Name:      resourceName,
 						Namespace: "default",
 					},
-					// TODO(user): Specify other spec details if needed.
+					Spec: paperclipv1alpha1.InstanceSpec{
+						Image: paperclipv1alpha1.ImageSpec{
+							Tag: "v1.0.0",
+						},
+					},
 				}
 				Expect(k8sClient.Create(ctx, resource)).To(Succeed())
 			}

internal/resources/statefulset.go

@@ -849,11 +849,7 @@ func containerImage(instance *paperclipv1alpha1.Instance) string {
 		return repo + "@" + instance.Spec.Image.Digest
 	}
 
-	tag := instance.Spec.Image.Tag
-	if tag == "" {
-		tag = "latest"
-	}
-	return repo + ":" + tag
+	return repo + ":" + instance.Spec.Image.Tag
 }
 
 func imagePullPolicy(instance *paperclipv1alpha1.Instance) corev1.PullPolicy {