Stage 4: TerdutAlertSource

Covers webhook Secret generation/ownership (DESIGN.md §4.5, §7), the
WebhookSecretLost fail-closed condition, and the kind-change
delete-and-recreate rotation path.

Idempotent-create here is deliberately neither adopt-on-409
(Team/service-account) nor list-and-match-by-name (TerdutDeadmanSwitch):
terdut-server shows the webhook key exactly once, at creation, and never
again, so no server-side lookup could ever recover it after a crash.
Instead the generated webhook Secret itself -- written immediately after
the POST, before status is ever touched -- is this CR's only durable
record that a create already succeeded; found with status.integrationID
still unset on a later reconcile, it's read back directly rather than
POSTing a second, orphaned integration. Found missing with
status.integrationID *set* instead, that's the already-designed
WebhookSecretLost case: fail closed, not self-healed, since the key is
genuinely gone and recreating it would rotate a live webhook URL with no
spec change to explain why.

Renaming (PATCH) never touches the key, so it's applied unconditionally
every reconcile, same as the escalation policy's whole-policy PUT. A
spec.kind change is the one case with no in-place update verb at all:
DELETE the old integration, delete the stale webhook Secret, then run the
same create path fresh -- fires a Warning event since this breaks whatever
still sends to the old URL.

Also: fakeTerdutServer grows POST/PATCH/DELETE .../integrations routes
behind a new handleIntegrationSubPath, split out of handleTeamSubPath to
stay under gocyclo's threshold; three goconst-flagged test literals
("does-not-exist", "unready") and one unparam-flagged test helper
parameter (bootstrapReadyTerdutServer's always-"default" namespace) get
shared/removed now that a fourth same-shaped caller made the repetition
concrete enough for the linter to flag.

DESIGN.md §13 gains one honest gap found while grounding this stage, not
introduced by it: no child CRD specially detects a mid-life teamRef
change; all three always resolve spec.teamRef fresh and trust the
already-stored server-side id remains valid there.

make fmt lint test build all clean; internal/controller envtest coverage
holds at 71.6%.

config/crd/bases/terdut.ryuvia.com_terdutalertsources.yaml

@@ -0,0 +1,194 @@
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  annotations:
+    controller-gen.kubebuilder.io/version: v0.22.0
+  name: terdutalertsources.terdut.ryuvia.com
+spec:
+  group: terdut.ryuvia.com
+  names:
+    kind: TerdutAlertSource
+    listKind: TerdutAlertSourceList
+    plural: terdutalertsources
+    singular: terdutalertsource
+  scope: Namespaced
+  versions:
+  - additionalPrinterColumns:
+    - jsonPath: .spec.teamRef.name
+      name: Team
+      type: string
+    - jsonPath: .status.integrationID
+      name: IntegrationID
+      type: integer
+    - jsonPath: .status.conditions[?(@.type=="Ready")].status
+      name: Ready
+      type: string
+    - jsonPath: .status.conditions[?(@.type=="Ready")].reason
+      name: Reason
+      type: string
+    name: v1alpha1
+    schema:
+      openAPIV3Schema:
+        description: TerdutAlertSource is the Schema for the terdutalertsources API
+        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
+          spec:
+            description: spec defines the desired state of TerdutAlertSource
+            properties:
+              kind:
+                default: alertmanager
+                description: |-
+                  kind is the alert source type. Only "alertmanager" is supported
+                  today, mirroring terdut-server's own CHECK constraint on
+                  integrations.kind (internal/db/migrations/003_teams.sql) --
+                  confirmed against source, not assumed. Changing it after the
+                  integration already exists rotates the webhook key (DESIGN.md §5's
+                  reconciliation table): the old one is deleted and a fresh one
+                  created, which breaks whatever sends to the old URL until the new
+                  Secret is picked up.
+                enum:
+                - alertmanager
+                type: string
+              name:
+                description: |-
+                  name is this source's own display name server-side -- distinct from
+                  this object's own metadata.name. POST
+                  /api/teams/{teamID}/integrations {"name": ...} at creation, and what
+                  PATCH renames thereafter; renaming never rotates the webhook key.
+                minLength: 1
+                type: string
+              teamRef:
+                description: |-
+                  TerdutTeamRef names the TerdutTeam this resource belongs to. Always
+                  same-namespace as the CR itself (DESIGN.md §1: only TerdutTeam.spec.serverRef
+                  crosses namespaces in v1) -- no namespace field, unlike TerdutServerRef.
+                properties:
+                  name:
+                    minLength: 1
+                    type: string
+                required:
+                - name
+                type: object
+            required:
+            - name
+            - teamRef
+            type: object
+          status:
+            description: status defines the observed state of TerdutAlertSource
+            properties:
+              conditions:
+                items:
+                  description: Condition contains details for one aspect of the current
+                    state of this API Resource.
+                  properties:
+                    lastTransitionTime:
+                      description: |-
+                        lastTransitionTime is the last time the condition transitioned from one status to another.
+                        This should be when the underlying condition changed.  If that is not known, then using the time when the API field changed is acceptable.
+                      format: date-time
+                      type: string
+                    message:
+                      description: |-
+                        message is a human readable message indicating details about the transition.
+                        This may be an empty string.
+                      maxLength: 32768
+                      type: string
+                    observedGeneration:
+                      description: |-
+                        observedGeneration represents the .metadata.generation that the condition was set based upon.
+                        For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
+                        with respect to the current state of the instance.
+                      format: int64
+                      minimum: 0
+                      type: integer
+                    reason:
+                      description: |-
+                        reason contains a programmatic identifier indicating the reason for the condition's last transition.
+                        Producers of specific condition types may define expected values and meanings for this field,
+                        and whether the values are considered a guaranteed API.
+                        The value should be a CamelCase string.
+                        This field may not be empty.
+                      maxLength: 1024
+                      minLength: 1
+                      pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
+                      type: string
+                    status:
+                      description: status of the condition, one of True, False, Unknown.
+                      enum:
+                      - "True"
+                      - "False"
+                      - Unknown
+                      type: string
+                    type:
+                      description: type of condition in CamelCase or in foo.example.com/CamelCase.
+                      maxLength: 316
+                      pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
+                      type: string
+                  required:
+                  - lastTransitionTime
+                  - message
+                  - reason
+                  - status
+                  - type
+                  type: object
+                type: array
+                x-kubernetes-list-map-keys:
+                - type
+                x-kubernetes-list-type: map
+              integrationID:
+                description: integrationID is the server-side id.
+                format: int64
+                type: integer
+              lastAppliedKind:
+                description: |-
+                  lastAppliedKind is the kind the currently-live integration was
+                  actually created with -- compared against spec.kind on every
+                  reconcile to detect the one spec change that requires
+                  delete-and-recreate (DESIGN.md §5), since terdut-server's own API has
+                  no way to read a live integration's kind back for comparison.
+                type: string
+              observedGeneration:
+                format: int64
+                type: integer
+              webhookURLSecretRef:
+                description: |-
+                  webhookURLSecretRef names the generated Secret holding "url" and
+                  "key" -- the integration's webhook address and credential, shown by
+                  terdut-server's API exactly once, at creation (DESIGN.md §4.5), and
+                  never re-readable afterward, including from this status. Lives in
+                  this CR's own namespace with a plain OwnerReference (§7) -- unlike
+                  TerdutServer/TerdutTeam's credential Secrets, this one never crosses
+                  namespaces, so no finalizer cleanup is needed for it specifically.
+                properties:
+                  name:
+                    description: name is the Secret's name.
+                    minLength: 1
+                    type: string
+                required:
+                - name
+                type: object
+            type: object
+        required:
+        - spec
+        type: object
+    served: true
+    storage: true
+    subresources:
+      status: {}

config/crd/kustomization.yaml

@@ -6,6 +6,7 @@ resources:
 - bases/terdut.ryuvia.com_terdutteams.yaml
 - bases/terdut.ryuvia.com_terdutescalationrules.yaml
 - bases/terdut.ryuvia.com_terdutdeadmanswitches.yaml
+- bases/terdut.ryuvia.com_terdutalertsources.yaml
 # +kubebuilder:scaffold:crdkustomizeresource
 
 patches:

config/rbac/kustomization.yaml

@@ -22,6 +22,9 @@ resources:
 # default, aiding admins in cluster management. Those roles are
 # not used by the terdut-operator itself. You can comment the following lines
 # if you do not want those helpers be installed with your Project.
+- terdutalertsource_admin_role.yaml
+- terdutalertsource_editor_role.yaml
+- terdutalertsource_viewer_role.yaml
 - terdutdeadmanswitch_admin_role.yaml
 - terdutdeadmanswitch_editor_role.yaml
 - terdutdeadmanswitch_viewer_role.yaml

config/rbac/role.yaml

@@ -55,6 +55,7 @@ rules:
 - apiGroups:
   - terdut.ryuvia.com
   resources:
+  - terdutalertsources
   - terdutdeadmanswitches
   - terdutescalationrules
   - terdutservers
@@ -70,6 +71,7 @@ rules:
 - apiGroups:
   - terdut.ryuvia.com
   resources:
+  - terdutalertsources/finalizers
   - terdutdeadmanswitches/finalizers
   - terdutescalationrules/finalizers
   - terdutservers/finalizers
@@ -79,6 +81,7 @@ rules:
 - apiGroups:
   - terdut.ryuvia.com
   resources:
+  - terdutalertsources/status
   - terdutdeadmanswitches/status
   - terdutescalationrules/status
   - terdutservers/status

config/rbac/terdutalertsource_admin_role.yaml

@@ -0,0 +1,27 @@
+# This rule is not used by the project terdut-operator itself.
+# It is provided to allow the cluster admin to help manage permissions for users.
+#
+# Grants full permissions ('*') over terdut.ryuvia.com.
+# This role is intended for users authorized to modify roles and bindings within the cluster,
+# enabling them to delegate specific permissions to other users or groups as needed.
+
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  labels:
+    app.kubernetes.io/name: terdut-operator
+    app.kubernetes.io/managed-by: kustomize
+  name: terdutalertsource-admin-role
+rules:
+- apiGroups:
+  - terdut.ryuvia.com
+  resources:
+  - terdutalertsources
+  verbs:
+  - '*'
+- apiGroups:
+  - terdut.ryuvia.com
+  resources:
+  - terdutalertsources/status
+  verbs:
+  - get

config/rbac/terdutalertsource_editor_role.yaml

@@ -0,0 +1,33 @@
+# This rule is not used by the project terdut-operator itself.
+# It is provided to allow the cluster admin to help manage permissions for users.
+#
+# Grants permissions to create, update, and delete resources within the terdut.ryuvia.com.
+# This role is intended for users who need to manage these resources
+# but should not control RBAC or manage permissions for others.
+
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  labels:
+    app.kubernetes.io/name: terdut-operator
+    app.kubernetes.io/managed-by: kustomize
+  name: terdutalertsource-editor-role
+rules:
+- apiGroups:
+  - terdut.ryuvia.com
+  resources:
+  - terdutalertsources
+  verbs:
+  - create
+  - delete
+  - get
+  - list
+  - patch
+  - update
+  - watch
+- apiGroups:
+  - terdut.ryuvia.com
+  resources:
+  - terdutalertsources/status
+  verbs:
+  - get

config/rbac/terdutalertsource_viewer_role.yaml

@@ -0,0 +1,29 @@
+# This rule is not used by the project terdut-operator itself.
+# It is provided to allow the cluster admin to help manage permissions for users.
+#
+# Grants read-only access to terdut.ryuvia.com resources.
+# This role is intended for users who need visibility into these resources
+# without permissions to modify them. It is ideal for monitoring purposes and limited-access viewing.
+
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  labels:
+    app.kubernetes.io/name: terdut-operator
+    app.kubernetes.io/managed-by: kustomize
+  name: terdutalertsource-viewer-role
+rules:
+- apiGroups:
+  - terdut.ryuvia.com
+  resources:
+  - terdutalertsources
+  verbs:
+  - get
+  - list
+  - watch
+- apiGroups:
+  - terdut.ryuvia.com
+  resources:
+  - terdutalertsources/status
+  verbs:
+  - get

config/samples/kustomization.yaml

@@ -4,4 +4,5 @@ resources:
 - terdut_v1alpha1_terdutteam.yaml
 - terdut_v1alpha1_terdutescalationrule.yaml
 - terdut_v1alpha1_terdutdeadmanswitch.yaml
+- terdut_v1alpha1_terdutalertsource.yaml
 # +kubebuilder:scaffold:manifestskustomizesamples

config/samples/terdut_v1alpha1_terdutalertsource.yaml

@@ -0,0 +1,19 @@
+apiVersion: terdut.ryuvia.com/v1alpha1
+kind: TerdutAlertSource
+metadata:
+  labels:
+    app.kubernetes.io/name: terdut-operator
+    app.kubernetes.io/managed-by: kustomize
+  name: terdutalertsource-sample
+spec:
+  teamRef:
+    name: terdutteam-sample
+  # kind defaults to "alertmanager" -- the only value terdut-server
+  # supports today. Changing it after this object exists rotates the
+  # webhook key (DESIGN.md §5): the old integration is deleted and a new
+  # one created, which breaks whatever still sends to the old URL.
+  kind: alertmanager
+  # name is this source's own display name server-side, distinct from this
+  # object's own metadata.name above -- renaming it is safe and never
+  # rotates the key.
+  name: prod-alertmanager