Documentation
¶
Overview ¶
Package audit provides audit trail management for WorkflowExecution.
This package implements BR-WE-005 (Audit Trail) by recording all workflow lifecycle events to the Data Storage service via the pkg/audit shared library.
Audit Events: - execution.started: PipelineRun initiated (Gap #6, BR-AUDIT-005) - workflow.completed: PipelineRun succeeded - workflow.failed: PipelineRun failed or timed out - selection.completed: Workflow selected from spec (Gap #5, BR-AUDIT-005)
Per ADR-032: Audit is MANDATORY for WorkflowExecution (P0 service). Per DD-AUDIT-004: Uses type-safe WorkflowExecutionAuditPayload structures.
Per Controller Refactoring Pattern Library (P3: Audit Manager): - Extracted from internal/controller/workflowexecution/audit.go - Testable audit logic in isolation - Consistent package structure with other controllers
Reference: docs/architecture/patterns/CONTROLLER_REFACTORING_PATTERN_LIBRARY.md
Index ¶
- Constants
- type Manager
- func (m *Manager) RecordExecutionWorkflowStarted(ctx context.Context, wfe *workflowexecutionv1alpha1.WorkflowExecution, ...) error
- func (m *Manager) RecordWorkflowCompleted(ctx context.Context, wfe *workflowexecutionv1alpha1.WorkflowExecution) error
- func (m *Manager) RecordWorkflowFailed(ctx context.Context, wfe *workflowexecutionv1alpha1.WorkflowExecution) error
- func (m *Manager) RecordWorkflowSelectionCompleted(ctx context.Context, wfe *workflowexecutionv1alpha1.WorkflowExecution) error
Constants ¶
const ( ActionStarted = "started" ActionCompleted = "completed" ActionFailed = "failed" )
Event actions for WorkflowExecution audit events (per DD-AUDIT-003)
const ( EventTypeExecutionStarted = "workflowexecution.execution.started" // Gap #6 (BR-AUDIT-005) - PipelineRun created EventTypeCompleted = "workflowexecution.workflow.completed" // Per OpenAPI spec discriminator EventTypeFailed = "workflowexecution.workflow.failed" // Per OpenAPI spec discriminator EventTypeSelectionCompleted = "workflowexecution.selection.completed" // Gap #5 (BR-AUDIT-005) - Per ADR-034 v1.5 )
Event types for WorkflowExecution audit events (per ADR-034 v1.5 + OpenAPI spec) Per ADR-034 v1.5: ALL event types from WorkflowExecution controller use "workflowexecution" prefix These match the event_type enum values in data-storage-v1.yaml
const (
CategoryWorkflowExecution = "workflowexecution" // Per ADR-034 v1.5 (2026-01-08)
)
Event category for WorkflowExecution audit events (ADR-034 v1.5: Service-level category) Per ADR-034 v1.5: ALL events from WorkflowExecution controller use "workflowexecution" category
const (
EventCategoryWorkflowExecution = "workflowexecution"
)
Event category constant (from OpenAPI spec)
const ServiceName = "workflowexecution-controller"
ServiceName is the canonical service identifier for audit events.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager handles audit trail recording for WorkflowExecution lifecycle events.
The Manager provides typed methods for each audit event type, ensuring consistent audit event structure across all workflow execution events.
Usage:
auditMgr := audit.NewManager(auditStore, logger) err := auditMgr.RecordExecutionWorkflowStarted(ctx, wfe, pipelineRunName, namespace)
func NewManager ¶
func NewManager(store audit.AuditStore, logger logr.Logger) *Manager
NewManager creates a new audit manager.
Parameters: - store: AuditStore for writing audit events (from pkg/audit) - logger: Logger for audit operations
The store may be nil to disable audit (graceful degradation), though per ADR-032 audit is MANDATORY for WorkflowExecution (P0 service).
func (*Manager) RecordExecutionWorkflowStarted ¶
func (m *Manager) RecordExecutionWorkflowStarted( ctx context.Context, wfe *workflowexecutionv1alpha1.WorkflowExecution, pipelineRunName string, pipelineRunNamespace string, ) error
RecordExecutionWorkflowStarted records an execution.workflow.started audit event (Gap #6).
This event is emitted immediately after PipelineRun creation succeeds, providing the PipelineRun reference for complete Request-Response reconstruction. Per BR-AUDIT-005 Gap #6, this links WorkflowExecution to Tekton PipelineRun.
Event Data Structure:
- execution_ref: {api_version: "tekton.dev/v1", kind: "PipelineRun", name, namespace}
Parameters:
- pipelineRunName: Name of the created PipelineRun
- pipelineRunNamespace: Namespace of the created PipelineRun
func (*Manager) RecordWorkflowCompleted ¶
func (m *Manager) RecordWorkflowCompleted(ctx context.Context, wfe *workflowexecutionv1alpha1.WorkflowExecution) error
RecordWorkflowCompleted records a workflow.completed audit event.
This event is emitted when a PipelineRun completes successfully.
func (*Manager) RecordWorkflowFailed ¶
func (m *Manager) RecordWorkflowFailed(ctx context.Context, wfe *workflowexecutionv1alpha1.WorkflowExecution) error
RecordWorkflowFailed records a workflow.failed audit event.
This event is emitted when a PipelineRun fails or times out. BR-AUDIT-005 Gap #7: Now includes standardized error_details for SOC2 compliance.
func (*Manager) RecordWorkflowSelectionCompleted ¶
func (m *Manager) RecordWorkflowSelectionCompleted(ctx context.Context, wfe *workflowexecutionv1alpha1.WorkflowExecution) error
RecordWorkflowSelectionCompleted records a workflow.selection.completed audit event (Gap #5).
This event is emitted immediately after workflow selection from spec.WorkflowRef, before PipelineRun creation. Per BR-AUDIT-005 Gap #5, this provides visibility into which workflow was selected for execution.
Event Data Structure:
- selected_workflow_ref: {workflow_id, version, container_image}
Source Files