Add entity-groups support for ADX operator federation

[jessejlt]

Summary

This PR adds entity-groups support to the ADX operator federation system, enabling efficient cross-cluster queries by creating named database metadata objects that reference all active partition clusters.

Changes

Core Implementation

• Entity-Groups Creation: Added ensureEntityGroups() function that creates/updates entity-groups for each database with active partition clusters
• Naming Convention: Entity-groups follow the pattern {DatabaseName}_Partitions (e.g., Metrics_Partitions, Logs_Partitions)
• Stale Cleanup: Automatically removes entity-groups for databases that no longer have active partition clusters
• Zero-Heartbeat Protection: Skips entity-group operations when no heartbeat data is received to prevent accidental mass deletion

Integration Points

• Federation Workflow: Entity-groups are created/updated during the FederateClusters() reconciliation loop
• Heartbeat-Driven: Entity-group membership is based on recent heartbeat data from partition clusters
• Database Scoped: Each database gets its own entity-group containing only the partition clusters that have that database

Testing

• Comprehensive Unit Tests: Added TestEntityGroupLogic() with 6 test cases covering:
  • Zero-heartbeat protection behavior
  • Entity-group naming conventions
  • Database filtering logic
  • Stale entity-group detection and cleanup
  • Multi-endpoint federation scenarios
  • Error handling for missing databases

Technical Details

• Safety First: Zero-heartbeat protection prevents mass deletion when partition clusters are temporarily unavailable
• Efficient Queries: Entity-groups enable using entity_group in KQL queries instead of manually listing all cluster endpoints
• Graceful Degradation: Entity-group failures don't block function generation - federation continues working
• Kusto Integration: Uses .create entity_group and .alter entity_group commands with proper error handling

Usage Example

After this change, users can query across all partition clusters for a database using:

// Instead of manually listing all clusters:
// union cluster('endpoint1').database('Metrics').MyTable, cluster('endpoint2').database('Metrics').MyTable

// Now you can use the entity-group:
entity_group Metrics_Partitions | MyTable

Testing

All tests pass:

• Unit tests validate entity-group logic with comprehensive scenarios
• Integration with existing federation workflow
• Error handling and edge cases covered

Backwards Compatibility

This change is fully backwards compatible:

• Existing federation functionality continues to work unchanged
• Entity-groups are created in addition to existing function generation
• No breaking changes to APIs or existing behavior

Implementation Notes

• Entity-groups are created/updated during the 10-minute federation reconciliation cycle
• Zero-heartbeat protection ensures robust operation during partition cluster maintenance
• Proper cleanup prevents accumulation of stale entity-groups
• Error handling allows federation to continue even if entity-group operations fail

[Copilot]

Pull Request Overview

This PR adds comprehensive entity-groups support to the ADX operator federation system, enabling efficient cross-cluster queries by creating named database metadata objects that reference all active partition clusters. The implementation provides an alternative to generated functions while maintaining full backward compatibility.

Key changes:

• Entity-Groups Creation: Added ensureEntityGroups() function that creates/updates entity-groups for each database with active partition clusters, following naming pattern {DatabaseName}_Partitions
• Safety Features: Implemented zero-heartbeat protection to prevent accidental mass deletion during outages, plus automatic cleanup of stale entity-groups
• Enhanced Query Options: Users can now query federated data using either auto-generated functions or direct entity-group access with macro-expand entity_group syntax

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
operator/adx.go	Core implementation of entity-groups creation, validation, and lifecycle management with safety protections
operator/adx_test.go	Comprehensive unit tests covering entity-group logic, naming validation, and zero-heartbeat protection scenarios
docs/designs/operator.md	Detailed documentation of entity-groups functionality including usage examples and advanced scenarios
docs/concepts.md	Updated federation concepts to include entity-groups as an additional query approach
.github/plans/operator/entity-groups.md	Complete implementation plan and project tracking document

Comments suppressed due to low confidence (1)

operator/adx_test.go:968

• The variable name err shadows the error variable from the outer scope which could lead to confusion. Consider using a more descriptive name like mockErr or expectedErr.

					for pattern, err := range tt.mgmtErrors {

[jessejlt]

All KQL injection vulnerabilities identified in the security review have been resolved. The changes implement:

1. Secure KQL Builder Patterns: Replaced all fmt.Sprintf and AddUnsafe() usage with proper KQL builder methods using AddLiteral() and AddParameter()
2. Input Validation: Added isValidEntityGroupName() validation to prevent injection attacks
3. Code Quality Improvements: Extracted magic strings to constants (PartitionsSuffix) to reduce duplication
4. Parameterized Queries: Used proper KQL parameter syntax with AddParameter() for all dynamic content

These security fixes ensure that all user-controlled input is properly validated and safely incorporated into KQL queries, preventing injection vulnerabilities while maintaining the intended functionality of the entity-groups federation feature.

[mkeesey]

I'm concerned this comment is not right. I think we're just consuming from whatever is in the heartbeat table, but if someone has the ability to insert rows into that table, they can add arbitrary stuff to those rows including weird KQL.

Is there a mechanism we can use to parameterize the string slice in the kql library so it escapes anything bad?