Requirements

Requirements Document: N8n Platform

Introduction

This specification defines the comprehensive requirements for running n8n in Kubernetes through a custom operator. It covers the complete lifecycle including operator development and maintenance, instance deployment architecture, database connectivity, workflow management, and operational tooling. The goal is to provide a production-ready, secure, and maintainable n8n platform that follows Kubernetes best practices and GitOps principles.

Glossary

• N8n_Operator: Kubernetes operator that manages n8n instances and workflows
• N8n_Instance: A deployed n8n application managed by the operator
• N8nWorkflow_CRD: Custom Resource Definition for managing n8n workflows declaratively
• Workflow_Controller: Controller component that syncs N8nWorkflow resources with n8n API
• Credential_Manager: Component responsible for injecting Kubernetes secrets into n8n credentials
• Upstream_Repository: The original n8n-operator repository (jakub-k-slys/n8n-operator)
• Fork_Repository: Our forked repository (craigedmunds/n8n-operator)
• Database_Service: PostgreSQL database service used by n8n instances
• Operator_Namespace: Kubernetes namespace where the operator runs
• Instance_Namespace: Kubernetes namespace where n8n instances are deployed
• Cleanup_Tool: Utility for maintaining n8n instances by removing orphaned workflows
• System: The complete n8n platform including operator, instances, tools, and utilities

Requirements

Requirement 1: Operator Architecture and Namespace Design

User Story: As a platform architect, I want a clear namespace and connectivity architecture for the n8n operator and instances, so that I can ensure proper isolation, security, and operational simplicity while supporting multi-tenancy.

Acceptance Criteria

1. THE System SHALL deploy the operator in a dedicated namespace (n8n-operator-system) separate from n8n instances
2. THE System SHALL deploy a shared PostgreSQL database in a dedicated data namespace (n8n-data)
3. THE System SHALL deploy n8n instances in their own namespaces (e.g., n8n, n8n-tenant-1, etc.)
4. WHEN the operator connects to databases in different namespaces, THE System SHALL use fully qualified service names (FQDN)
5. WHEN a database hostname does not contain a dot, THE System SHALL automatically construct the FQDN as <service>.<namespace>.svc.cluster.local
6. THE System SHALL support multi-tenancy by allowing multiple n8n instances to share the same PostgreSQL server
7. WHEN multiple instances share a PostgreSQL server, THE System SHALL create separate databases for each instance
8. WHEN multiple instances share a PostgreSQL server, THE System SHALL use separate credentials for each instance
9. THE System SHALL document the recommended namespace architecture and provide clear guidance on deployment patterns
10. WHEN the operator needs cross-namespace access, THE System SHALL configure appropriate RBAC permissions

Requirement 2: Multi-Architecture Build and Distribution

User Story: As a platform engineer, I want the n8n operator to support multiple architectures, so that I can deploy it on different hardware platforms including ARM and AMD64.

Acceptance Criteria

1. THE System SHALL build operator images for both linux/amd64 and linux/arm64 architectures
2. WHEN building images, THE System SHALL use Docker Buildx for multi-platform builds
3. WHEN pushing images, THE System SHALL publish multi-architecture manifests to the container registry
4. THE System SHALL use semantic versioning for operator releases
5. WHEN building development images, THE System SHALL tag them with -dev-<timestamp> suffix
6. WHEN building release images, THE System SHALL increment the version number appropriately
7. THE System SHALL include all necessary testing tools in development images
8. THE System SHALL optimize production images for size and security

Requirement 3: Upstream Maintenance and Security

User Story: As a security-conscious maintainer, I want to maintain synchronization with the upstream n8n-operator repository while ensuring security, so that I can stay current without compromising the fork.

Acceptance Criteria

1. WHEN a workflow file is added or modified, THE System SHALL analyze it for security risks before execution
2. WHEN analyzing workflows, THE System SHALL detect use of third-party actions without version pinning
3. WHEN analyzing workflows, THE System SHALL detect suspicious commands or script execution patterns
4. WHEN analyzing workflows, THE System SHALL detect credential exposure risks
5. WHEN a security risk is detected, THE System SHALL block automatic merge and require manual review
6. WHEN Dependabot proposes a dependency update, THE System SHALL verify the dependency source
7. WHEN a major version update is proposed, THE System SHALL require manual review before auto-merge
8. WHEN upstream changes are available, THE System SHALL present a summary of changes for review
9. WHEN changes are approved, THE System SHALL apply them to the fork with appropriate testing
10. THE System SHALL support manual triggering of upstream synchronization

Requirement 4: 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 5: 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 6: 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 7: 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 8: 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 9: 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 10: 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 11: 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 12: 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 13: 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 14: Database Lifecycle Safety

User Story: As a platform operator, I want to safely manage database lifecycle for n8n instances using a shared PostgreSQL server, so that I can prevent accidental data loss or corruption while maintaining control over data retention and supporting multi-tenancy.

Acceptance Criteria

1. WHEN creating an n8n instance, THE N8n_Operator SHALL create a dedicated database within the shared PostgreSQL server
2. WHEN creating a database for an instance, THE N8n_Operator SHALL verify the database name does not already exist
3. WHEN a database name already exists, THE N8n_Operator SHALL refuse to provision the instance unless explicitly configured to adopt existing data
4. WHEN an operator explicitly opts-in to reusing existing data, THE N8n_Operator SHALL allow the instance to connect to an existing database
5. WHEN multiple n8n instances accidentally reference the same database name, THE N8n_Operator SHALL detect the conflict and prevent data corruption
6. WHEN database validation fails, THE N8n_Operator SHALL report clear error messages indicating the conflict and remediation steps
7. THE N8n_Operator SHALL ensure each n8n instance maintains data isolation through separate databases and credentials
8. WHEN creating an n8n instance, THE N8n_Operator SHALL create dedicated PostgreSQL user credentials for that instance
9. WHEN creating an n8n instance, THE N8n_Operator SHALL default to cleaning up the database when the instance is deleted
10. WHEN an operator explicitly configures data retention, THE N8n_Operator SHALL preserve the database when the instance is deleted
11. WHEN deleting an n8n instance configured for database cleanup, THE N8n_Operator SHALL drop the database and remove the user credentials
12. WHEN deleting an n8n instance configured for data retention, THE N8n_Operator SHALL leave the database and credentials intact
13. WHEN database cleanup is configured, THE N8n_Operator SHALL execute cleanup operations during instance deletion
14. WHEN database cleanup fails, THE N8n_Operator SHALL report the error and allow manual intervention
15. THE N8n_Operator SHALL clearly communicate the configured cleanup behavior in the instance status