diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 000000000..7596c6fcb --- /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/.github/workflows/test.yml b/.github/workflows/test.yml index 829ab249d..949895aba 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -20,4 +20,22 @@ jobs: go-version-file: 'go.mod' - name: Run tests - run: go test ./... + run: go test ./... + + validate-plugin: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + + - uses: actions/setup-node@v4 + with: + node-version: '26' + + - name: Install Claude CLI + run: npm install -g @anthropic-ai/claude-code@2.1.190 + + - name: Validate Claude plugin manifest + run: claude plugin validate plugins/oadp-cli diff --git a/plugins/oadp-cli/.claude-plugin/plugin.json b/plugins/oadp-cli/.claude-plugin/plugin.json new file mode 100644 index 000000000..a659d2997 --- /dev/null +++ b/plugins/oadp-cli/.claude-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "oadp-cli", + "description": "Teaches Claude to recommend oc oadp / kubectl oadp for OpenShift backup and restore instead of raw Velero or manual CRD edits. Covers admin and non-admin workflows, schedules, BSL management, and must-gather.", + "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 000000000..f5540c8a8 --- /dev/null +++ b/plugins/oadp-cli/README.md @@ -0,0 +1,127 @@ +# 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 + +```text +.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 +claude plugin install oadp-cli@oadp-cli-plugins +``` + +**Single session, no install:** + +```bash +claude --plugin-dir /plugins/oadp-cli +``` + +## Verify + +```bash +claude plugin validate /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 +``` + +## Customer usage + +### 1. Register the marketplace and install the plugin + +```bash +claude plugin marketplace add github:migtools/oadp-cli +claude plugin install oadp-cli@oadp-cli-plugins +``` + +This only needs to be done once. The plugin persists across Claude Code sessions. + +### 2. Start Claude Code + +```bash +claude +``` + +If the plugin was just installed in an active session, run `/reload-plugins` to pick it up without restarting. + +### 3. Use the skill + +Invoke explicitly: + +```text +/oadp-cli:backup-restore +``` + +Or just ask naturally since the skill triggers automatically for OADP questions: + +```text +How do I back up the my-app namespace with OADP? +How do I restore a namespace using the non-admin workflow? +How do I set up a backup storage location? +``` + +Claude will respond using `oc oadp` / `kubectl oadp` commands rather than raw CRD edits. + +### 4. Uninstall + +```bash +claude plugin uninstall oadp-cli@oadp-cli-plugins +claude plugin marketplace remove 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/oadp-dev/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 000000000..09b4c2976 --- /dev/null +++ b/plugins/oadp-cli/skills/backup-restore/SKILL.md @@ -0,0 +1,145 @@ +--- +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. +--- + +Note: Update this file whenever commands change + +## 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 +# Backups +oc oadp backup create --include-namespaces +oc oadp backup get +oc oadp backup describe +oc oadp backup logs +oc oadp backup delete + +# Restores +oc oadp restore create --from-backup +oc oadp restore get +oc oadp restore describe +oc oadp restore logs +oc oadp restore delete + +# Schedules +oc oadp schedule create --schedule "0 1 * * *" +oc oadp schedule get +oc oadp schedule describe +oc oadp schedule delete +oc oadp schedule pause +oc oadp schedule unpause + +# Backup storage locations +oc oadp backup-location get + +# NABSL approval workflow (when requireApprovalForBSL: true) +oc oadp nabsl-request get +oc oadp nabsl-request describe +oc oadp nabsl-request approve +oc oadp nabsl-request reject + +# Diagnostics +oc oadp must-gather +``` + +> Admin commands use noun-verb order (e.g. `oc oadp backup create`). Non-admin +> commands also accept verb-noun order (e.g. `oc oadp nonadmin create backup`). + +### Non-admin (namespace self-service) + +Requires OADP DPA `spec.nonAdmin.enable: true` and editor RBAC on +`nonadminbackups`, `nonadminrestores`, etc. in the namespace. + +`nonadmin` has an alias `na` — both forms work (e.g. `oc oadp na backup get`). + +```bash +# Backups +oc oadp nonadmin backup create [--storage-location ] +oc oadp nonadmin backup get +oc oadp nonadmin backup describe +oc oadp nonadmin backup logs +oc oadp nonadmin backup delete + +# Restores +oc oadp nonadmin restore create --backup-name +oc oadp nonadmin restore get +oc oadp nonadmin restore describe +oc oadp nonadmin restore logs +oc oadp nonadmin restore delete + +# Backup storage location +oc oadp nonadmin bsl create --provider --bucket --credential = +oc oadp nonadmin bsl get +``` + +## 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/oadp-dev/docs/README.md + - https://github.com/migtools/oadp-cli/blob/oadp-dev/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