revert-migration

# 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. ```bash 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: ```bash 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. ```bash # 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: ```bash 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: ```bash # 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).