docs: Add comprehensive documentation, examples, and project roadmap (#40)

* docs: Add comprehensive architecture and multi-pool documentation

Added three key documentation files to guide operator development and usage:

- architecture-decisions.md: Documents critical architectural understanding of
  RustFS unified cluster model, erasure coding behavior, and valid/invalid
  multi-pool use cases. Includes warnings about storage class mixing pitfalls.

- multi-pool-use-cases.md: Comprehensive guide covering valid multi-pool
  scenarios (capacity expansion, geographic distribution, spot instances,
  hardware migration) with concrete examples and anti-patterns to avoid.

- DEVELOPMENT-NOTES.md: Development workflow documentation including build
  commands, testing procedures, and contribution guidelines.

These docs prevent common misconfigurations and establish architectural
understanding for contributors.

* examples: Add comprehensive Tenant CRD examples and reorganize structure

Moved examples from deploy/rustfs-operator/examples/ to project root examples/
directory for better visibility and accessibility.

New examples added:
- cluster-expansion-tenant.yaml: Demonstrates capacity expansion and gradual
  hardware migration using multiple pools
- geographic-pools-tenant.yaml: Multi-region deployment with topology
  constraints for compliance and disaster recovery
- hardware-pools-tenant.yaml: Heterogeneous disk sizes within same storage
  class for efficient capacity utilization
- spot-instance-tenant.yaml: Cost optimization using spot instances with
  appropriate tolerations and affinity rules
- production-ha-tenant.yaml: Production-ready HA setup with topology spread
  constraints and resource limits
- README.md: Comprehensive guide with usage instructions, architectural
  warnings, and kubectl verification commands

Enhanced existing examples:
- simple-tenant.yaml: Added documentation for all scheduling fields
- minimal-dev-tenant.yaml: Corrected port references
- custom-rbac-tenant.yaml: Clarified RBAC patterns
- multi-pool-tenant.yaml: Fixed syntax and structure

All examples include:
- Inline documentation explaining configuration choices
- Architectural warnings about RustFS unified cluster behavior
- kubectl verification commands for testing
- Best practices for production deployments

Removed:
- deploy/rustfs-operator/examples/multi-pool-tenant.yaml (moved to examples/)
- deploy/rustfs-operator/examples/simple-tenant.yaml (moved to examples/)

* docs: Add comprehensive CHANGELOG documenting all changes

Added CHANGELOG.md following Keep a Changelog format to track all notable
changes to the RustFS Kubernetes Operator.

Documented changes include:
- Multi-pool scheduling enhancements (2025-11-08)
- Required environment variables additions (2025-11-05)
- Critical port corrections (console: 9090→9001, IO: 90→9000)
- Volume path standardization (/data/{N} → /data/rustfs{N})
- Architecture corrections and clarifications
- Example improvements and bug fixes
- Documentation of valid vs invalid multi-pool use cases

Key architectural facts documented:
- Unified cluster architecture (all pools form ONE erasure-coded cluster)
- Uniform data distribution across ALL volumes
- No storage class awareness or intelligent placement
- Performance limited by slowest storage class
- External tiering via lifecycle policies

Verification against RustFS source code, Helm charts, and official
documentation ensures accuracy.

Test status: 25 tests passing, backward compatibility maintained.

* docs: Add comprehensive project ROADMAP for discussion

Added ROADMAP.md outlining development plans from v0.2.0 through v1.0.0 and
beyond. This document serves as a foundation for community discussion and
priority alignment.

Key sections:
- Current status (v0.1.0) with completed features and known issues
- v0.2.0 (Q1 2026): Core stability with Secret management, status conditions,
  improved error handling, and integration tests
- v0.3.0 (Q2 2026): Advanced lifecycle management, pool operations, TLS
  automation, and monitoring integration
- v0.4.0 (Q3 2026): Enterprise features including multi-tenancy, security
  hardening, compliance, and advanced networking
- v1.0.0 (Q4 2026): Production ready with stability guarantees, complete
  documentation, and ecosystem integration
- Post-1.0: Future considerations (GitOps, multi-cluster, AI/ML optimization)

Also includes:
- Technical debt tracking
- Community and contribution goals
- Release schedule (quarterly pre-1.0, monthly post-1.0)
- Success metrics and contribution guidelines

Target 1.0 release: Q4 2026

This roadmap is a living document open to community input and feedback.

* remove timelines

* remove target release timeline

* remove release schedule

* docs: Update CLAUDE.md with comprehensive project context

Enhanced CLAUDE.md with critical information from recent documentation:

Critical Architectural Understanding:
- Added prominent warning about RustFS unified cluster architecture
- Clarified that all pools form ONE cluster, not separate clusters
- Documented valid vs invalid multi-pool use cases
- Reference to architecture-decisions.md for detailed ADRs

RustFS-Specific Standards:
- Service ports verified against source (IO: 9000, Console: 9001)
- Volume path patterns (/data/rustfs{N})
- Required environment variables
- Credential requirements

Enhanced Documentation:
- Updated CRD validation rules (2-server, 3-server requirements)
- SchedulingConfig with flatten pattern
- Persistence config details
- New spec fields: image_pull_policy, pod_management_policy

Development Context:
- Known issues and TODOs with specific line numbers
- Documentation structure (CHANGELOG, ROADMAP, docs/, examples/)
- All 10 examples organized by category
- Development priorities from ROADMAP (without timelines)
- Test coverage: 25 tests passing

Verification Standards:
- Sources for verifying RustFS behavior
- Warning against inventing features

This provides comprehensive guidance for future development sessions.

* docs: Update ROADMAP with correct discussion and issue tracker links

* docs: Remove community chat placeholder from ROADMAP

Author: Shahab96

CHANGELOG.md

@@ -0,0 +1,175 @@
+# Changelog
+
+All notable changes to the RustFS Kubernetes Operator will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+#### Multi-Pool Scheduling Enhancements (2025-11-08)
+
+- **Per-Pool Kubernetes Scheduling**: Added comprehensive scheduling configuration to Pool struct
+  - `nodeSelector` - Target specific nodes by labels
+  - `affinity` - Complex node/pod affinity rules
+  - `tolerations` - Schedule on tainted nodes (e.g., spot instances)
+  - `topologySpreadConstraints` - Distribute pods across failure domains
+  - `resources` - CPU/memory requests and limits per pool
+  - `priorityClassName` - Override tenant-level priority per pool
+
+- **SchedulingConfig Struct**: Grouped scheduling fields for better code organization
+  - Uses `#[serde(flatten)]` to maintain flat YAML structure
+  - Follows industry-standard pattern (MongoDB, PostgreSQL operators)
+  - 100% backward compatible
+
+- **New Examples**:
+  - `cluster-expansion-tenant.yaml` - Demonstrates capacity expansion and pool migration
+  - `hardware-pools-tenant.yaml` - Shows heterogeneous disk sizes (same storage class)
+  - `geographic-pools-tenant.yaml` - Multi-region deployment for compliance and DR
+  - `spot-instance-tenant.yaml` - Cost optimization using spot instances
+
+- **Documentation**:
+  - `docs/multi-pool-use-cases.md` - Comprehensive multi-pool use case guide
+  - `docs/architecture-decisions.md` - Critical architecture understanding
+  - Updated `examples/README.md` with architecture warnings
+
+- **Tests**: Added 5 new tests for scheduling field propagation (20 → 25 tests)
+
+#### Required Environment Variables (2025-11-05)
+
+- Operator now automatically sets required RustFS environment variables:
+  - `RUSTFS_VOLUMES` - Multi-node volume configuration (already existed)
+  - `RUSTFS_ADDRESS` - Server binding address (0.0.0.0:9000)
+  - `RUSTFS_CONSOLE_ADDRESS` - Console binding address (0.0.0.0:9001)
+  - `RUSTFS_CONSOLE_ENABLE` - Enable console UI (true)
+
+### Fixed
+
+#### Critical Port Corrections (2025-11-05)
+
+- **Console Port**: Changed from 9090 to 9001 (correct RustFS default)
+  - Fixed in `services.rs` and `workloads.rs`
+  - Verified against RustFS source code constants
+
+- **IO Service Port**: Changed from 90 to 9000 (S3 API standard)
+  - Fixed in `services.rs`
+  - Now matches S3-compatible service expectations
+
+#### Volume Path Standardization (2025-11-05)
+
+- **Volume Mount Paths**: Changed from `/data/{N}` to `/data/rustfs{N}`
+  - Matches RustFS official Helm chart convention
+  - Aligns with RustFS docker-compose examples
+  - Verified against RustFS MNMD deployment guide
+
+- **RUSTFS_VOLUMES Format**: Updated path from `/data/{0...N}` to `/data/rustfs{0...N}`
+  - Consistent with RustFS ecosystem standards
+  - Uses 3-dot ellipsis notation for RustFS expansion
+
+#### Architecture Corrections (2025-11-08)
+
+- **Storage Class Mixing**: Corrected examples that incorrectly mixed storage classes
+  - Updated `hardware-pools-tenant.yaml` to use same storage class with different sizes
+  - Fixed `spot-instance-tenant.yaml` to use uniform storage class
+  - Added warnings to `geographic-pools-tenant.yaml` about unified cluster behavior
+
+- **Architectural Clarifications**:
+  - All pools form ONE unified RustFS erasure-coded cluster
+  - Data is striped uniformly across ALL volumes regardless of storage class
+  - Mixing NVMe/SSD/HDD results in HDD-level performance for entire cluster
+  - RustFS has no intelligent storage class-based data placement
+
+#### Examples Bug Fixes (2025-11-05)
+
+- Fixed `multi-pool-tenant.yaml` syntax error (missing `persistence:` nesting)
+- Moved examples from `deploy/rustfs-operator/examples/` to `examples/` at project root
+- Created comprehensive `examples/README.md` with usage guide
+
+### Changed
+
+#### Example Improvements (2025-11-05 to 2025-11-08)
+
+- **simple-tenant.yaml**: Added documentation for all scheduling fields
+- **production-ha-tenant.yaml**: Added topology spread constraints and resource requirements
+- **minimal-dev-tenant.yaml**: Corrected port references and added verification commands
+- **custom-rbac-tenant.yaml**: Clarified RBAC patterns
+
+### Removed
+
+- **tiered-storage-tenant.yaml** (2025-11-05): Removed example with fabricated RustFS features
+  - Contained non-existent environment variables
+  - Made false claims about automatic storage tiering
+  - Replaced with architecturally sound examples
+
+### Documentation
+
+#### Architecture Understanding (2025-11-08)
+
+Key architectural facts now documented:
+
+1. **Unified Cluster Architecture**: All pools in a Tenant form ONE erasure-coded cluster
+2. **Uniform Data Distribution**: Erasure coding stripes data across ALL volumes equally
+3. **No Storage Class Awareness**: RustFS does not prefer fast disks over slow disks
+4. **Performance Limitation**: Cluster performs at speed of SLOWEST storage class
+5. **External Tiering**: RustFS tiering uses lifecycle policies to external cloud storage (S3, Azure, GCS)
+
+#### Valid Multi-Pool Use Cases
+
+Documented valid uses:
+- ✅ Cluster capacity expansion and hardware migration
+- ✅ Geographic distribution for compliance and disaster recovery
+- ✅ Spot vs on-demand instance optimization (compute cost savings)
+- ✅ Same storage class with different disk sizes
+- ✅ Resource differentiation (CPU/memory) per pool
+- ✅ Topology-aware distribution across failure domains
+
+Invalid uses clarified:
+- ❌ Storage class mixing for performance tiering (NVMe for hot, HDD for cold)
+- ❌ Automatic intelligent data placement based on access patterns
+
+---
+
+## [0.1.0] - 2025-11-05
+
+### Initial State
+
+- Basic Tenant CRD with pool support
+- RBAC resource creation (Role, ServiceAccount, RoleBinding)
+- Service creation (IO, Console, Headless)
+- StatefulSet creation per pool
+- Volume claim template generation
+- RUSTFS_VOLUMES automatic configuration
+
+### Known Issues in 0.1.0 (Before Fixes)
+
+- Incorrect console port (9090 instead of 9001)
+- Incorrect IO service port (90 instead of 9000)
+- Missing required RustFS environment variables
+- Non-standard volume mount paths
+- Limited multi-pool scheduling capabilities
+- Misleading examples with fabricated features
+
+---
+
+## Verification
+
+All changes verified against:
+- RustFS source code (`~/git/rustfs`)
+- RustFS Helm chart (`helm/rustfs/`)
+- RustFS docker-compose examples
+- RustFS MNMD deployment guide
+- RustFS configuration constants
+
+## Testing
+
+- **Test Count**: 25 tests
+- **Status**: All passing ✅
+- **Build**: Successful ✅
+- **Backward Compatibility**: 100% maintained ✅
+
+---
+
+**Branch**: `feature/pool-scheduling-enhancements`
+**Status**: Ready for merge