feat(controller): per-pod Executor status (Gatekeeper-style) for multi-replica safety

api/v2alpha1/executor_types.go

@@ -103,6 +103,15 @@ type ExecutorStatus struct {
 	// Truncated error message if the message is too long.
 	// +optional
 	BriefError string `json:"briefError,omitempty"`
+
+	// ByPod reports the status observed by each individual Ratify pod (replica).
+	// It is aggregated from the per-pod ExecutorPodStatus objects and lets an
+	// operator tell, for example, that "2 of 5 replicas are unhealthy" instead
+	// of the top-level fields flapping under last-writer-wins.
+	// +optional
+	// +listType=map
+	// +listMapKey=id
+	ByPod []PodStatusEntry `json:"byPod,omitempty"`
 }
 
 // +kubebuilder:object:root=true

api/v2alpha1/executorpodstatus_types.go

@@ -0,0 +1,83 @@
+/*
+Copyright The Ratify Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v2alpha1
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// PodStatusEntry captures the health a single Ratify pod (replica) reports for
+// an Executor resource. It is the unit that is written by each pod into its own
+// ExecutorPodStatus object and later aggregated into Executor.status.byPod.
+type PodStatusEntry struct {
+	// ID is the name of the pod that produced this status entry. Required.
+	ID string `json:"id"`
+
+	// ObservedGeneration is the metadata.generation of the Executor that this
+	// entry was produced for.
+	// +optional
+	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+
+	// Succeeded indicates whether the reporting pod successfully built the
+	// executor from the Executor spec. Required.
+	Succeeded bool `json:"succeeded"`
+
+	// Error is the error message if the reporting pod failed to build the
+	// executor.
+	// +optional
+	Error string `json:"error,omitempty"`
+
+	// BriefError is a truncated error message when Error is too long to be
+	// displayed conveniently.
+	// +optional
+	BriefError string `json:"briefError,omitempty"`
+
+	// LastTransitionTime is the time the reporting pod last updated this entry.
+	// +optional
+	LastTransitionTime *metav1.Time `json:"lastTransitionTime,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+// +kubebuilder:storageversion
+
+// ExecutorPodStatus is the per-pod status of an Executor. Each Ratify replica
+// owns exactly one ExecutorPodStatus object per Executor (the object name embeds
+// the pod identity), so no two pods ever write the same object and there are no
+// write conflicts. The object lives in the pod's own namespace and carries an
+// owner reference to the pod, so it is garbage-collected automatically when the
+// pod is deleted. (It is namespaced rather than cluster-scoped because a
+// cluster-scoped object cannot be owned by a namespaced pod.)
+type ExecutorPodStatus struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Status PodStatusEntry `json:"status,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+
+// ExecutorPodStatusList contains a list of ExecutorPodStatus.
+type ExecutorPodStatusList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []ExecutorPodStatus `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&ExecutorPodStatus{}, &ExecutorPodStatusList{})
+}

config/crd/bases/config.ratify.dev_executorpodstatuses.yaml

@@ -0,0 +1,90 @@
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  annotations:
+    controller-gen.kubebuilder.io/version: v0.18.0
+  name: executorpodstatuses.config.ratify.dev
+spec:
+  group: config.ratify.dev
+  names:
+    kind: ExecutorPodStatus
+    listKind: ExecutorPodStatusList
+    plural: executorpodstatuses
+    singular: executorpodstatus
+  scope: Namespaced
+  versions:
+  - name: v2alpha1
+    schema:
+      openAPIV3Schema:
+        description: |-
+          ExecutorPodStatus is the per-pod status of an Executor. Each Ratify replica
+          owns exactly one ExecutorPodStatus object per Executor (the object name embeds
+          the pod identity), so no two pods ever write the same object and there are no
+          write conflicts. The object lives in the pod's own namespace and carries an
+          owner reference to the pod, so it is garbage-collected automatically when the
+          pod is deleted. (It is namespaced rather than cluster-scoped because a
+          cluster-scoped object cannot be owned by a namespaced pod.)
+        properties:
+          apiVersion:
+            description: |-
+              APIVersion defines the versioned schema of this representation of an object.
+              Servers should convert recognized schemas to the latest internal value, and
+              may reject unrecognized values.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
+            type: string
+          kind:
+            description: |-
+              Kind is a string value representing the REST resource this object represents.
+              Servers may infer this from the endpoint the client submits requests to.
+              Cannot be updated.
+              In CamelCase.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
+            type: string
+          metadata:
+            type: object
+          status:
+            description: |-
+              PodStatusEntry captures the health a single Ratify pod (replica) reports for
+              an Executor resource. It is the unit that is written by each pod into its own
+              ExecutorPodStatus object and later aggregated into Executor.status.byPod.
+            properties:
+              briefError:
+                description: |-
+                  BriefError is a truncated error message when Error is too long to be
+                  displayed conveniently.
+                type: string
+              error:
+                description: |-
+                  Error is the error message if the reporting pod failed to build the
+                  executor.
+                type: string
+              id:
+                description: ID is the name of the pod that produced this status entry.
+                  Required.
+                type: string
+              lastTransitionTime:
+                description: LastTransitionTime is the time the reporting pod last
+                  updated this entry.
+                format: date-time
+                type: string
+              observedGeneration:
+                description: |-
+                  ObservedGeneration is the metadata.generation of the Executor that this
+                  entry was produced for.
+                format: int64
+                type: integer
+              succeeded:
+                description: |-
+                  Succeeded indicates whether the reporting pod successfully built the
+                  executor from the Executor spec. Required.
+                type: boolean
+            required:
+            - id
+            - succeeded
+            type: object
+        type: object
+    served: true
+    storage: true
+    subresources:
+      status: {}

config/crd/bases/config.ratify.dev_executors.yaml

@@ -139,6 +139,56 @@ spec:
               briefError:
                 description: Truncated error message if the message is too long.
                 type: string
+              byPod:
+                description: |-
+                  ByPod reports the status observed by each individual Ratify pod (replica).
+                  It is aggregated from the per-pod ExecutorPodStatus objects and lets an
+                  operator tell, for example, that "2 of 5 replicas are unhealthy" instead
+                  of the top-level fields flapping under last-writer-wins.
+                items:
+                  description: |-
+                    PodStatusEntry captures the health a single Ratify pod (replica) reports for
+                    an Executor resource. It is the unit that is written by each pod into its own
+                    ExecutorPodStatus object and later aggregated into Executor.status.byPod.
+                  properties:
+                    briefError:
+                      description: |-
+                        BriefError is a truncated error message when Error is too long to be
+                        displayed conveniently.
+                      type: string
+                    error:
+                      description: |-
+                        Error is the error message if the reporting pod failed to build the
+                        executor.
+                      type: string
+                    id:
+                      description: ID is the name of the pod that produced this status
+                        entry. Required.
+                      type: string
+                    lastTransitionTime:
+                      description: LastTransitionTime is the time the reporting pod
+                        last updated this entry.
+                      format: date-time
+                      type: string
+                    observedGeneration:
+                      description: |-
+                        ObservedGeneration is the metadata.generation of the Executor that this
+                        entry was produced for.
+                      format: int64
+                      type: integer
+                    succeeded:
+                      description: |-
+                        Succeeded indicates whether the reporting pod successfully built the
+                        executor from the Executor spec. Required.
+                      type: boolean
+                  required:
+                  - id
+                  - succeeded
+                  type: object
+                type: array
+                x-kubernetes-list-map-keys:
+                - id
+                x-kubernetes-list-type: map
               error:
                 description: Error is the error message if the executor failed to
                   start.

config/crd/kustomization.yaml

@@ -3,6 +3,7 @@
 # It should be run by config/default
 resources:
 - bases/config.ratify.dev_executors.yaml
+- bases/config.ratify.dev_executorpodstatuses.yaml
 # +kubebuilder:scaffold:crdkustomizeresource
 
 patches:

config/manager/manager.yaml

@@ -65,6 +65,15 @@ spec:
           - --health-probe-bind-address=:8081
         image: controller:latest
         name: manager
+        env:
+        - name: POD_NAME
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.name
+        - name: RATIFY_NAMESPACE
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.namespace
         ports: []
         securityContext:
           allowPrivilegeEscalation: false