revert-migration

name	revert-migration
description	Use when the user wants to "undo the migration", "delete the dashboards I just uploaded", "remove the migrated alert rules", "roll back", "clean up Kibana", or "start over" — removes some or all of the Kibana assets a migration created (uploaded dashboards and/or migrated alerting rules). Operates only on the TARGET (Kibana); it never deletes anything from the source Grafana/Datadog.

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 run delete-dashboards. Alert-rule deletion is safer by default because delete-rules is 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-dashboards requires --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-dashboards clears 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 in list-dashboards until 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 is cluster list-dashboards; once delete-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-rules only matches migrated rules (tag obs-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: cluster and delete-rules accept --ca-cert <path> (env OBS_MIGRATE_CA_CERT) or --insecure (env OBS_MIGRATE_INSECURE, testing only).

Do NOT

• Do not run a destructive delete without confirming the scope with the user first.
• Do not claim delete-dashboards fully 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-rules when the user only wants rules paused — use audit-rules --disable-enabled for 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-assets skill — re-migrate a chosen subset after reverting.
• migrate-all-supported-assets skill — re-run a full migration after a clean revert.
• review-and-enable-migrated-alerts skill — 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).