Revert a migration (remove generated Kibana assets)
Audience: operators of the published obs-migrate CLI (PyPI/uvx), using public docs and their real source + Elastic/Kibana — not a repo lab harness.
Goal: cleanly remove the assets a migration put into Kibana — dashboards, alerting rules, or both — so the user can back out or redo. This is a target-only, destructive operation; nothing is touched in the source Grafana/Datadog.
Prerequisites (install)
These skills help operators of the published CLI (not a repo checkout).
If obs-migrate is missing or doctor is not Ready, follow
install-obs-migrate first — that skill owns PyPI/uvx/pip, extras, and
Python/uv gotchas. Do not invent alternate install commands here.
uvx --from 'elastic-observability-migration[all]' obs-migrate doctor
# After a persistent install, the same check is: obs-migrate doctor
Source/Elastic credentials: connect-to-o11y-source (and your env exports).
Safety first
- This deletes target assets. Confirm with the user what to remove (which dashboards, alerts, or everything) before running a destructive step.
- Dashboard deletion has no dry-run or
--confirm: list dashboards first, confirm the exact IDs with the user, then rundelete-dashboards. Alert-rule deletion is safer by default becausedelete-rulesis dry-run unless--confirm. - Reverting does not touch the source. The original Grafana/Datadog dashboards and monitors are unaffected.
Reverting dashboards
There is no "delete by migration tag" for dashboards — you delete by id. Prefer ids from <output-dir>/dashboards/native/*.native.json → dashboard_id, then confirm they still exist:
export KIBANA_ENDPOINT="https://...kbn..." KEY="<api-key>"
# 1. List dashboards in Kibana to find the ids to remove (read-only):
obs-migrate cluster list-dashboards \
--kibana-url "$KIBANA_ENDPOINT" --kibana-api-key "$KEY"
# Optional: confirm Serverless vs stateful (affects delete semantics messaging):
obs-migrate cluster detect-serverless \
--kibana-url "$KIBANA_ENDPOINT" --kibana-api-key "$KEY"
# 2. Delete the chosen dashboards by id:
obs-migrate cluster delete-dashboards \
--kibana-url "$KIBANA_ENDPOINT" --kibana-api-key "$KEY" \
--dashboard-ids id1,id2,id3
delete-dashboardsrequires--dashboard-ids; there is no "delete all" switch. To remove everything, list first and pass the full id set.- Placeholder caveat: on Elastic Serverless,
delete-dashboardsclears each dashboard into a[DELETED] …placeholder rather than removing the saved object outright. The command prints a note saying so — relay it; the user may still see[DELETED]shells inlist-dashboardsuntil removed in the Kibana UI.
Reverting alerting rules
Migrated rules are tagged obs-migration (or named [migrated] ...). obs-migrate delete-rules finds them by that marker and removes them — dry-run by default, so you can preview the exact set before deleting.
# 1. Dry run: show which migrated rules WOULD be deleted (no changes):
obs-migrate delete-rules \
--kibana-url "$KIBANA_ENDPOINT" --kibana-api-key "$KEY"
# JSON includes dry_run=true, would_delete_count, would_delete_rule_ids
# 2. Confirm: actually delete them:
obs-migrate delete-rules \
--kibana-url "$KIBANA_ENDPOINT" --kibana-api-key "$KEY" --confirm
Exit codes: 2 if the cluster is unreachable, 1 if any delete fails, 0 otherwise (including a clean dry run).
In very large spaces, delete-rules may hit its rule-listing scan limit before it sees every rule. If that happens it returns rule_listing_truncated, exits 2, and does not delete anything. Increase --max-pages and rerun the dry run before passing --confirm.
Disable instead of delete
If the user wants to stop the rules from firing without removing them (e.g. keep them for review, or re-enable later), disable rather than delete:
obs-migrate audit-rules \
--kibana-url "$KIBANA_ENDPOINT" --kibana-api-key "$KEY" --disable-enabled
audit-rules --disable-enabled disables the enabled migrated rules but leaves them in place. Use delete-rules --confirm only when the user truly wants them gone. Plain audit-rules (no flag) is read-only and reports enabled_migrated_rule_ids / disabled_migrated_rule_ids.
Full revert (dashboards + rules)
For a complete back-out, do both — preview each, then execute:
# Dashboards: list, then delete by id (see above).
# Rules: dry-run, then delete with --confirm:
obs-migrate delete-rules --kibana-url "$KIBANA_ENDPOINT" --kibana-api-key "$KEY" # preview
obs-migrate delete-rules --kibana-url "$KIBANA_ENDPOINT" --kibana-api-key "$KEY" --confirm # execute
After reverting, the user can re-run the migration cleanly (e.g. via migrate-selected-assets or migrate-all-supported-assets) without duplicate active dashboards (placeholders may still exist until UI cleanup).
Honest limits (tell the user)
- Dashboards delete by id, not by tag. There is no migration-tag filter for dashboards and no "delete all" flag — list and pass ids.
- Dashboard deletion has no dry-run or
--confirm. The safe preview iscluster list-dashboards; oncedelete-dashboards --dashboard-ids ...runs, it mutates the target. - Dashboards become
[DELETED]placeholders on Serverless, not fully removed objects — that is the command's Serverless-safe behavior, not a bug. delete-rulesonly matches migrated rules (tagobs-migration/ name[migrated] ...). Rules created another way are not in scope; hand-built Kibana rules are untouched.- Source is never modified. Reverting cleans Kibana only; the user's Grafana/Datadog assets remain as-is.
- Custom-CA / self-signed clusters:
clusteranddelete-rulesaccept--ca-cert <path>(envOBS_MIGRATE_CA_CERT) or--insecure(envOBS_MIGRATE_INSECURE, testing only).
Do NOT
- Do not run a destructive delete without confirming the scope with the user first.
- Do not claim
delete-dashboardsfully removed the objects on Serverless — it leaves[DELETED]placeholders. - Do not invent a "delete all dashboards" or "delete by tag" dashboard flag — neither exists; use ids.
- Do not use
delete-ruleswhen the user only wants rules paused — useaudit-rules --disable-enabledfor disable-without-delete. - Do not touch the source vendor to "undo" — revert is target-only.
See also
install-obs-migrate— install/doctor when the CLI is missing or not Ready.migrate-selected-assetsskill — re-migrate a chosen subset after reverting.migrate-all-supported-assetsskill — re-run a full migration after a clean revert.review-and-enable-migrated-alertsskill — audit/disable before delete when rules were enabled.obs-migrate cluster --help,obs-migrate delete-rules --help,obs-migrate audit-rules --help— authoritative flags for the installed version.https://github.com/elastic/observability-migration-platform/blob/main/docs/command-contract.md— cluster, delete-rules, and audit-rules contracts and the Serverless delete caveat (online docs / repo).