microsoft / microsoft/GitHub-Copilot-for-Azure

[Add Capability]: azure-kusto - document local Kustainer emulator container-recreate reattach (.attach database vs .create ... persist)

Open Beginner friendly
#2,924 1 comment 0 reactions 0 assignees View on GitHub
untriaged
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.