microsoft / microsoft/GitHub-Copilot-for-Azure
[Add Capability]: azure-kusto - document local Kustainer emulator container-recreate reattach (.attach database vs .create ... persist)
- Dominant language
- Python
- Stars
- 250
- Forks
- 204
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 67
Description
### Existing Skill to Extend
azure-kusto
### Contacts
MSBrett
### Current Behavior / Gap
The `azure-kusto` skill covers querying/managing real ADX clusters via the Azure MCP Kusto tools and Azure CLI, but has no guidance for the **local Kusto emulator (Kustainer, `mcr.microsoft.com/azuredataexplorer/kustainer-linux`)**, which is a common offline/dev-loop scenario (e.g. FinOps Toolkit's `ftklocal` work uses it to run the toolkit's Kusto-backed analytics without a live Azure cluster).
Specifically, there's a sharp, easy-to-hit failure mode around **container lifecycle**: if the Kustainer Docker container is stopped/removed and recreated (e.g. to bump `--memory`, move hosts, or upgrade the image) against the *same* bind-mounted `/kustodata` volume, previously-persisted databases do **not** automatically reattach - only the built-in empty `NetDefaultDB` is created on engine start. Users/agents who then try to "fix" this by re-running the canonical creation command:
```kusto
.create database MyDb persist (@"/kustodata/dbs/MyDb/md", @"/kustodata/dbs/MyDb/data")
```
...get a generic, unhelpful `Internal service error`, because that command is for *creating a new* database, not reattaching one whose metadata already exists on disk. This is easy to misdiagnose as data loss/corruption (the data is actually fully intact on disk the whole time) when the real fix is the distinct reattach command:
```kusto
.attach database MyDb from @"/kustodata/dbs/MyDb/md"
```
This was confirmed via live, first-party incident reproduction: the failing `.create ... persist(...)` command failed identically and near-instantly (flat CPU/memory, no resource pressure) on both a 408KB and a 49GB database, ruling out size/resource causes, while `.attach database ... from` succeeded in ~0.15s for both and preserved 100% of the data (row counts verified identical before/after against a 40M+ row table).
### Intended Agent Scenarios
- "My local Kusto emulator container was recreated and I can't see my database anymore - is my data lost?"
- "How do I reattach a Kustainer database after restarting the Docker container?"
- "I'm getting `Internal service error` running `.create database ... persist(...)` against my Kusto emulator."
- General guidance on persisting/reattaching Kustainer databases across container restarts for local ADX development.
### Timeline
Now - small, self-contained documentation addition (no new tools/triggers), PR ready alongside this issue.
### Additional Context
Proposed change adds a new "Local Kusto Emulator (Kustainer / Docker)" section to `plugin/skills/azure-kusto/SKILL.md` plus one line in "Common Issues", pointing at the `.attach database ... from` command as the correct reattach mechanism. No new MCP tools or activation triggers; stays well within the SKILL.md token budget (~2.7k of the 5k token limit). Verified with the repo's own `checkCopilotCliCharBudget` and `frontmatter` validators (only pre-existing, repo-wide `0.0.0-placeholder` semver notice appears, unrelated to this change).
Contributor guide
Research direction
Review plugin/skills/azure-kusto/SKILL.md and its Common Issues section first. Run the repository's checkCopilotCliCharBudget and frontmatter validators before and after the documentation update. Done means the Kustainer container-recreation and database-reattachment guidance is present without adding tools or activation triggers.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, docker
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 82/100