Repository files navigation

This C# project provides functionality to work with schemas in Azure Data Explorer (Kusto). You can load a schema from yaml files or a database to the interal data structure. This can be used for creating diffs of two databases as scripts or markdown, and also to write it back to files or update schemas in a database.

A second project "KustoSchemaToolsAction" wraps that into a CLI tool inside a docker container for usage in GitHub Actions.

Thedatabase object holds all schema related information for a Kusto database. It can be loaded from, or written to a cluster using theKustoDatabaseHandler which can be created by theKustoDatabaseHandlerFactory. There are several steps involved for loading all relevant information from a kusto database into thedatabase object. These are covered by different plugins, which can be configured for theKustoDatabaseHandlerFactory.

vardbFactory=newKustoDatabaseHandlerFactory(sp.GetService<ILogger<KustoDatabaseHandler>>()).WithPlugin<KustoDatabasePrincipalLoader>().WithPlugin<KustoDatabaseRetentionAndCacheLoader>().WithPlugin<KustoTableBulkLoader>().WithPlugin<KustoFunctionBulkLoader>().WithPlugin<KustoMaterializedViewBulkLoader>().WithPlugin<DatabaseCleanup>()

For synchronizing it to files, theYamlDatabaseHandler and theYamlDatabaseHandlerFactory are the right tools. To prevent super large files, there are plugins that handle reading and writing functions, tables and materialized views to separate files and folders. They can be configured for theYamlDatabaseHandlerFactory.

varyamlFactory=newYamlDatabaseHandlerFactory().WithPlugin(newTablePlugin()).WithPlugin(newFunctionPlugin()).WithPlugin(newMaterializedViewsPlugin()).WithPlugin<DatabaseCleanup>();

Additional features can be added with custom plugins. A sample fortable groups, where some parts of the schema are defined once, but are applied for several tables can be found inhere.

TheKustoSchemaHandler is the central place for synching schemas between yaml and a database. It offers functions for generating changes formatted in markdown, writing a database to yaml files and applying changes from yaml files to a database.

Cluster configuration changes are handled by theKustoClusterOrchestrator. Currently supported features includeCapacity Policies andWorkload Groups. The orchestrator expects a file path to a configuration file. A key design principle is that you only need to specify the properties you wish to set or change. Any property omitted in your policy file will be ignored, preserving its current value on the cluster.A sample file could look like this:

connections:-name:testurl:test.eastuscapacityPolicy:ingestionCapacity:clusterMaximumConcurrentOperations:512coreUtilizationCoefficient:0.75extentsMergeCapacity:minimumConcurrentOperationsPerNode:1maximumConcurrentOperationsPerNode:3extentsPurgeRebuildCapacity:maximumConcurrentOperationsPerNode:1workloadGroups:  -workloadGroupName:DataScienceworkloadGroupPolicy:requestRateLimitsEnforcementPolicy:commandsEnforcementLevel:Cluster

TheKustoClusterOrchestrator coordinates between cluster handlers to manage cluster configuration changes:

1. Loading Configuration: UsesYamlClusterHandler to parse the YAML configuration file and load the desired cluster state
2. Reading Current State: UsesKustoClusterHandler to connect to each live cluster and retrieve the current capacity policy and workload group settings
3. Generating Changes: Compares the desired state (from YAML) with the current state (from Kusto) to identify differences
4. Creating Scripts: Generates the necessary Kusto control commands (like.alter-merge cluster policy capacity and.create-or-alter workload_group) to apply the changes
5. Applying Updates: Executes the generated scripts against the live clusters to synchronize them with the desired configuration

Currently no plugins are supported. The orchestrator expects all cluster configuration in a central file.

Currently following features are supported:

• Cluster
  • Capacity Policies
  • Workload Groups
• Database
  • Permissions
  • Default Retention
  • Default Hot Cache
• Tables
  • Columns
  • Retention
  • HotCache
  • Update Policies
  • Docstring
  • Folder
• Functions
  • Body
  • Docstring
  • Folder
  • Preformatted
• Materialized Views
  • Query
  • Retention
  • HotCache
  • Docstring
  • Folder
  • Preformatted
• External Tables (managed identity/impersonation only)
  • Storage / Delta / SQL
  • Folder
  • Docstring
• Continuous Exports
• Entity Groups
• Deleting existing items using deletions in the database definition
  • Tables
  • Columns
  • Functions
  • Materialized Views
  • Extenal Tables
  • Continuous Exports

TheDatabaseCleanup will remove redundant retention and hotcache definitions.It will also pretty print KQL queries in functions (unless thepreformatted feature is used) , update policies, materialized views and continuous exports.