Skip to content

docs: rewrite ocp-admin deploy & use instructions #150

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
r2dedios wants to merge 3 commits into
base: main
Choose a base branch
from
+53 −24
Open

docs: rewrite ocp-admin deploy & use instructions #150

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2f8180c
docs: rewrite ocp-admin deploy & use instructions
r2dedios Aug 3, 2026
e45e990
docs: simplify deploy_and_use per review feedback
r2dedios Aug 4, 2026
52da338
docs: address review feedback on deploy_and_use
r2dedios Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 53 additions & 24 deletions ocp-admin/.catalog/deploy_and_use.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,52 +3,81 @@
Golden sources: skills/*/SKILL.md, README.md, AGENTS.md
-->

## Deploy and use

@dmartinol dmartinol Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm concerned that it will change the layout of this pack but not other packs (these files are used to build the catalog as in https://rhecosystemappeng.github.io/agentic-catalog/)

@r2dedios r2dedios Aug 4, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could update them again, but the docs update is becoming urgent

@dmartinol dmartinol Aug 4, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could update them again, but the docs update is becoming urgent

From the agentic-catalog perspective, everything is fine: the installation steps are correctly reported and the RH catalog has its own settings. I don't see the urgency, unless we want to automate the deployment of these catalog items to production environment.

@r2dedios r2dedios Aug 4, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I meant urgent because there's people trying to start using the agentic-packs but the installation docs are wrong

@TomerFi TomerFi Aug 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @dmartinol .
I think that if we update any of the catalog files in a manner such as this, we should probably update the same files in each pack at the same time.

**Note:** This skill pack is released as Developer Preview. Developer Preview features provide early access to functionality in advance of possible inclusion in a Red Hat product offering. For more information about the support scope of Red Hat Developer Preview features, see Developer Preview Support Scope.

@TomerFi TomerFi Aug 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see Developer Preview Support Scope

Can we add a link to that?


### Prerequisites

- Claude Code CLI or IDE extension (if using Claude Code)
- Podman (or Docker) for the container-based MCP servers in **`mcps.json`**
- Red Hat account with access to [cloud.redhat.com](https://cloud.redhat.com) for **cluster creation** and **inventory** flows
- **Offline token** from [OpenShift offline token](https://cloud.redhat.com/openshift/token) for Assisted Installer and OCM APIs
- For **`/cluster-report`**: valid **`KUBECONFIG`** with contexts that point at real OpenShift clusters (read-only MCP mode)
- At least one supported AI coding assistant:
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (CLI or IDE extension)

@TomerFi TomerFi Aug 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (CLI or IDE extension)
- [Claude Code](https://claude.com/product/claude-code) (CLI or IDE extension)

@TomerFi TomerFi Aug 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpicking, but I think directing users to the product pages is more consistent and appropriate. Feel free to dismiss.

- [GitHub Copilot](https://docs.github.com/en/copilot) (CLI or VS Code)

@TomerFi TomerFi Aug 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [GitHub Copilot](https://docs.github.com/en/copilot) (CLI or VS Code)
- [GitHub Copilot](https://github.com/features/copilot) (CLI or VS Code)

@TomerFi TomerFi Aug 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpicking, but I think directing users to the product pages is more consistent and appropriate. Feel free to dismiss.

- [Cursor](https://www.cursor.com/)
- [Gemini CLI](https://github.com/google-gemini/gemini-cli)

@TomerFi TomerFi Aug 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gemini CLI was shutdown in June, see deprecations table.
I'm not sure you can still install it, but if you can or you already have it installed, you can't run it. You'll get a message requsting you to install Antigravity (agy) instead. We have APPENG-5742 to track this.

I know Gemini CLI is still listed as supported in Lola, they have LobsterTrap/lola#218 for tracking Antigravity support.
But since just running Gemini CLI gives an error, and Agy is not supported yet. I would leave Gemini off this list.

- [OpenCode](https://github.com/opencode-ai/opencode)

@TomerFi TomerFi Aug 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [OpenCode](https://github.com/opencode-ai/opencode)
- [OpenCode](https://opencode.ai/)

@TomerFi TomerFi Aug 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpicking, but I think directing users to the product pages is more consistent and appropriate. Feel free to dismiss.

- [Lola](https://github.com/LobsterTrap/lola) CLI installed

@TomerFi TomerFi Aug 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [Lola](https://github.com/LobsterTrap/lola) CLI installed
- [Lola](https://docs.getlola.dev/) CLI installed

@TomerFi TomerFi Aug 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure about this one, which is better... just a thought. Anyway, it's just nitpicking, dismiss if you think we're good as-is.

- [Podman](https://podman.io/) (or Docker) — the MCP servers run as containers
- A Red Hat account with access to [cloud.redhat.com](https://cloud.redhat.com)
- For security skills (`/container-cve-validator`, `/coreos-cve-validator`, `/image-inspect`):

@TomerFi TomerFi Aug 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a comment on this PR, more of a general wondering. I haven't notice before now that we depend on local installations for running skills, and I don't think it's a practice we've taken in other plugins. Was this tested with cloud assitants, i.e. ChatGPT? @dmartinol

- [Python requests](https://pypi.org/project/requests/) (`pip install requests`)
- [regctl](https://github.com/regclient/regclient)
- [cosign](https://github.com/sigstore/cosign)
- [syft](https://github.com/anchore/syft) (optional, fallback SBOM generation)

### Step 1: Install the skill pack

```bash
# Add the Red Hat Agentic marketplace (one-time setup)
lola market add rh-agentic-collection https://raw.githubusercontent.com/RHEcosystemAppEng/agentic-catalog/main/marketplace/rh-agentic-collection.yml

@TomerFi TomerFi Aug 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
lola market add rh-agentic-collection https://raw.githubusercontent.com/RHEcosystemAppEng/agentic-catalog/main/marketplace/rh-agentic-collection.yml
lola market add rh-agentic-plugins https://raw.githubusercontent.com/RHEcosystemAppEng/agentic-catalog/main/marketplace/rh-agentic-collection.yml

@TomerFi TomerFi Aug 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we have named the underlying yaml file in the catalog rh-agentic-plugins.yml instead of the existing rh-agentic-collection.yml when we did the catalog repo seperation and name change?


### Environment setup
# Install the ocp-admin pack (replace claude-code with your AI assistant)
# Valid targets: claude-code, copilot-cli, copilot-vscode, cursor, gemini-cli, opencode
lola install ocp-admin -a claude-code
```

Variable **names** must match **`mcps.json`** (use **`${...}`** placeholders only in git; never commit secrets).
This installs the skills, the `AGENTS.md` routing file, and the `mcps.json` MCP server definitions into your project.

@TomerFi TomerFi Aug 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this line is too specific. AGENTS.md will only be created if you choose opencode as your target, for claudecode it will be CLAUDE.md. Also the mcps.json, each target as it own file name and placments, I would stay away from mentioning file names here to avoid confusion.

Also, I think it's more commonly known as an instructions file rather than a routing file.


**Assisted Installer + managed clusters** (`openshift-self-managed`, `openshift-ocm-managed`):
Verify the installation:

```bash
export OFFLINE_TOKEN="your-offline-api-token"
lola list
```

**Multi-cluster kube report** (`openshift-administration`):
### Step 2: Configure environment variables

The pack uses three MCP servers, each requiring specific credentials passed as environment variables. **Never hardcode tokens or paths — always use environment variables.**

**For cluster creation and inventory** (`openshift-self-managed`, `openshift-ocm-managed`):

1. Go to [https://cloud.redhat.com/openshift/token](https://cloud.redhat.com/openshift/token)
2. Click **Load token** → **Copy to clipboard**
3. Export it:

```bash
export KUBECONFIG="/path/to/your/kubeconfig"
export OFFLINE_TOKEN="<your-token>"
```

### Installation (Lola)
**For cluster operations and reporting** (`openshift-administration`):

```bash
lola install -f ocp-admin
export KUBECONFIG="/path/to/your/kubeconfig"
```

Module path: **`ocp-admin`** in **`marketplace/rh-agentic-collection.yml`** ([agentic-catalog](https://github.com/RHEcosystemAppEng/agentic-catalog)). See the root [README.md](../../README.md) for full prerequisites and MCP setup.
To make these persistent, add them to your shell profile (`~/.bashrc`, `~/.zshrc`).

@TomerFi TomerFi Aug 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure I would suggest users to save KUBECONFIG="/path/to/your/kubeconfig" in thier main shell profile. 😁


### Installation (Claude Code)
### Step 3: Use the skills

```bash
lola install -f ocp-admin -a claude-code
```
The pack provides 7 skills. See the [ocp-admin README](../README.md) for the full list with descriptions and usage examples.

### Uninstall

### Installation (Cursor)
Remove the skill pack from your project:

```bash
lola install -f ocp-admin -a cursor
lola uninstall ocp-admin
```

### MCP configuration
To also remove the marketplace registry:

Servers are defined in **`mcps.json`** at the pack root: Assisted Installer / OCM (`OFFLINE_TOKEN`) and read-only OpenShift API (`KUBECONFIG`). Use **`${VAR}`** placeholders only; never print token or kubeconfig contents in chat output.

**Linux vs macOS:** OpenShift MCP `podman` args may include user-namespace flags for `KUBECONFIG` mounts; adjust per the pack **README** if Podman runs in a VM.
```bash
lola market rm rh-agentic-collection

@TomerFi TomerFi Aug 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
lola market rm rh-agentic-collection
lola market rm rh-agentic-plugins

@TomerFi TomerFi Aug 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Depending on your response to #150 (comment).

```
Loading