Requirements

Requirements Document

Introduction

This specification defines the requirements for extending the existing N8n Operator (https://github.com/craigedmunds/n8n-operator) to support declarative workflow management through Kubernetes Custom Resource Definitions (CRDs). The extension will add workflow management capabilities to the existing operator that currently manages n8n instances, enabling Infrastructure as Code practices for n8n workflows and making them version-controlled, GitOps-compatible, and automatically deployable.

Glossary

• N8n_Operator: The existing Kubernetes operator (https://github.com/craigedmunds/n8n-operator) that manages n8n instances
• N8nWorkflow_CRD: A new Custom Resource Definition for managing n8n workflows declaratively
• Workflow_Controller: The controller component that syncs N8nWorkflow resources with n8n API
• N8n_Instance: A deployed n8n application managed by the existing operator
• Credential_Manager: Component responsible for injecting Kubernetes secrets into n8n credentials
• ArgoCD: GitOps tool used for automated deployment and synchronization
• Cleanup_Tool: Utility for maintaining n8n instances by removing orphaned workflows
• System: The complete n8n management solution including operator, tools, and utilities

Requirements

Requirement 1: Declarative Workflow Management

User Story: As a DevOps engineer, I want to define n8n workflows in YAML manifests, so that I can manage workflows as code alongside other infrastructure components.

Acceptance Criteria

1. THE N8nWorkflow_CRD SHALL accept workflow definitions in YAML format
2. WHEN a N8nWorkflow resource is created, THE Workflow_Controller SHALL create the corresponding workflow in the referenced n8n instance
3. WHEN a N8nWorkflow resource is updated, THE Workflow_Controller SHALL update the corresponding workflow in n8n
4. WHEN a N8nWorkflow resource is deleted, THE Workflow_Controller SHALL remove the corresponding workflow from n8n
5. THE N8nWorkflow_CRD SHALL include workflow metadata such as name, active status, and tags
6. THE Workflow_Controller SHALL handle resource updates from Git commits and reconcile workflow state appropriately

Requirement 2: N8n Instance Integration

User Story: As a platform engineer, I want workflows to reference existing n8n instances, so that I can deploy workflows to the appropriate n8n deployment.

Acceptance Criteria

1. THE N8nWorkflow_CRD SHALL reference n8n instances by name and namespace
2. WHEN referencing an n8n instance, THE Workflow_Controller SHALL validate the instance exists and is accessible
3. IF an n8n instance is not found, THEN THE Workflow_Controller SHALL report an error condition in the resource status
4. THE Workflow_Controller SHALL support workflows targeting n8n instances in different namespaces
5. WHEN multiple workflows reference the same n8n instance, THE Workflow_Controller SHALL manage them independently

Requirement 3: Credential Management Integration

User Story: As a security engineer, I want workflow credentials to be managed through Kubernetes secrets, so that sensitive data is handled securely and consistently.

Acceptance Criteria

1. THE N8nWorkflow_CRD SHALL reference Kubernetes secrets for workflow credentials
2. WHEN a workflow requires credentials, THE Credential_Manager SHALL inject secret data into n8n before workflow creation
3. THE Credential_Manager SHALL support multiple credential types (HTTP Basic Auth, API keys, OAuth tokens)
4. WHEN secret data changes, THE Workflow_Controller SHALL update the corresponding n8n credentials
5. THE Credential_Manager SHALL support ESO-managed secrets for centralized credential management

Requirement 4: Workflow Lifecycle Management

User Story: As a developer, I want to control workflow activation and deactivation, so that I can manage when workflows are running.

Acceptance Criteria

1. THE N8nWorkflow_CRD SHALL include an active field to control workflow execution
2. WHEN active is set to true, THE Workflow_Controller SHALL activate the workflow in n8n
3. WHEN active is set to false, THE Workflow_Controller SHALL deactivate the workflow in n8n
4. THE Workflow_Controller SHALL report the current active status in the resource status
5. WHEN workflow activation fails, THE Workflow_Controller SHALL report the error and retry

Requirement 5: Status Reporting and Health Monitoring

User Story: As an operations engineer, I want to monitor workflow sync status and health, so that I can troubleshoot issues and ensure workflows are functioning correctly.

Acceptance Criteria

1. THE Workflow_Controller SHALL report workflow sync status in the N8nWorkflow resource status
2. THE Workflow_Controller SHALL include the n8n workflow ID in the status after successful creation
3. WHEN sync operations fail, THE Workflow_Controller SHALL report error conditions with descriptive messages
4. THE Workflow_Controller SHALL update the lastSync timestamp after each successful sync operation
5. THE Workflow_Controller SHALL implement health checks to verify workflow existence in n8n

Requirement 6: Workflow Definition Validation

User Story: As a developer, I want workflow definitions to be validated, so that I can catch configuration errors before deployment.

Acceptance Criteria

1. THE N8nWorkflow_CRD SHALL validate required fields (name, nodes, connections) at admission time
2. WHEN workflow definitions are invalid, THE Workflow_Controller SHALL report validation errors in the resource status
3. THE Workflow_Controller SHALL validate node types and parameters against n8n schema
4. WHEN credential references are invalid, THE Workflow_Controller SHALL report credential validation errors
5. THE N8nWorkflow_CRD SHALL use OpenAPI schema validation for structural validation

Requirement 7: Controller Testing and Verification

User Story: As a developer, I want comprehensive testing of the controller, so that I can ensure it functions correctly and catch regressions early.

Acceptance Criteria

1. WHEN the operator starts, THE System SHALL log that the N8nWorkflow controller is starting and register it with the manager
2. WHEN controller registration fails, THE System SHALL exit with a clear error message
3. WHEN a N8nWorkflow resource is created or updated, THE System SHALL trigger reconciliation and update the resource status
4. WHEN running integration tests, THE System SHALL test controller registration, basic reconciliation, workflow sync with a mock n8n, and error handling scenarios
5. WHEN running end-to-end tests, THE System SHALL deploy a real n8n instance, create N8nWorkflow resources, and verify workflows appear in n8n with correct activation status
6. WHEN code is committed, THE System SHALL run unit tests in CI, and integration tests on pull requests
7. WHEN tests fail, THE System SHALL block merging
8. WHEN a N8nWorkflow is deleted, THE System SHALL delete the workflow from n8n and remove the finalizer after successful deletion

Requirement 8: Workflow Cleanup and Maintenance Operations

User Story: As a platform operator, I want to efficiently clean up orphaned or unwanted workflows from n8n instances, so that I can maintain a clean system and remove hundreds of test workflows.

Acceptance Criteria

1. WHEN listing workflows from n8n API, THE Cleanup_Tool SHALL handle pagination to retrieve all workflows regardless of total count
2. WHEN the n8n API returns paginated results, THE Cleanup_Tool SHALL continue fetching pages until all workflows are retrieved
3. WHEN filtering workflows by name, THE Cleanup_Tool SHALL support exact name matching for workflow deletion
4. WHEN deleting workflows in bulk, THE Cleanup_Tool SHALL support dry-run mode to preview deletions before execution
5. WHEN performing cleanup operations, THE Cleanup_Tool SHALL report progress per page including workflows found and deleted counts
6. WHEN cleanup operations fail, THE Cleanup_Tool SHALL report errors with workflow IDs and continue processing remaining workflows
7. THE Cleanup_Tool SHALL support filtering workflows by multiple criteria including exact name match, active status, and empty/blank workflows

Requirement 9: Emergency Data Reset Operations

User Story: As a platform operator, I want to completely reset an n8n instance when it becomes unmanageable through normal operations, so that I can recover from extreme data accumulation or corruption scenarios.

Acceptance Criteria

1. WHEN an n8n instance has accumulated data beyond practical API-based management, THE System SHALL provide a complete reset capability
2. WHEN initiating a complete reset, THE System SHALL require explicit user confirmation to prevent accidental data loss
3. WHEN reset is confirmed, THE System SHALL remove all n8n data including workflows, credentials, and configuration
4. WHEN reset completes, THE System SHALL ensure all persistent storage is cleaned up
5. WHEN cleanup is complete, THE System SHALL restore the environment to a deployable state
6. WHEN reset operations complete, THE System SHALL provide guidance for restoring service
7. THE System SHALL clearly communicate all data that will be lost before proceeding with reset

Requirement 10: Administrative User Provisioning

User Story: As an n8n operator, I want to automatically provision an administrative user when creating an n8n instance, so that I can programmatically manage workflows and credentials through the n8n API.

Acceptance Criteria

1. WHEN the N8n_Operator creates a new n8n instance, THE N8n_Operator SHALL provision an administrative user account
2. WHEN provisioning the administrative user, THE N8n_Operator SHALL generate secure credentials for API access
3. WHEN the administrative user is created, THE N8n_Operator SHALL store the credentials in a Kubernetes secret
4. WHEN the n8n instance becomes ready, THE N8n_Operator SHALL ensure the administrative user has full permissions
5. WHEN administrative user provisioning fails, THE N8n_Operator SHALL report the error and retry
6. THE N8n_Operator SHALL verify the administrative user can authenticate before marking the instance as ready
7. WHEN an n8n instance is deleted, THE N8n_Operator SHALL clean up associated administrative user credentials

Requirement 11: Database Lifecycle Safety

User Story: As a platform operator, I want to safely manage database lifecycle for n8n instances, so that I can prevent accidental data loss or corruption while maintaining control over data retention.

Acceptance Criteria

1. WHEN creating an n8n instance, THE N8n_Operator SHALL verify the target database does not contain existing n8n data by default
2. WHEN a database contains existing n8n data, THE N8n_Operator SHALL refuse to provision the instance unless explicitly configured to adopt existing data
3. WHEN an operator explicitly opts-in to reusing existing data, THE N8n_Operator SHALL allow the instance to connect to a database with existing n8n data
4. WHEN multiple n8n instances accidentally reference the same database, THE N8n_Operator SHALL detect the conflict and prevent data corruption
5. WHEN database validation fails, THE N8n_Operator SHALL report clear error messages indicating the conflict and remediation steps
6. THE N8n_Operator SHALL ensure each n8n instance maintains data isolation from other instances by default
7. WHEN creating an n8n instance, THE N8n_Operator SHALL default to cleaning up the database when the instance is deleted
8. WHEN an operator explicitly configures data retention, THE N8n_Operator SHALL preserve the database when the instance is deleted
9. WHEN deleting an n8n instance configured for database cleanup, THE N8n_Operator SHALL remove all n8n data from the database
10. WHEN deleting an n8n instance configured for data retention, THE N8n_Operator SHALL leave the database intact
11. WHEN database cleanup is configured, THE N8n_Operator SHALL execute cleanup operations during instance deletion
12. WHEN database cleanup fails, THE N8n_Operator SHALL report the error and allow manual intervention
13. THE N8n_Operator SHALL clearly communicate the configured cleanup behavior in the instance status