Documentation
¶
Overview ¶
Package types provides shared types used across multiple Kubernaut CRDs. These types ensure API contract alignment between services.
Package types provides shared types used across multiple Kubernaut CRDs. These types ensure API contract alignment between services.
======================================== AUTHORITATIVE SOURCE - SINGLE SOURCE OF TRUTH ========================================
This file is the AUTHORITATIVE SOURCE for:
- EnrichmentResults schema
- DetectedLabels schema (8 fields)
- OwnerChainEntry schema
- KubernetesContext schema (lean, classification-focused)
- NamespaceContext schema
- WorkloadDetails schema
- BusinessClassification schema
All services MUST use these type definitions:
- SignalProcessing (populates at incident time via type aliases)
- AIAnalysis (passes to HolmesGPT-API via type aliases)
- HolmesGPT-API (uses for workflow filtering + LLM context)
- Data Storage (stores workflow metadata constraints)
Issue #113: KubernetesContext restructured to lean, classification-focused schema. Per-type workload fields (PodDetails, DeploymentDetails, etc.) replaced with generic WorkloadDetails (kind, name, labels, annotations) for Rego classification. Operational details (replicas, conditions, ports) removed -- LLM fetches on demand.
ADR-056: DetectedLabels and OwnerChain removed from EnrichmentResults. DetectedLabels are now computed by HAPI post-RCA (see PostRCAContext). OwnerChain is resolved by HAPI via get_resource_context tool (ADR-055).
Design Decision: DD-WORKFLOW-001 v2.2, DD-CONTRACT-002 See: docs/architecture/decisions/DD-WORKFLOW-001-mandatory-label-schema.md
+kubebuilder:object:generate=true
Index ¶
- func SharedDescriptionToOgen(d StructuredDescription) ogenclient.ActionTypeDescription
- type BusinessClassification
- type ConfigMapSummary
- type ContainerStatus
- type DeduplicationInfo
- type DeploymentDetails
- type DetectedLabels
- type EnrichmentResults
- type IngressRule
- type IngressSummary
- type KubernetesContext
- type NamespaceContext
- type NodeCondition
- type NodeDetails
- type OwnerChainEntry
- type PodDetails
- type ResourceList
- type ServicePort
- type ServiceSummary
- type StructuredDescription
- type WorkloadDetails
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SharedDescriptionToOgen ¶
func SharedDescriptionToOgen(d StructuredDescription) ogenclient.ActionTypeDescription
SharedDescriptionToOgen converts the canonical shared type to an ogen-generated ActionTypeDescription (snake_case REST wire format).
Types ¶
type BusinessClassification ¶
type BusinessClassification struct {
// Business unit owning the service (e.g., "payments", "platform")
BusinessUnit string `json:"businessUnit,omitempty"`
// Service owner team or individual
ServiceOwner string `json:"serviceOwner,omitempty"`
// Business criticality level: critical, high, medium, low
Criticality string `json:"criticality,omitempty"`
// SLA requirement tier: platinum, gold, silver, bronze
SLARequirement string `json:"slaRequirement,omitempty"`
}
BusinessClassification contains business context derived from SP categorization. BR-SP-002: Business Classification BR-SP-080: Business Unit Detection BR-SP-081: SLA Requirement Mapping
func (*BusinessClassification) DeepCopy ¶
func (in *BusinessClassification) DeepCopy() *BusinessClassification
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new BusinessClassification.
func (*BusinessClassification) DeepCopyInto ¶
func (in *BusinessClassification) DeepCopyInto(out *BusinessClassification)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type ConfigMapSummary ¶
type ConfigMapSummary struct {
Name string `json:"name"`
Keys []string `json:"keys"` // ConfigMap key names (not full data)
}
ConfigMapSummary contains ConfigMap targeting information.
func (*ConfigMapSummary) DeepCopy ¶
func (in *ConfigMapSummary) DeepCopy() *ConfigMapSummary
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ConfigMapSummary.
func (*ConfigMapSummary) DeepCopyInto ¶
func (in *ConfigMapSummary) DeepCopyInto(out *ConfigMapSummary)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type ContainerStatus ¶
type ContainerStatus struct {
Name string `json:"name"`
Image string `json:"image"`
Ready bool `json:"ready"`
RestartCount int32 `json:"restartCount"`
State string `json:"state"` // running, waiting, terminated
}
ContainerStatus contains container-level status.
func (*ContainerStatus) DeepCopy ¶
func (in *ContainerStatus) DeepCopy() *ContainerStatus
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ContainerStatus.
func (*ContainerStatus) DeepCopyInto ¶
func (in *ContainerStatus) DeepCopyInto(out *ContainerStatus)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type DeduplicationInfo ¶
type DeduplicationInfo struct {
// True if this signal is a duplicate of an active remediation
IsDuplicate bool `json:"isDuplicate,omitempty"`
// Timestamp when this signal fingerprint was first seen
// DD-GATEWAY-011: Made optional (moved to status.deduplication)
FirstOccurrence metav1.Time `json:"firstOccurrence,omitempty"`
// Timestamp when this signal fingerprint was last seen
// DD-GATEWAY-011: Made optional (moved to status.deduplication)
LastOccurrence metav1.Time `json:"lastOccurrence,omitempty"`
// Total count of occurrences of this signal
// DD-GATEWAY-011: Made optional (moved to status.deduplication)
OccurrenceCount int `json:"occurrenceCount,omitempty"`
// Optional correlation ID for grouping related signals
CorrelationID string `json:"correlationId,omitempty"`
// Reference to previous RemediationRequest CRD (if duplicate)
PreviousRemediationRequestRef string `json:"previousRemediationRequestRef,omitempty"`
}
DeduplicationInfo tracks duplicate signal suppression. Shared between RemediationRequest and SignalProcessing CRDs. See: RO team API Contract Alignment decision. DD-GATEWAY-011: Fields made optional for backward compatibility (Gateway Team Fix 2025-12-12)
func (*DeduplicationInfo) DeepCopy ¶
func (in *DeduplicationInfo) DeepCopy() *DeduplicationInfo
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new DeduplicationInfo.
func (*DeduplicationInfo) DeepCopyInto ¶
func (in *DeduplicationInfo) DeepCopyInto(out *DeduplicationInfo)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type DeploymentDetails ¶
type DeploymentDetails struct {
Name string `json:"name"`
Replicas int32 `json:"replicas"`
ReadyReplicas int32 `json:"readyReplicas"`
AvailableReplicas int32 `json:"availableReplicas"`
Strategy string `json:"strategy"` // RollingUpdate, Recreate
Labels map[string]string `json:"labels,omitempty"`
}
DeploymentDetails contains deployment-level context.
func (*DeploymentDetails) DeepCopy ¶
func (in *DeploymentDetails) DeepCopy() *DeploymentDetails
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new DeploymentDetails.
func (*DeploymentDetails) DeepCopyInto ¶
func (in *DeploymentDetails) DeepCopyInto(out *DeploymentDetails)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type DetectedLabels ¶
type DetectedLabels struct {
// ========================================
// DETECTION FAILURE TRACKING (DD-WORKFLOW-001 v2.2)
// ========================================
// Lists field names where detection QUERY failed (RBAC, timeout, network error).
// If a field is in this array, its value should be ignored.
// If empty/nil, all detections succeeded.
// Only accepts valid field names: gitOpsManaged, pdbProtected, hpaEnabled,
// stateful, helmManaged, networkIsolated, serviceMesh
// +kubebuilder:validation:items:Enum={gitOpsManaged,pdbProtected,hpaEnabled,stateful,helmManaged,networkIsolated,serviceMesh}
FailedDetections []string `json:"failedDetections,omitempty"`
// ========================================
// GITOPS MANAGEMENT
// ========================================
// True if namespace/deployment is managed by GitOps controller
// Detection: ArgoCD annotations, Flux labels
GitOpsManaged bool `json:"gitOpsManaged"`
// GitOps tool managing this resource
// +kubebuilder:validation:Enum=argocd;flux;""
GitOpsTool string `json:"gitOpsTool,omitempty"`
// ========================================
// WORKLOAD PROTECTION
// ========================================
// True if PodDisruptionBudget exists for this workload
PDBProtected bool `json:"pdbProtected"`
// True if HorizontalPodAutoscaler targets this workload
HPAEnabled bool `json:"hpaEnabled"`
// ========================================
// WORKLOAD CHARACTERISTICS
// ========================================
// True if StatefulSet or has PVCs attached
Stateful bool `json:"stateful"`
// True if managed by Helm (has helm.sh/chart label)
HelmManaged bool `json:"helmManaged"`
// ========================================
// SECURITY POSTURE
// ========================================
// True if NetworkPolicy exists in namespace
NetworkIsolated bool `json:"networkIsolated"`
// Service mesh if detected (from sidecar or namespace labels)
// +kubebuilder:validation:Enum=istio;linkerd;""
ServiceMesh string `json:"serviceMesh,omitempty"`
}
DetectedLabels contains auto-detected cluster characteristics. SignalProcessing populates these automatically from K8s resources. Used by HolmesGPT-API for:
- Workflow filtering (deterministic SQL WHERE)
- LLM context (natural language in prompt)
DETECTION FAILURE HANDLING (DD-WORKFLOW-001 v2.2): All fields are plain `bool` (NOT `*bool`). Uses `FailedDetections` array to track which fields had query failures (RBAC denied, timeout, network error).
IMPORTANT DISTINCTION:
- Resource doesn't exist (no PDB) → false value, NOT in FailedDetections
- Query failed (RBAC denied) → false value, field name IN FailedDetections
Consumers should check FailedDetections before trusting a false value.
func (*DetectedLabels) DeepCopy ¶
func (in *DetectedLabels) DeepCopy() *DetectedLabels
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new DetectedLabels.
func (*DetectedLabels) DeepCopyInto ¶
func (in *DetectedLabels) DeepCopyInto(out *DetectedLabels)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type EnrichmentResults ¶
type EnrichmentResults struct {
// Kubernetes resource context (classification-focused: namespace, workload labels, owner chain)
KubernetesContext *KubernetesContext `json:"kubernetesContext,omitempty"`
// Business classification from SP categorization phase
// BR-SP-002, BR-SP-080, BR-SP-081: Business unit, criticality, SLA
// Passed through to HolmesGPT-API for workflow filtering and Rego approval decisions
BusinessClassification *BusinessClassification `json:"businessClassification,omitempty"`
}
EnrichmentResults contains all enrichment data from SignalProcessing. DD-CONTRACT-002: Authoritative enrichment schema for all CRDs. Used by: SignalProcessing (output), AIAnalysis (input)
Issue #113: CustomLabels removed from EnrichmentResults. CustomLabels are now accessed via KubernetesContext.CustomLabels (single source, no redundancy).
func (*EnrichmentResults) DeepCopy ¶
func (in *EnrichmentResults) DeepCopy() *EnrichmentResults
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new EnrichmentResults.
func (*EnrichmentResults) DeepCopyInto ¶
func (in *EnrichmentResults) DeepCopyInto(out *EnrichmentResults)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type IngressRule ¶
IngressRule contains ingress rule configuration.
func (*IngressRule) DeepCopy ¶
func (in *IngressRule) DeepCopy() *IngressRule
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new IngressRule.
func (*IngressRule) DeepCopyInto ¶
func (in *IngressRule) DeepCopyInto(out *IngressRule)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type IngressSummary ¶
type IngressSummary struct {
Name string `json:"name"`
Hosts []string `json:"hosts"`
Rules []IngressRule `json:"rules,omitempty"`
}
IngressSummary contains ingress targeting information.
func (*IngressSummary) DeepCopy ¶
func (in *IngressSummary) DeepCopy() *IngressSummary
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new IngressSummary.
func (*IngressSummary) DeepCopyInto ¶
func (in *IngressSummary) DeepCopyInto(out *IngressSummary)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type KubernetesContext ¶
type KubernetesContext struct {
// Namespace context (nil for cluster-scoped resources like Node)
Namespace *NamespaceContext `json:"namespace,omitempty"`
// Target workload context (kind, name, labels, annotations)
Workload *WorkloadDetails `json:"workload,omitempty"`
// Owner chain from target to top-level controller
// DD-WORKFLOW-001 v1.8: Used for historical remediation context
OwnerChain []OwnerChainEntry `json:"ownerChain,omitempty"`
// Custom labels extracted via Rego policies (BR-SP-102)
// DD-WORKFLOW-001 v1.9: map[string][]string (subdomain -> list of values)
CustomLabels map[string][]string `json:"customLabels,omitempty"`
// DegradedMode indicates context was built with partial data
// DD-4: K8s Enrichment Failure Handling (target resource not found)
DegradedMode bool `json:"degradedMode,omitempty"`
}
KubernetesContext contains lean, classification-focused Kubernetes resource context. Issue #113: Restructured from per-type workload fields to generic WorkloadDetails. Only stores data needed for Rego classification (labels, annotations, ownership). Operational details (replicas, conditions, ports) are fetched by the LLM on demand.
DD-CONTRACT-002: Type-safe structured data shared across SP, AA, and HAPI.
func (*KubernetesContext) DeepCopy ¶
func (in *KubernetesContext) DeepCopy() *KubernetesContext
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new KubernetesContext.
func (*KubernetesContext) DeepCopyInto ¶
func (in *KubernetesContext) DeepCopyInto(out *KubernetesContext)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type NamespaceContext ¶
type NamespaceContext struct {
// Namespace name
Name string `json:"name"`
// Namespace labels (used by environment, priority, business classifiers)
Labels map[string]string `json:"labels,omitempty"`
// Namespace annotations (used by business classifier for kubernaut.ai/ labels)
Annotations map[string]string `json:"annotations,omitempty"`
}
NamespaceContext holds namespace details for classification. Nil for cluster-scoped signals (e.g., Node signals).
func (*NamespaceContext) DeepCopy ¶
func (in *NamespaceContext) DeepCopy() *NamespaceContext
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new NamespaceContext.
func (*NamespaceContext) DeepCopyInto ¶
func (in *NamespaceContext) DeepCopyInto(out *NamespaceContext)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type NodeCondition ¶
type NodeCondition struct {
Type string `json:"type"` // Ready, MemoryPressure, DiskPressure
Status string `json:"status"` // True, False, Unknown
}
NodeCondition contains node condition status.
func (*NodeCondition) DeepCopy ¶
func (in *NodeCondition) DeepCopy() *NodeCondition
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new NodeCondition.
func (*NodeCondition) DeepCopyInto ¶
func (in *NodeCondition) DeepCopyInto(out *NodeCondition)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type NodeDetails ¶
type NodeDetails struct {
Name string `json:"name"`
Labels map[string]string `json:"labels,omitempty"`
Capacity ResourceList `json:"capacity"`
Allocatable ResourceList `json:"allocatable"`
Conditions []NodeCondition `json:"conditions,omitempty"`
}
NodeDetails contains node-level context.
func (*NodeDetails) DeepCopy ¶
func (in *NodeDetails) DeepCopy() *NodeDetails
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new NodeDetails.
func (*NodeDetails) DeepCopyInto ¶
func (in *NodeDetails) DeepCopyInto(out *NodeDetails)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type OwnerChainEntry ¶
type OwnerChainEntry struct {
// Namespace of the owner resource (empty for cluster-scoped resources like Node)
Namespace string `json:"namespace,omitempty"`
// Kind of the owner resource (e.g., ReplicaSet, Deployment, StatefulSet, DaemonSet)
Kind string `json:"kind"`
// Name of the owner resource
Name string `json:"name"`
}
OwnerChainEntry represents a single entry in the K8s ownership chain. DD-WORKFLOW-001 v1.8: SignalProcessing traverses ownerReferences to build this. Example chain for a Pod owned by Deployment:
[0]: {Namespace: "prod", Kind: "ReplicaSet", Name: "api-7d8f9c6b5"}
[1]: {Namespace: "prod", Kind: "Deployment", Name: "api"}
func (*OwnerChainEntry) DeepCopy ¶
func (in *OwnerChainEntry) DeepCopy() *OwnerChainEntry
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new OwnerChainEntry.
func (*OwnerChainEntry) DeepCopyInto ¶
func (in *OwnerChainEntry) DeepCopyInto(out *OwnerChainEntry)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type PodDetails ¶
type PodDetails struct {
Name string `json:"name"`
Phase string `json:"phase"` // Running, Pending, Failed
Labels map[string]string `json:"labels,omitempty"`
Annotations map[string]string `json:"annotations,omitempty"`
Containers []ContainerStatus `json:"containers,omitempty"`
RestartCount int32 `json:"restartCount"`
CreationTimestamp string `json:"creationTimestamp"`
}
PodDetails contains pod-level context.
func (*PodDetails) DeepCopy ¶
func (in *PodDetails) DeepCopy() *PodDetails
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PodDetails.
func (*PodDetails) DeepCopyInto ¶
func (in *PodDetails) DeepCopyInto(out *PodDetails)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type ResourceList ¶
type ResourceList struct {
CPU string `json:"cpu"` // e.g., "4000m"
Memory string `json:"memory"` // e.g., "16Gi"
}
ResourceList contains resource quantities.
func (*ResourceList) DeepCopy ¶
func (in *ResourceList) DeepCopy() *ResourceList
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ResourceList.
func (*ResourceList) DeepCopyInto ¶
func (in *ResourceList) DeepCopyInto(out *ResourceList)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type ServicePort ¶
type ServicePort struct {
Name string `json:"name"`
Port int32 `json:"port"`
TargetPort string `json:"targetPort"`
Protocol string `json:"protocol"` // TCP, UDP
}
ServicePort contains service port configuration.
func (*ServicePort) DeepCopy ¶
func (in *ServicePort) DeepCopy() *ServicePort
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ServicePort.
func (*ServicePort) DeepCopyInto ¶
func (in *ServicePort) DeepCopyInto(out *ServicePort)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type ServiceSummary ¶
type ServiceSummary struct {
Name string `json:"name"`
Type string `json:"type"` // ClusterIP, NodePort, LoadBalancer
ClusterIP string `json:"clusterIP"`
Ports []ServicePort `json:"ports,omitempty"`
}
ServiceSummary contains service targeting information.
func (*ServiceSummary) DeepCopy ¶
func (in *ServiceSummary) DeepCopy() *ServiceSummary
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ServiceSummary.
func (*ServiceSummary) DeepCopyInto ¶
func (in *ServiceSummary) DeepCopyInto(out *ServiceSummary)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type StructuredDescription ¶
type StructuredDescription struct {
What string `json:"what" yaml:"what"`
WhenToUse string `json:"whenToUse" yaml:"whenToUse"`
WhenNotToUse string `json:"whenNotToUse,omitempty" yaml:"whenNotToUse,omitempty"`
Preconditions string `json:"preconditions,omitempty" yaml:"preconditions,omitempty"`
}
StructuredDescription provides a structured format for workflow and action type descriptions, consumed by the LLM and operators.
BR-WORKFLOW-004: camelCase field names for both YAML and JSONB storage. DD-WORKFLOW-016: Same format shared between RemediationWorkflow and ActionType.
This is the canonical type. CRD types (api/) keep kubebuilder-annotated copies and convert via DescriptionFromCRD / DescriptionToCRD helpers on their packages. The ogen-generated wire types use snake_case on the REST boundary and convert via OgenDescriptionToShared / SharedDescriptionToOgen.
func OgenDescriptionToShared ¶
func OgenDescriptionToShared(d ogenclient.ActionTypeDescription) StructuredDescription
OgenDescriptionToShared converts an ogen-generated ActionTypeDescription (snake_case REST wire format) to the canonical shared type.
func (*StructuredDescription) DeepCopy ¶
func (in *StructuredDescription) DeepCopy() *StructuredDescription
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new StructuredDescription.
func (*StructuredDescription) DeepCopyInto ¶
func (in *StructuredDescription) DeepCopyInto(out *StructuredDescription)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
func (StructuredDescription) String ¶
func (d StructuredDescription) String() string
String returns the What field as a human-readable summary.
type WorkloadDetails ¶
type WorkloadDetails struct {
// Resource kind (e.g., "Deployment", "StatefulSet", "Node", "Pod")
Kind string `json:"kind"`
// Resource name
Name string `json:"name"`
// Resource labels (primary classification input for Rego policies)
Labels map[string]string `json:"labels,omitempty"`
// Resource annotations (used by business classifier for kubernaut.ai/ labels)
Annotations map[string]string `json:"annotations,omitempty"`
}
WorkloadDetails contains generic workload context for Rego classification. Replaces per-type fields (PodDetails, DeploymentDetails, StatefulSetDetails, etc.) with a single type that works for any K8s resource kind. Rego policies differentiate by Kind when needed (e.g., input.workload.kind == "Node").
func (*WorkloadDetails) DeepCopy ¶
func (in *WorkloadDetails) DeepCopy() *WorkloadDetails
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new WorkloadDetails.
func (*WorkloadDetails) DeepCopyInto ¶
func (in *WorkloadDetails) DeepCopyInto(out *WorkloadDetails)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.