events

package
v0.1.135 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 4, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package events provides core infrastructure for generating Kubernetes Events for muster CRD lifecycle operations.

This package extends the existing unified MusterClient architecture to support Kubernetes Events generation, enabling visibility into CRD operations through standard Kubernetes tooling (kubectl get events).

Architecture:

The events package follows the existing service locator pattern and integrates with the unified MusterClient interface. It provides:

  • EventGenerator: Core event generation utilities using MusterClient
  • MessageTemplateEngine: Dynamic message templating system
  • Event type definitions and constants
  • API integration following service locator pattern

Backend Support:

  • Kubernetes: Creates actual Kubernetes Events API objects
  • Filesystem: Logs events to console and events.log file

The package automatically adapts to the current client mode (Kubernetes vs filesystem) through the unified MusterClient interface, ensuring consistent behavior across different deployment environments.

Usage:

Components should access event generation functionality through the API layer: 

eventManager := api.GetEventManager()
if eventManager != nil {
	err := eventManager.CreateEvent(ctx, objectRef, "Created", "MCPServer successfully created", "Normal")
}

Direct usage of EventGenerator is also supported for advanced scenarios: 

generator := events.NewEventGenerator(musterClient)
err := generator.MCPServerEvent(server, events.ReasonCreated, events.EventData{})

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Adapter 

type Adapter struct {
	// contains filtered or unexported fields
}

Adapter implements the EventManagerHandler interface using the unified MusterClient. It bridges the events package functionality with the API service locator pattern. It also implements the ToolProvider interface to expose event querying capabilities through the aggregator.

func NewAdapter 

func NewAdapter(musterClient client.MusterClient) *Adapter

NewAdapter creates a new events adapter using the provided MusterClient.

func (*Adapter) CreateEvent 

func (a *Adapter) CreateEvent(ctx context.Context, objectRef api.ObjectReference, reason, message, eventType string) error

CreateEvent creates an event for a specific object reference. Implements EventManagerHandler.CreateEvent.

func (*Adapter) CreateEventForCRD 

func (a *Adapter) CreateEventForCRD(ctx context.Context, crdType, name, namespace, reason, message, eventType string) error

CreateEventForCRD creates an event for a CRD by type, name, and namespace. Implements EventManagerHandler.CreateEventForCRD.

func (*Adapter) ExecuteTool 

func (a *Adapter) ExecuteTool(ctx context.Context, toolName string, args map[string]interface{}) (*api.CallToolResult, error)

ExecuteTool executes a tool by name. Implements api.ToolProvider.ExecuteTool.

func (*Adapter) GetGenerator 

func (a *Adapter) GetGenerator() *EventGenerator

GetGenerator returns the underlying EventGenerator for advanced usage scenarios. This method is not part of the EventManagerHandler interface but provides access to advanced event generation features when needed.

func (*Adapter) GetTools 

func (a *Adapter) GetTools() []api.ToolMetadata

GetTools returns metadata for all tools this provider offers. Implements api.ToolProvider.GetTools.

func (*Adapter) IsKubernetesMode 

func (a *Adapter) IsKubernetesMode() bool

IsKubernetesMode returns true if the event manager is using Kubernetes mode. Implements EventManagerHandler.IsKubernetesMode.

func (*Adapter) QueryEvents 

func (a *Adapter) QueryEvents(ctx context.Context, options api.EventQueryOptions) (*api.EventQueryResult, error)

QueryEvents retrieves events based on filtering options. Implements EventManagerHandler.QueryEvents.

func (*Adapter) Register 

func (a *Adapter) Register()

Register registers this adapter with the API service locator. This method follows the standard pattern used by all service adapters.

type EventData 

type EventData struct {
	// Name is the name of the object involved in the event.
	Name string

	// Namespace is the namespace of the object involved in the event.
	Namespace string

	// Operation is the operation that triggered the event (e.g., "create", "update", "delete").
	Operation string

	// ServiceClass is the ServiceClass name for service instance events.
	ServiceClass string

	// Arguments contains additional key-value data for the event.
	Arguments map[string]interface{}

	// Error contains error information for failure events.
	Error string

	// Duration is the duration of an operation (for execution events).
	Duration time.Duration

	// StepCount is the number of steps in a workflow execution.
	StepCount int

	// Workflow-specific fields
	// StepID is the ID of the workflow step involved in the event.
	StepID string

	// StepTool is the tool used in the workflow step.
	StepTool string

	// ConditionResult is the result of step condition evaluation.
	ConditionResult string

	// ExecutionID is the unique identifier for a workflow execution.
	ExecutionID string

	// ToolNames contains the list of tools (for availability events).
	ToolNames []string

	// AllowFailure indicates whether a failed step allows failure.
	AllowFailure bool
}

EventData holds contextual information for event message templating.

type EventGenerator 

type EventGenerator struct {
	// contains filtered or unexported fields
}

EventGenerator provides event generation utilities using the unified MusterClient. It automatically adapts to the current client mode (Kubernetes vs filesystem) through the MusterClient interface.

func NewEventGenerator 

func NewEventGenerator(musterClient client.MusterClient) *EventGenerator

NewEventGenerator creates a new EventGenerator using the provided MusterClient.

func (*EventGenerator) CRDEvent 

func (g *EventGenerator) CRDEvent(crdType, name, namespace string, reason EventReason, data EventData) error

CRDEvent generates an event for a CRD by type, name, and namespace. This is useful when you don't have the actual CRD object but know its details.

func (*EventGenerator) GetTemplate 

func (g *EventGenerator) GetTemplate(reason EventReason) (string, bool)

GetTemplate returns the template for a specific event reason.

func (*EventGenerator) IsKubernetesMode 

func (g *EventGenerator) IsKubernetesMode() bool

IsKubernetesMode returns true if the generator is using Kubernetes mode.

func (*EventGenerator) MCPServerEvent 

func (g *EventGenerator) MCPServerEvent(server *musterv1alpha1.MCPServer, reason EventReason, data EventData) error

MCPServerEvent generates an event for an MCPServer CRD.

func (*EventGenerator) ServiceClassEvent 

func (g *EventGenerator) ServiceClassEvent(serviceClass *musterv1alpha1.ServiceClass, reason EventReason, data EventData) error

ServiceClassEvent generates an event for a ServiceClass CRD.

func (*EventGenerator) ServiceInstanceEvent 

func (g *EventGenerator) ServiceInstanceEvent(serviceName, serviceClass, namespace string, reason EventReason, data EventData) error

ServiceInstanceEvent generates an event for a service instance. Since service instances are not CRDs, this creates events using the CreateEventForCRD method with a synthetic CRD type.

func (*EventGenerator) SetTemplate 

func (g *EventGenerator) SetTemplate(reason EventReason, template string)

SetTemplate allows customizing the message template for a specific event reason.

func (*EventGenerator) WorkflowEvent 

func (g *EventGenerator) WorkflowEvent(workflow *musterv1alpha1.Workflow, reason EventReason, data EventData) error

WorkflowEvent generates an event for a Workflow CRD.

type EventReason 

type EventReason string

EventReason represents the reason code for an event. 

const (
	// CRD Management Events
	// ReasonMCPServerCreated indicates an MCPServer CRD was successfully created.
	ReasonMCPServerCreated EventReason = "MCPServerCreated"

	// ReasonMCPServerUpdated indicates an MCPServer CRD was successfully updated.
	ReasonMCPServerUpdated EventReason = "MCPServerUpdated"

	// ReasonMCPServerDeleted indicates an MCPServer CRD was successfully deleted.
	ReasonMCPServerDeleted EventReason = "MCPServerDeleted"

	// Service Lifecycle Events
	// ReasonMCPServerStarting indicates an MCPServer service is beginning to start.
	ReasonMCPServerStarting EventReason = "MCPServerStarting"

	// ReasonMCPServerStarted indicates an MCPServer service was started successfully.
	ReasonMCPServerStarted EventReason = "MCPServerStarted"

	// ReasonMCPServerStopped indicates an MCPServer service was stopped.
	ReasonMCPServerStopped EventReason = "MCPServerStopped"

	// ReasonMCPServerRestarting indicates an MCPServer service is being restarted.
	ReasonMCPServerRestarting EventReason = "MCPServerRestarting"

	// ReasonMCPServerFailed indicates an MCPServer operation failed.
	ReasonMCPServerFailed EventReason = "MCPServerFailed"

	// Tool Discovery Events
	// ReasonMCPServerToolsDiscovered indicates tools were successfully discovered from an MCPServer.
	ReasonMCPServerToolsDiscovered EventReason = "MCPServerToolsDiscovered"

	// ReasonMCPServerToolsUnavailable indicates tool discovery failed or tools became unavailable.
	ReasonMCPServerToolsUnavailable EventReason = "MCPServerToolsUnavailable"

	// ReasonMCPServerReconnected indicates connection to an MCPServer was restored.
	ReasonMCPServerReconnected EventReason = "MCPServerReconnected"

	// Health and Recovery Events
	// ReasonMCPServerHealthCheckFailed indicates health checks failed for an MCPServer.
	ReasonMCPServerHealthCheckFailed EventReason = "MCPServerHealthCheckFailed"

	// ReasonMCPServerRecoveryStarted indicates automatic recovery began for an MCPServer.
	ReasonMCPServerRecoveryStarted EventReason = "MCPServerRecoveryStarted"

	// ReasonMCPServerRecoverySucceeded indicates automatic recovery succeeded for an MCPServer.
	ReasonMCPServerRecoverySucceeded EventReason = "MCPServerRecoverySucceeded"

	// ReasonMCPServerRecoveryFailed indicates automatic recovery failed for an MCPServer.
	ReasonMCPServerRecoveryFailed EventReason = "MCPServerRecoveryFailed"

	// ReasonMCPServerAuthRequired indicates an MCPServer requires OAuth authentication.
	ReasonMCPServerAuthRequired EventReason = "MCPServerAuthRequired"

	// ReasonMCPServerTokenForwarded indicates an ID token was forwarded to a downstream server.
	// This event is generated when muster forwards a user's ID token instead of triggering
	// a separate OAuth flow, enabling SSO across the MCP ecosystem.
	ReasonMCPServerTokenForwarded EventReason = "MCPServerTokenForwarded" //nolint:gosec

	// ReasonMCPServerTokenForwardingFailed indicates ID token forwarding failed.
	// This may trigger fallback to server-specific OAuth if configured.
	ReasonMCPServerTokenForwardingFailed EventReason = "MCPServerTokenForwardingFailed" //nolint:gosec

	// ReasonMCPServerTokenExchanged indicates a token was successfully exchanged via RFC 8693.
	// This event is generated when muster exchanges a local token for one valid on a remote
	// cluster's Identity Provider, enabling cross-cluster SSO.
	ReasonMCPServerTokenExchanged EventReason = "MCPServerTokenExchanged" //nolint:gosec

	// ReasonMCPServerTokenExchangeFailed indicates RFC 8693 token exchange failed.
	// This may trigger fallback to server-specific OAuth if configured.
	ReasonMCPServerTokenExchangeFailed EventReason = "MCPServerTokenExchangeFailed" //nolint:gosec
)

MCPServer event reasons 

const (
	// ReasonServiceClassCreated indicates a ServiceClass was successfully created.
	ReasonServiceClassCreated EventReason = "ServiceClassCreated"

	// ReasonServiceClassUpdated indicates a ServiceClass was successfully updated.
	ReasonServiceClassUpdated EventReason = "ServiceClassUpdated"

	// ReasonServiceClassDeleted indicates a ServiceClass was successfully deleted.
	ReasonServiceClassDeleted EventReason = "ServiceClassDeleted"

	// ReasonServiceClassValidated indicates a ServiceClass was successfully validated.
	ReasonServiceClassValidated EventReason = "ServiceClassValidated"

	// ReasonServiceClassValidationFailed indicates a ServiceClass validation failed.
	ReasonServiceClassValidationFailed EventReason = "ServiceClassValidationFailed"

	// Tool Availability Events
	// ReasonServiceClassAvailable indicates all required tools became available (transitions to Available=true).
	ReasonServiceClassAvailable EventReason = "ServiceClassAvailable"

	// ReasonServiceClassUnavailable indicates required tools became unavailable (transitions to Available=false).
	ReasonServiceClassUnavailable EventReason = "ServiceClassUnavailable"

	// ReasonServiceClassToolsDiscovered indicates new required tools are discovered and available.
	ReasonServiceClassToolsDiscovered EventReason = "ServiceClassToolsDiscovered"

	// ReasonServiceClassToolsMissing indicates specific tools became unavailable.
	ReasonServiceClassToolsMissing EventReason = "ServiceClassToolsMissing"

	// ReasonServiceClassToolsRestored indicates previously missing tools became available again.
	ReasonServiceClassToolsRestored EventReason = "ServiceClassToolsRestored"
)

ServiceClass event reasons 

const (
	// Configuration Management Events
	// ReasonWorkflowCreated indicates a Workflow was successfully created.
	ReasonWorkflowCreated EventReason = "WorkflowCreated"

	// ReasonWorkflowUpdated indicates a Workflow was successfully updated.
	ReasonWorkflowUpdated EventReason = "WorkflowUpdated"

	// ReasonWorkflowDeleted indicates a Workflow was successfully deleted.
	ReasonWorkflowDeleted EventReason = "WorkflowDeleted"

	// ReasonWorkflowValidationFailed indicates workflow definition validation failed.
	ReasonWorkflowValidationFailed EventReason = "WorkflowValidationFailed"

	// ReasonWorkflowValidationSucceeded indicates workflow definition validation passed.
	ReasonWorkflowValidationSucceeded EventReason = "WorkflowValidationSucceeded"

	// Execution Lifecycle Events
	// ReasonWorkflowExecutionStarted indicates workflow execution has begun.
	ReasonWorkflowExecutionStarted EventReason = "WorkflowExecutionStarted"

	// ReasonWorkflowExecutionCompleted indicates workflow execution completed successfully.
	ReasonWorkflowExecutionCompleted EventReason = "WorkflowExecutionCompleted"

	// ReasonWorkflowExecutionFailed indicates workflow execution failed.
	ReasonWorkflowExecutionFailed EventReason = "WorkflowExecutionFailed"

	// ReasonWorkflowExecutionTracked indicates execution state was persisted.
	ReasonWorkflowExecutionTracked EventReason = "WorkflowExecutionTracked"

	// Step-Level Execution Events
	// ReasonWorkflowStepStarted indicates individual step began execution.
	ReasonWorkflowStepStarted EventReason = "WorkflowStepStarted"

	// ReasonWorkflowStepCompleted indicates individual step completed successfully.
	ReasonWorkflowStepCompleted EventReason = "WorkflowStepCompleted"

	// ReasonWorkflowStepFailed indicates individual step failed (with allowFailure context).
	ReasonWorkflowStepFailed EventReason = "WorkflowStepFailed"

	// ReasonWorkflowStepSkipped indicates step was skipped due to condition evaluation.
	ReasonWorkflowStepSkipped EventReason = "WorkflowStepSkipped"

	// ReasonWorkflowStepConditionEvaluated indicates step condition was evaluated.
	ReasonWorkflowStepConditionEvaluated EventReason = "WorkflowStepConditionEvaluated"

	// Tool Availability Events
	// ReasonWorkflowAvailable indicates all required tools became available.
	ReasonWorkflowAvailable EventReason = "WorkflowAvailable"

	// ReasonWorkflowUnavailable indicates required tools became unavailable.
	ReasonWorkflowUnavailable EventReason = "WorkflowUnavailable"

	// ReasonWorkflowToolsDiscovered indicates new required tools are discovered and available.
	ReasonWorkflowToolsDiscovered EventReason = "WorkflowToolsDiscovered"

	// ReasonWorkflowToolsMissing indicates specific tools became unavailable.
	ReasonWorkflowToolsMissing EventReason = "WorkflowToolsMissing"

	// Tool Registration Events
	// ReasonWorkflowToolRegistered indicates workflow was registered as action_<workflow-name> tool.
	ReasonWorkflowToolRegistered EventReason = "WorkflowToolRegistered"

	// ReasonWorkflowToolUnregistered indicates workflow tool was removed from aggregator.
	ReasonWorkflowToolUnregistered EventReason = "WorkflowToolUnregistered"

	// ReasonWorkflowCapabilitiesRefreshed indicates aggregator capabilities were updated after workflow changes.
	ReasonWorkflowCapabilitiesRefreshed EventReason = "WorkflowCapabilitiesRefreshed"

	// Legacy event reasons (kept for compatibility)
	// ReasonWorkflowExecuted indicates a Workflow was successfully executed.
	ReasonWorkflowExecuted EventReason = "WorkflowExecuted"
)

Workflow event reasons 

const (
	// ReasonServiceInstanceCreated indicates a service instance was successfully created.
	ReasonServiceInstanceCreated EventReason = "ServiceInstanceCreated"

	// ReasonServiceInstanceStarting indicates a service instance is beginning to start.
	ReasonServiceInstanceStarting EventReason = "ServiceInstanceStarting"

	// ReasonServiceInstanceStarted indicates a service instance was successfully started.
	ReasonServiceInstanceStarted EventReason = "ServiceInstanceStarted"

	// ReasonServiceInstanceStopping indicates a service instance is beginning to stop.
	ReasonServiceInstanceStopping EventReason = "ServiceInstanceStopping"

	// ReasonServiceInstanceStopped indicates a service instance was successfully stopped.
	ReasonServiceInstanceStopped EventReason = "ServiceInstanceStopped"

	// ReasonServiceInstanceRestarting indicates a service instance restart is initiated.
	ReasonServiceInstanceRestarting EventReason = "ServiceInstanceRestarting"

	// ReasonServiceInstanceRestarted indicates a service instance restart completed successfully.
	ReasonServiceInstanceRestarted EventReason = "ServiceInstanceRestarted"

	// ReasonServiceInstanceDeleted indicates a service instance was successfully deleted.
	ReasonServiceInstanceDeleted EventReason = "ServiceInstanceDeleted"

	// ReasonServiceInstanceFailed indicates a service instance operation failed.
	ReasonServiceInstanceFailed EventReason = "ServiceInstanceFailed"

	// ReasonServiceInstanceHealthy indicates a service instance health checks are passing.
	ReasonServiceInstanceHealthy EventReason = "ServiceInstanceHealthy"

	// ReasonServiceInstanceUnhealthy indicates a service instance health checks are failing.
	ReasonServiceInstanceUnhealthy EventReason = "ServiceInstanceUnhealthy"

	// ReasonServiceInstanceHealthCheckFailed indicates an individual health check failed.
	ReasonServiceInstanceHealthCheckFailed EventReason = "ServiceInstanceHealthCheckFailed"

	// ReasonServiceInstanceHealthCheckRecovered indicates health check recovered after failures.
	ReasonServiceInstanceHealthCheckRecovered EventReason = "ServiceInstanceHealthCheckRecovered"

	// ReasonServiceInstanceStateChanged indicates detailed state transitions.
	ReasonServiceInstanceStateChanged EventReason = "ServiceInstanceStateChanged"

	// ReasonServiceInstanceToolExecutionStarted indicates ServiceClass lifecycle tool execution began.
	ReasonServiceInstanceToolExecutionStarted EventReason = "ServiceInstanceToolExecutionStarted"

	// ReasonServiceInstanceToolExecutionCompleted indicates ServiceClass lifecycle tool execution succeeded.
	ReasonServiceInstanceToolExecutionCompleted EventReason = "ServiceInstanceToolExecutionCompleted"

	// ReasonServiceInstanceToolExecutionFailed indicates ServiceClass lifecycle tool execution failed.
	ReasonServiceInstanceToolExecutionFailed EventReason = "ServiceInstanceToolExecutionFailed"
)

Service Instance event reasons

type EventType 

type EventType string

EventType represents the type/severity of a Kubernetes Event. 

const (
	// EventTypeNormal indicates normal, non-problematic events.
	EventTypeNormal EventType = "Normal"

	// EventTypeWarning indicates events that may require attention.
	EventTypeWarning EventType = "Warning"
)

type MessageTemplateEngine 

type MessageTemplateEngine struct {
	// contains filtered or unexported fields
}

MessageTemplateEngine provides dynamic message generation for events.

func NewMessageTemplateEngine 

func NewMessageTemplateEngine() *MessageTemplateEngine

NewMessageTemplateEngine creates a new message template engine with default templates.

func (*MessageTemplateEngine) GetTemplate 

func (e *MessageTemplateEngine) GetTemplate(reason EventReason) (string, bool)

GetTemplate returns the template for a specific event reason.

func (*MessageTemplateEngine) Render 

func (e *MessageTemplateEngine) Render(reason EventReason, data EventData) string

Render generates a message for the given event reason and data.

func (*MessageTemplateEngine) SetTemplate 

func (e *MessageTemplateEngine) SetTemplate(reason EventReason, template string)

SetTemplate allows customizing the message template for a specific event reason.

type ObjectReference 

type ObjectReference struct {
	// APIVersion is the API version of the object.
	APIVersion string

	// Kind is the kind of the object.
	Kind string

	// Name is the name of the object.
	Name string

	// Namespace is the namespace of the object.
	Namespace string

	// UID is the unique identifier of the object (optional).
	UID string
}

ObjectReference represents a reference to a Kubernetes object for event creation.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.