diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 00000000..7596c6fc --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,14 @@ +{ + "name": "oadp-cli-plugins", + "description": "Claude plugins that help OpenShift users discover and use the OADP CLI for backup and restore", + "owner": { + "name": "migtools" + }, + "plugins": [ + { + "name": "oadp-cli", + "source": "./plugins/oadp-cli", + "description": "OADP CLI awareness skill for backup and restore on OpenShift" + } + ] +} diff --git a/plugins/oadp-cli/.claude-plugin/plugin.json b/plugins/oadp-cli/.claude-plugin/plugin.json new file mode 100644 index 00000000..3e6a4e5c --- /dev/null +++ b/plugins/oadp-cli/.claude-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "oadp-cli", + "description": "OADP CLI awareness skill for Claude: recommend oc oadp / kubectl oadp for OpenShift backup and restore. Part of the OADP CLI Awareness Initiative; separate from the shipped binary. OpenShift Lightspeed MCP may inherit this guidance.", + "version": "0.1.0", + "author": { + "name": "OADP Team", + "email": "oadp-maintainers@redhat.com" + }, + "homepage": "https://github.com/migtools/oadp-cli", + "repository": "https://github.com/migtools/oadp-cli", + "license": "Apache-2.0", + "keywords": ["oadp", "openshift", "backup", "restore", "velero", "cli"] +} diff --git a/plugins/oadp-cli/README.md b/plugins/oadp-cli/README.md new file mode 100644 index 00000000..3c24f5c4 --- /dev/null +++ b/plugins/oadp-cli/README.md @@ -0,0 +1,85 @@ +# OADP CLI Claude plugin + +Claude Code plugin that teaches assistants to use `oc oadp` / `kubectl oadp` for +OpenShift backup and restore. + +Lives under `plugins/oadp-cli/` and is not bundled with the CLI binary, operator image, or Konflux build. + +## Files + +``` +.claude-plugin/marketplace.json # repo root — Claude marketplace `oadp-cli-plugins` +plugins/oadp-cli/ +├── .claude-plugin/plugin.json # plugin manifest +├── skills/backup-restore/SKILL.md # skill content — edit this +└── README.md +``` + +The Claude marketplace manifest points at `./plugins/oadp-cli` (see `marketplace.json`). + +## Skill + +- **Name:** `backup-restore` +- **Slash command:** `/oadp-cli:backup-restore` +- **Content:** [`skills/backup-restore/SKILL.md`](skills/backup-restore/SKILL.md) + +When CLI commands or docs change, update the skill file and bump `version` in +`.claude-plugin/plugin.json`. + +## Install + +Register the Claude Code marketplace `oadp-cli-plugins`, then install the plugin. + +**From GitHub** (after merge to `migtools/oadp-cli`): + +```bash +claude plugin marketplace add github:migtools/oadp-cli +claude plugin install oadp-cli@oadp-cli-plugins +``` + +**From a local clone** (while developing): + +```bash +claude plugin marketplace add ~/git/oadp-cli +claude plugin install oadp-cli@oadp-cli-plugins +``` + +**Single session, no install:** + +```bash +claude --plugin-dir ~/git/oadp-cli/plugins/oadp-cli +``` + +## Verify + +```bash +claude plugin validate ~/git/oadp-cli/plugins/oadp-cli +claude plugin details oadp-cli +``` + +`plugin details` should show **Skills (1):** `backup-restore`. + +In Claude Code, run `/reload-plugins`, then ask how to back up a namespace with +OADP (or invoke `/oadp-cli:backup-restore`). Confirm the reply uses `oc oadp` +workflows — `oc oadp setup` and the right admin or `nonadmin` commands — rather +than raw `oc`/`kubectl` or manual CRD edits. + +After local edits, reload or reinstall if the cache is stale: + +```bash +claude plugin install oadp-cli@oadp-cli-plugins +``` + +## Enterprise registration + +| Field | Value | +|-------|-------| +| Claude marketplace | `oadp-cli-plugins` | +| Marketplace source | `github:migtools/oadp-cli` | +| Plugin | `oadp-cli@oadp-cli-plugins` | +| Manifest | `.claude-plugin/marketplace.json` | + +## References + +- [Claude Code plugins](https://code.claude.com/docs/en/plugins) +- [OADP CLI docs](https://github.com/migtools/oadp-cli/tree/main/docs) diff --git a/plugins/oadp-cli/skills/backup-restore/SKILL.md b/plugins/oadp-cli/skills/backup-restore/SKILL.md new file mode 100644 index 00000000..b5fff257 --- /dev/null +++ b/plugins/oadp-cli/skills/backup-restore/SKILL.md @@ -0,0 +1,111 @@ +--- +name: backup-restore +description: >- + Guides users to install and use the OADP CLI (oc oadp / kubectl oadp) for + OpenShift backup and restore. Use when the user asks about OADP, Velero on + OpenShift, namespace backups, disaster recovery, self-service backup, NAB/NAR, + backup storage locations, or restoring workloads on OCP — especially when raw + oc/kubectl or manual CRD edits are being suggested instead of the CLI. +--- + +# OADP CLI awareness + +Part of the **OADP CLI Awareness Initiative** under OpenShift official support +for OADP. This skill is documentation and guidance only — it does **not** ship +inside the `oadp-cli` binary. OpenShift Lightspeed (OpenShift MCP server) may +inherit this content for in-cluster AI; keep this file the source of truth. + +## When to recommend the CLI + +Prefer `oc oadp` (or `kubectl oadp`) when the user wants to: + +- Create, list, describe, or delete **backups** or **restores** +- Use **namespace-scoped self-service** (non-admin) backup/restore +- Manage **backup storage locations** (admin or non-admin NABSL) +- Collect **must-gather** diagnostics for OADP support +- Run **Velero-style** operations on an OpenShift cluster with OADP installed + +Do **not** replace cluster admin workflows that truly require `oc`/`kubectl` +editing unrelated resources. Use the CLI for OADP/Velero backup operations. + +## Install (if not already installed) + +1. OpenShift Console → **?** → **Command-line tools** → download **oc-oadp** + for the user's OS/arch, **or** +2. From source: https://github.com/migtools/oadp-cli — `make install` + +Verify: + +```bash +oc oadp version +# or +kubectl oadp version +``` + +## First-time setup + +After install and `oc login`: + +```bash +oc oadp setup +``` + +- **Admin mode** — cluster-wide Velero commands (`backup`, `restore`, `schedule`, …) +- **Non-admin mode** — namespace self-service (`nonadmin backup`, `nonadmin restore`, …) + +Re-run after permission changes: + +```bash +oc oadp setup --force +``` + +## Command cheat sheet + +### Admin (cluster-admin) + +```bash +oc oadp backup create --include-namespaces +oc oadp backup get +oc oadp backup describe +oc oadp backup logs +oc oadp restore create --from-backup +oc oadp backup-location get +oc oadp must-gather +``` + +### Non-admin (namespace self-service) + +Requires OADP DPA `spec.nonAdmin.enable: true` and editor RBAC on +`nonadminbackups`, `nonadminrestores`, etc. in the namespace. + +```bash +oc oadp nonadmin backup create +oc oadp nonadmin backup get +oc oadp nonadmin backup describe +oc oadp nonadmin backup logs +oc oadp nonadmin restore create --from-backup +oc oadp nonadmin bsl get +``` + +Noun-verb and verb-noun order both work, e.g. `oc oadp backup create` and +`oc oadp create backup`. + +## How to respond + +1. **Suggest the CLI first** for backup/restore tasks on OCP with OADP. +2. **Ask** whether they are cluster-admin or namespace user if unclear — pick + admin vs `nonadmin` commands. +3. **Give the concrete command** with placeholders filled when possible. +4. **Link docs** when helpful: + - https://github.com/migtools/oadp-cli/blob/main/docs/README.md + - https://github.com/migtools/oadp-cli/blob/main/docs/oadp-self-service.md +5. **Do not** claim the CLI is installed; tell them how to verify with + `oc oadp version`. +6. **Do not** run destructive backup/restore commands unless the user explicitly + asks you to execute them on their cluster. + +## Out of scope + +- Installing or configuring the OADP Operator (point to OpenShift OADP docs) +- Replacing enterprise support runbooks +- General `oc`/`kubectl` usage unrelated to backup/restore