From ce5a2bc4e3e431fa6cccb3e56b75623ded521f02 Mon Sep 17 00:00:00 2001 From: ikrispin Date: Sun, 8 Feb 2026 10:08:34 +0200 Subject: [PATCH 01/12] update repo reference --- rh-developer/.claude-plugin/plugin.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rh-developer/.claude-plugin/plugin.json b/rh-developer/.claude-plugin/plugin.json index e4a41bc..067ef82 100644 --- a/rh-developer/.claude-plugin/plugin.json +++ b/rh-developer/.claude-plugin/plugin.json @@ -6,8 +6,8 @@ "name": "Red Hat Ecosystem Engineering", "email": "eco-engineering@redhat.com" }, - "homepage": "https://github.com/dmartinol/ai5-marketplaces", - "repository": "https://github.com/dmartinol/ai5-marketplaces", + "homepage": "https://github.com/RHEcosystemAppEng/agentic-collections", + "repository": "https://github.com/RHEcosystemAppEng/agentic-collections", "license": "Apache-2.0", "keywords": ["developer", "openshift", "rhel", "s2i", "containerization", "deployment", "helm", "podman"] } From 9910dbec19c706f509dff27686ee7bde7d17ec41 Mon Sep 17 00:00:00 2001 From: ikrispin Date: Sun, 8 Feb 2026 10:17:52 +0200 Subject: [PATCH 02/12] extended agent description --- rh-developer/agents/error-handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rh-developer/agents/error-handling.md b/rh-developer/agents/error-handling.md index 76aa9e0..871d56a 100644 --- a/rh-developer/agents/error-handling.md +++ b/rh-developer/agents/error-handling.md @@ -1,7 +1,7 @@ --- name: error-handling description: | - Reference guide for common error patterns and recovery strategies in OpenShift S2I deployments. Covers authentication errors (401/403), resource conflicts (409), build failures (git clone, S2I assemble, image push), deployment errors (ImagePullBackOff, CrashLoopBackOff, Pending pods), and route issues. Provides templated responses for each error type with troubleshooting steps and user options. Used by /s2i-build, /deploy, and /containerize-deploy skills. + Reference guide for common error patterns and recovery strategies in OpenShift and Kubernetes deployments. Covers authentication errors (401/403), resource conflicts (409), S2I build failures (git clone, assemble, image push), deployment errors (ImagePullBackOff, CrashLoopBackOff, Pending pods), route issues, and Helm deployment errors. Provides templated responses for each error type with troubleshooting steps and user options. Used by /s2i-build, /deploy, /helm-deploy, and /containerize-deploy skills. --- # Error Handling Patterns From 3d6f1b069a51d34565e3882b553bbe5cede472a5 Mon Sep 17 00:00:00 2001 From: ikrispin Date: Sun, 8 Feb 2026 10:39:35 +0200 Subject: [PATCH 03/12] remove error handler agent - doesn't provide extra value --- rh-developer/agents/error-handling.md | 400 ------------------ .../skills/containerize-deploy/SKILL.md | 4 - rh-developer/skills/helm-deploy/SKILL.md | 2 - rh-developer/skills/s2i-build/SKILL.md | 2 - 4 files changed, 408 deletions(-) delete mode 100644 rh-developer/agents/error-handling.md diff --git a/rh-developer/agents/error-handling.md b/rh-developer/agents/error-handling.md deleted file mode 100644 index 871d56a..0000000 --- a/rh-developer/agents/error-handling.md +++ /dev/null @@ -1,400 +0,0 @@ ---- -name: error-handling -description: | - Reference guide for common error patterns and recovery strategies in OpenShift and Kubernetes deployments. Covers authentication errors (401/403), resource conflicts (409), S2I build failures (git clone, assemble, image push), deployment errors (ImagePullBackOff, CrashLoopBackOff, Pending pods), route issues, and Helm deployment errors. Provides templated responses for each error type with troubleshooting steps and user options. Used by /s2i-build, /deploy, /helm-deploy, and /containerize-deploy skills. ---- - -# Error Handling Patterns - -## Philosophy - -1. **Detect Early** - Check prerequisites before attempting actions -2. **Explain Clearly** - Tell user exactly what went wrong -3. **Offer Options** - Provide multiple paths forward -4. **Never Leave Hanging** - Always end with actionable next step - -## Authentication Errors - -### Not logged into cluster - -**Detection:** kubernetes MCP tools fail with 401/403 or connection refused - -**Response:** -``` -I cannot connect to the OpenShift cluster. - -Please ensure you are logged in: -1. Run: oc login -2. Or set KUBECONFIG environment variable to your kubeconfig file - -After logging in, try again. -``` - -### Insufficient permissions - -**Detection:** 403 Forbidden on resource creation - -**Response:** -``` -You don't have permission to create [resource-type] in namespace [namespace]. - -Current user: [username] -Required role: edit or admin - -Options: -1. Contact your cluster admin to grant permissions -2. Try a different namespace where you have edit access -3. List available namespaces: oc projects -``` - -## Resource Conflicts - -### Resource already exists - -**Detection:** 409 Conflict on create - -**Response:** -``` -A [resource-type] named '[name]' already exists in namespace '[namespace]'. - -Current [resource-type] details: -[show key details] - -Options: -1. Update existing resource with new configuration -2. Delete existing and recreate -3. Use a different name - -What would you like to do? -``` - -## Build Errors - -### Git clone failed - -**Detection:** Build fails in git-clone phase - -**Causes:** -- Invalid URL -- Private repo without credentials -- Network issues - -**Response:** -``` -Failed to clone Git repository: [url] - -Error: [git error message] - -Troubleshooting: -1. Verify URL is correct and accessible from the cluster -2. For private repos, create a Git secret: - oc create secret generic git-creds \ - --from-literal=username= \ - --from-literal=password= \ - --type=kubernetes.io/basic-auth - oc set build-secret --source bc/[name] git-creds -3. Check if the branch '[branch]' exists - -Would you like me to help set up Git credentials? -``` - -### S2I assemble failed - -**Detection:** Build fails during assemble phase - -**Response:** -``` -S2I build failed during the assemble phase. - -Error summary: -[last 10 error lines from log] - -Common causes: -- Missing dependencies in [package.json/requirements.txt/pom.xml] -- Incompatible language version (e.g., using Node 20 features with Node 18 image) -- Build script errors - -Would you like me to: -1. Show full build logs -2. Suggest a different S2I builder image -3. Help troubleshoot the specific error -``` - -### Image push failed - -**Detection:** Build fails during push phase - -**Response:** -``` -Failed to push image to internal registry. - -Error: [push error] - -Common causes: -- Image registry storage is full -- Registry is not accessible -- ImageStream not found - -This is typically a cluster configuration issue. Contact your cluster admin. -``` - -## Deployment Errors - -### ImagePullBackOff - -**Detection:** Pod in ImagePullBackOff state - -**Response:** -``` -Pods cannot pull the container image. - -Image: [image-reference] -Error: [pull error] - -For ImageStream images: -1. Verify build completed: oc get builds -2. Check ImageStream: oc get is [name] -o yaml -3. Ensure image tag exists: oc get istag [name]:latest - -For external images: -1. Verify image exists in registry -2. Create image pull secret if needed: - oc create secret docker-registry my-pull-secret \ - --docker-server= \ - --docker-username= \ - --docker-password= - oc secrets link default my-pull-secret --for=pull -``` - -### CrashLoopBackOff - -**Detection:** Pod in CrashLoopBackOff state - -**Response:** -``` -Application is crashing on startup. - -Pod: [pod-name] -Restart count: [count] - -Recent logs: -[last 20 lines of logs] - -Common causes: -- Missing environment variables -- Database/service connection failures -- Port binding issues (app not listening on expected port) -- Application startup errors - -Would you like me to: -1. Show full pod logs -2. Check pod events for more details -3. Describe the pod configuration -4. Help set up environment variables -``` - -### Pods stuck Pending - -**Detection:** Pod stuck in Pending state for >30 seconds - -**Response:** -``` -Pods are stuck in Pending state. - -Events: -[relevant events] - -Common causes: -- Insufficient cluster resources (CPU/memory) -- No nodes match pod requirements -- PersistentVolumeClaim not bound - -Try: -1. Reduce resource requests in deployment -2. Check cluster capacity: oc describe nodes -3. Contact cluster admin if resources are exhausted -``` - -## Route Errors - -### Route not admitted - -**Detection:** Route status shows not admitted - -**Response:** -``` -Route was created but not admitted by the router. - -Route: [route-name] -Status: [route status] - -Common causes: -- Hostname conflicts with existing route -- TLS certificate issues -- Router capacity exceeded - -Check details: oc describe route [name] - -Would you like me to: -1. Try a different hostname -2. Remove TLS configuration -3. Show conflicting routes -``` - -## Helm Deployment Errors - -### Chart not found - -**Detection:** `helm install` fails with chart not found error - -**Response:** -``` -Helm chart not found at specified path. - -Path checked: [chart-path] - -Verify: -1. Chart.yaml exists in the directory -2. Path is correct (check for typos) -3. If using a repository, run: helm repo update - -Would you like me to: -1. Search for Chart.yaml in common locations -2. Create a new Helm chart for this project -3. Specify a different chart path -``` - -### Release already exists - -**Detection:** `helm install` fails with "cannot re-use a name that is still in use" - -**Response:** -``` -A Helm release named '[release-name]' already exists in namespace '[namespace]'. - -Current release: -- Status: [status] -- Chart: [chart-name]-[version] -- Updated: [timestamp] - -Options: -1. Upgrade the existing release with new values -2. Uninstall the existing release and reinstall -3. Use a different release name - -What would you like to do? -``` - -### Helm values validation failed - -**Detection:** Template rendering fails due to invalid values - -**Response:** -``` -Helm chart validation failed. - -Error: [error message] - -Common causes: -- Missing required values -- Invalid value types (string vs number) -- Template syntax errors - -Would you like me to: -1. Show the default values.yaml for reference -2. Validate your custom values file -3. Render templates locally to debug -``` - -### Helm release failed - -**Detection:** Release status shows "failed" - -**Response:** -``` -Helm release '[name]' failed to deploy. - -Release Status: failed -Revision: [revision] - -**Events:** -[relevant events from pods] - -**Pod Status:** -[pod status table] - -Options: -1. View detailed release status -2. Check pod logs for errors -3. Rollback to previous revision -4. Uninstall and retry - -What would you like to do? -``` - -### Chart dependency error - -**Detection:** Dependencies not satisfied - -**Response:** -``` -Chart has unresolved dependencies. - -Missing dependencies: -[list of missing deps] - -Run these commands to resolve: -1. cd [chart-directory] -2. helm dependency update - -Would you like me to update dependencies? -``` - -## Recovery Actions - -### Retry pattern - -For transient errors: -``` -This might be a temporary issue. - -Would you like me to retry? (yes/no) -``` - -### Partial rollback - -When later steps fail: -``` -The deployment failed, but earlier steps succeeded. - -Completed: -- [x] ImageStream created -- [x] BuildConfig created -- [x] Build completed successfully - -Failed: -- [ ] Deployment creation - -The image is available at: [image] - -Options: -1. Retry deployment only -2. Investigate the issue -3. Rollback all changes -``` - -### Full rollback - -``` -Rolling back all changes... - -Deleting resources: -- [ ] Route: [name] -- [ ] Service: [name] -- [ ] Deployment: [name] -- [ ] BuildConfig: [name] -- [ ] ImageStream: [name] - -[After deletion] -All resources cleaned up. Your namespace is back to its original state. -``` diff --git a/rh-developer/skills/containerize-deploy/SKILL.md b/rh-developer/skills/containerize-deploy/SKILL.md index 68af1b6..1e53438 100644 --- a/rh-developer/skills/containerize-deploy/SKILL.md +++ b/rh-developer/skills/containerize-deploy/SKILL.md @@ -306,8 +306,6 @@ Here's what I'll create on OpenShift: Continue to deployment? (yes/no) ``` -If build fails, follow error handling from error-handling-agent. - ### Phase 6: Pre-Deploy Summary ```markdown @@ -363,8 +361,6 @@ If build fails, follow error handling from error-handling-agent. Rollout complete! ``` -If deployment fails, follow error handling from error-handling-agent. - --- ## HELM PATH (If DEPLOYMENT_STRATEGY is "Helm") diff --git a/rh-developer/skills/helm-deploy/SKILL.md b/rh-developer/skills/helm-deploy/SKILL.md index a5a28bb..863de54 100644 --- a/rh-developer/skills/helm-deploy/SKILL.md +++ b/rh-developer/skills/helm-deploy/SKILL.md @@ -44,8 +44,6 @@ Is this the correct cluster and namespace? (yes/no) If user says "no", wait for them to switch context and tell you to continue. -If connection fails, refer to error-handling-agent for authentication error patterns. - ### Step 2: Detect Helm Chart Search for Helm charts in this order: diff --git a/rh-developer/skills/s2i-build/SKILL.md b/rh-developer/skills/s2i-build/SKILL.md index 6cf3018..a7e8e01 100644 --- a/rh-developer/skills/s2i-build/SKILL.md +++ b/rh-developer/skills/s2i-build/SKILL.md @@ -47,8 +47,6 @@ Is this the correct cluster and namespace for the build? If user says "no", wait for them to switch context and tell you to continue. -If connection fails, show error from error-handling-agent. - ### Step 2: Gather Build Information Collect required information (from /detect-project or ask user): From 8c8f2adeec2384132f9f8ae99ca95b23dde439a3 Mon Sep 17 00:00:00 2001 From: ikrispin Date: Sun, 8 Feb 2026 10:44:26 +0200 Subject: [PATCH 04/12] extract relevant knowledge from builder-images agnet to relevant doc and delete agent (doesn't provide extra value) --- .claude-plugin/marketplace.json | 2 +- rh-developer/agents/s2i-builder-images.md | 178 ---------------------- rh-developer/docs/builder-images.md | 175 ++++++++++++++++++++- 3 files changed, 175 insertions(+), 180 deletions(-) delete mode 100644 rh-developer/agents/s2i-builder-images.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 82c0c59..0268d76 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -31,7 +31,7 @@ }, "source": "./rh-developer", "category": "developer", - "agents": ["./agents/error-handling.md", "./agents/s2i-builder-images.md"], + "agents": [], "skills": "./skills" } ] diff --git a/rh-developer/agents/s2i-builder-images.md b/rh-developer/agents/s2i-builder-images.md deleted file mode 100644 index 8068532..0000000 --- a/rh-developer/agents/s2i-builder-images.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -name: s2i-builder-images -description: | - Reference table of Red Hat UBI-based S2I builder images for Node.js, Python, Java, Go, Ruby, .NET, PHP, and Perl. Includes dynamic lookup methods (Red Hat Catalog API, skopeo), version extraction patterns from project files, framework-specific recommendations (Quarkus, Spring Boot, Next.js, Django), and OpenShift built-in ImageStreams. Used by /detect-project skill to recommend appropriate builder images. Note - verify image availability before recommending as versions may change. ---- - -# S2I Builder Image Reference - -Use this reference when recommending S2I builder images to users. - -## Important: Dynamic Lookup First - -**This reference may be outdated.** Always verify image availability before recommending. - -### Verify with Skopeo (Recommended) - -```bash -# Check if an image exists and get metadata -skopeo inspect docker://registry.access.redhat.com/ubi9/nodejs-20 - -# Get specific fields -skopeo inspect docker://registry.access.redhat.com/ubi9/nodejs-20 --format '{{.Created}}' -skopeo inspect docker://registry.access.redhat.com/ubi9/nodejs-20 --format '{{.Architecture}}' - -# List all available tags -skopeo list-tags docker://registry.access.redhat.com/ubi9/nodejs-20 -``` - -**If skopeo is not installed**, prompt the user: -``` -Install with: sudo dnf install skopeo (Fedora/RHEL) - sudo apt install skopeo (Ubuntu/Debian) - brew install skopeo (macOS) -``` - -### Check Security Status (Red Hat Security Data API) - -Query CVE information (no authentication required): - -```bash -# Check for critical CVEs affecting UBI9 -curl -s "https://access.redhat.com/hydra/rest/securitydata/cve.json?product=Red%20Hat%20Universal%20Base%20Image%209&severity=critical" | jq 'length' - -# Get CVE details -curl -s "https://access.redhat.com/hydra/rest/securitydata/cve.json?product=Red%20Hat%20Universal%20Base%20Image%209&severity=critical" | jq '.[] | {cve: .CVE, severity: .severity}' -``` - -### Verify with Red Hat Catalog API (Alternative) - -```bash -# Search for available Node.js images -curl -s "https://catalog.redhat.com/api/containers/v1/repositories?filter=repository=like=ubi9/nodejs" | jq '.data[].repository' - -# Search for available Python images -curl -s "https://catalog.redhat.com/api/containers/v1/repositories?filter=repository=like=ubi9/python" | jq '.data[].repository' -``` - -### Extract Version from Project Files - -Before recommending an image, check the project's version requirements: - -| Project File | How to Extract Version | -|--------------|------------------------| -| `package.json` | `.engines.node` field | -| `requirements.txt` | `python_requires` or comments | -| `pyproject.toml` | `[project].requires-python` | -| `pom.xml` | `` or `` | -| `go.mod` | `go` directive (e.g., `go 1.21`) | -| `*.csproj` | `` (e.g., `net8.0`) | - ---- - -## Image Reference Tables - -**Quick lookup pattern:** `ubi9/{language}-{version}` (e.g., `ubi9/nodejs-20`, `ubi9/python-311`) - ---- - -## Project Detection Mapping - -### Step 1: Detect Language from Files - -| Indicator File(s) | Language | Framework | Version Source | -|-------------------|----------|-----------|----------------| -| `package.json` | Node.js | - | `.engines.node` | -| `package.json` + `next.config.js` | Node.js | Next.js | `.engines.node` | -| `package.json` + `angular.json` | Node.js | Angular | `.engines.node` | -| `pom.xml` | Java | Maven | `` or `` | -| `pom.xml` + quarkus dep | Java | Quarkus | `` (prefer 21+) | -| `pom.xml` + spring-boot dep | Java | Spring Boot | `` | -| `build.gradle` / `build.gradle.kts` | Java | Gradle | `sourceCompatibility` or `java.toolchain` | -| `requirements.txt` | Python | - | `python_requires` or shebang | -| `Pipfile` | Python | Pipenv | `[requires].python_version` | -| `pyproject.toml` | Python | Poetry/Modern | `[project].requires-python` | -| `go.mod` | Go | - | `go` directive line | -| `Gemfile` | Ruby | - | `ruby` directive or `.ruby-version` | -| `*.csproj` / `*.sln` | .NET | - | `` (e.g., net8.0 → 80) | -| `composer.json` | PHP | - | `require.php` field | -| `Cargo.toml` | Rust | - | Custom (no official S2I) | - -### Step 2: Map Version to Image - -| Language | Version Mapping | Image Pattern | -|----------|-----------------|---------------| -| Node.js | 18.x → 18, 20.x → 20, 22.x → 22 | `ubi9/nodejs-{major}` | -| Python | 3.9 → 39, 3.11 → 311, 3.12 → 312 | `ubi9/python-{majmin}` | -| Java | 11, 17, 21 (use nearest LTS) | `ubi9/openjdk-{version}` | -| Go | 1.21 → 1.21, 1.22 → 1.22 | `ubi9/go-toolset:{version}` | -| Ruby | 3.1 → 31, 3.3 → 33 | `ubi9/ruby-{majmin}` | -| .NET | net6.0 → 60, net8.0 → 80 | `ubi9/dotnet-{version}` | -| PHP | 8.0 → 80, 8.1 → 81 | `ubi9/php-{majmin}` | - -### Step 3: Verify and Fallback - -1. **Verify image exists**: `skopeo inspect docker://registry.access.redhat.com/ubi9/{image}` -2. **If version not found**: Use nearest available LTS version -3. **If no version in project**: Use current LTS (check catalog API) - ---- - -## Use-Case Aware Selection - -For advanced image selection based on use case, see the `/recommend-image` skill. - -### Quick Use-Case Matrix - -| Use Case | Variant | Priority | Example | -|----------|---------|----------|---------| -| Production | Minimal/Runtime | Security, Size | `nodejs-20-minimal` | -| Development | Full | Tools, Debug | `nodejs-20` | -| Serverless | Minimal | Startup Time | `openjdk-21-runtime` | -| Edge/IoT | Minimal | Size | `nodejs-20-minimal` | - -### Image Variants - -| Variant | Description | Has Build Tools | Size | -|---------|-------------|-----------------|------| -| Full | Complete development environment | Yes | Largest | -| Minimal | Essential packages only | Limited | Medium | -| Runtime | Runtime only, no build tools | No | Smallest | - -**Availability by language:** - -| Language | Full | Minimal | Runtime | -|----------|------|---------|---------| -| Node.js | `nodejs-{ver}` | `nodejs-{ver}-minimal` | - | -| Python | `python-{ver}` | - | - | -| Java | `openjdk-{ver}` | - | `openjdk-{ver}-runtime` | -| Go | `go-toolset:{ver}` | - | (produces static binary) | -| .NET | `dotnet-{ver}` | - | `dotnet-{ver}-runtime` | -| Ruby | `ruby-{ver}` | - | - | -| PHP | `php-{ver}` | - | - | - -### When to Recommend Each Variant - -**Full variant:** -- User needs to compile native extensions -- Development/debugging environment -- CI/CD build stages - -**Minimal variant:** -- Production deployments -- Security-focused environments -- When size matters but some tools needed - -**Runtime variant:** -- Pre-compiled applications (JARs, .NET assemblies) -- Maximum security posture -- Smallest possible footprint - ---- - -## Python S2I Entry Point Requirements - -**Quick reference:** -- Default entry point: `app.py` (works without configuration) -- Custom entry points require: `gunicorn` + `APP_MODULE` environment variable -- Format: `APP_MODULE=module:variable` (e.g., `main:app`) diff --git a/rh-developer/docs/builder-images.md b/rh-developer/docs/builder-images.md index e36c228..dc4e091 100644 --- a/rh-developer/docs/builder-images.md +++ b/rh-developer/docs/builder-images.md @@ -1,9 +1,119 @@ -# S2I Builder Image Reference Tables +# S2I Builder Image Reference + +Use this reference when recommending S2I builder images to users. > **Note:** Versions marked "Recommended" may change. Always verify with `skopeo inspect` before use. Prefer matching the project's version requirements over these defaults. For use-case-aware image selection, use the `/recommend-image` skill. +--- + +## Dynamic Lookup and Verification + +**This reference may be outdated.** Always verify image availability before recommending. + +### Verify with Skopeo (Recommended) + +```bash +# Check if an image exists and get metadata +skopeo inspect docker://registry.access.redhat.com/ubi9/nodejs-20 + +# Get specific fields +skopeo inspect docker://registry.access.redhat.com/ubi9/nodejs-20 --format '{{.Created}}' +skopeo inspect docker://registry.access.redhat.com/ubi9/nodejs-20 --format '{{.Architecture}}' + +# List all available tags +skopeo list-tags docker://registry.access.redhat.com/ubi9/nodejs-20 +``` + +**If skopeo is not installed**, prompt the user: +``` +Install with: sudo dnf install skopeo (Fedora/RHEL) + sudo apt install skopeo (Ubuntu/Debian) + brew install skopeo (macOS) +``` + +### Check Security Status (Red Hat Security Data API) + +Query CVE information (no authentication required): + +```bash +# Check for critical CVEs affecting UBI9 +curl -s "https://access.redhat.com/hydra/rest/securitydata/cve.json?product=Red%20Hat%20Universal%20Base%20Image%209&severity=critical" | jq 'length' + +# Get CVE details +curl -s "https://access.redhat.com/hydra/rest/securitydata/cve.json?product=Red%20Hat%20Universal%20Base%20Image%209&severity=critical" | jq '.[] | {cve: .CVE, severity: .severity}' +``` + +### Verify with Red Hat Catalog API (Alternative) + +```bash +# Search for available Node.js images +curl -s "https://catalog.redhat.com/api/containers/v1/repositories?filter=repository=like=ubi9/nodejs" | jq '.data[].repository' + +# Search for available Python images +curl -s "https://catalog.redhat.com/api/containers/v1/repositories?filter=repository=like=ubi9/python" | jq '.data[].repository' +``` + +--- + +## Project Detection and Version Mapping + +### Extract Version from Project Files + +Before recommending an image, check the project's version requirements: + +| Project File | How to Extract Version | +|--------------|------------------------| +| `package.json` | `.engines.node` field | +| `requirements.txt` | `python_requires` or comments | +| `pyproject.toml` | `[project].requires-python` | +| `pom.xml` | `` or `` | +| `go.mod` | `go` directive (e.g., `go 1.21`) | +| `*.csproj` | `` (e.g., `net8.0`) | + +### Detect Language from Files + +| Indicator File(s) | Language | Framework | Version Source | +|-------------------|----------|-----------|----------------| +| `package.json` | Node.js | - | `.engines.node` | +| `package.json` + `next.config.js` | Node.js | Next.js | `.engines.node` | +| `package.json` + `angular.json` | Node.js | Angular | `.engines.node` | +| `pom.xml` | Java | Maven | `` or `` | +| `pom.xml` + quarkus dep | Java | Quarkus | `` (prefer 21+) | +| `pom.xml` + spring-boot dep | Java | Spring Boot | `` | +| `build.gradle` / `build.gradle.kts` | Java | Gradle | `sourceCompatibility` or `java.toolchain` | +| `requirements.txt` | Python | - | `python_requires` or shebang | +| `Pipfile` | Python | Pipenv | `[requires].python_version` | +| `pyproject.toml` | Python | Poetry/Modern | `[project].requires-python` | +| `go.mod` | Go | - | `go` directive line | +| `Gemfile` | Ruby | - | `ruby` directive or `.ruby-version` | +| `*.csproj` / `*.sln` | .NET | - | `` (e.g., net8.0 → 80) | +| `composer.json` | PHP | - | `require.php` field | +| `Cargo.toml` | Rust | - | Custom (no official S2I) | + +### Map Version to Image + +**Quick lookup pattern:** `ubi9/{language}-{version}` (e.g., `ubi9/nodejs-20`, `ubi9/python-311`) + +| Language | Version Mapping | Image Pattern | +|----------|-----------------|---------------| +| Node.js | 18.x → 18, 20.x → 20, 22.x → 22 | `ubi9/nodejs-{major}` | +| Python | 3.9 → 39, 3.11 → 311, 3.12 → 312 | `ubi9/python-{majmin}` | +| Java | 11, 17, 21 (use nearest LTS) | `ubi9/openjdk-{version}` | +| Go | 1.21 → 1.21, 1.22 → 1.22 | `ubi9/go-toolset:{version}` | +| Ruby | 3.1 → 31, 3.3 → 33 | `ubi9/ruby-{majmin}` | +| .NET | net6.0 → 60, net8.0 → 80 | `ubi9/dotnet-{version}` | +| PHP | 8.0 → 80, 8.1 → 81 | `ubi9/php-{majmin}` | + +### Verify and Fallback + +1. **Verify image exists**: `skopeo inspect docker://registry.access.redhat.com/ubi9/{image}` +2. **If version not found**: Use nearest available LTS version +3. **If no version in project**: Use current LTS (check catalog API) + +--- + ## Red Hat UBI-based Images ### Node.js @@ -74,6 +184,58 @@ For use-case-aware image selection, use the `/recommend-image` skill. |---------|-------|-------| | 5.32 | `registry.access.redhat.com/ubi9/perl-532` | | +--- + +## Image Variants and Use-Case Selection + +### Quick Use-Case Matrix + +| Use Case | Variant | Priority | Example | +|----------|---------|----------|---------| +| Production | Minimal/Runtime | Security, Size | `nodejs-20-minimal` | +| Development | Full | Tools, Debug | `nodejs-20` | +| Serverless | Minimal | Startup Time | `openjdk-21-runtime` | +| Edge/IoT | Minimal | Size | `nodejs-20-minimal` | + +### Image Variants + +| Variant | Description | Has Build Tools | Size | +|---------|-------------|-----------------|------| +| Full | Complete development environment | Yes | Largest | +| Minimal | Essential packages only | Limited | Medium | +| Runtime | Runtime only, no build tools | No | Smallest | + +**Availability by language:** + +| Language | Full | Minimal | Runtime | +|----------|------|---------|---------| +| Node.js | `nodejs-{ver}` | `nodejs-{ver}-minimal` | - | +| Python | `python-{ver}` | - | - | +| Java | `openjdk-{ver}` | - | `openjdk-{ver}-runtime` | +| Go | `go-toolset:{ver}` | - | (produces static binary) | +| .NET | `dotnet-{ver}` | - | `dotnet-{ver}-runtime` | +| Ruby | `ruby-{ver}` | - | - | +| PHP | `php-{ver}` | - | - | + +### When to Recommend Each Variant + +**Full variant:** +- User needs to compile native extensions +- Development/debugging environment +- CI/CD build stages + +**Minimal variant:** +- Production deployments +- Security-focused environments +- When size matters but some tools needed + +**Runtime variant:** +- Pre-compiled applications (JARs, .NET assemblies) +- Maximum security posture +- Smallest possible footprint + +--- + ## OpenShift Built-in ImageStreams These are often pre-configured in OpenShift clusters under the `openshift` namespace: @@ -94,6 +256,8 @@ from: name: nodejs:20-ubi9 ``` +--- + ## Framework-Specific Recommendations ### Quarkus (Java) @@ -115,3 +279,12 @@ from: ### Express.js (Node.js) - Use: `registry.access.redhat.com/ubi9/nodejs-18` or higher - Ensure `npm start` script is defined in `package.json` + +--- + +## Python S2I Entry Point Requirements + +**Quick reference:** +- Default entry point: `app.py` (works without configuration) +- Custom entry points require: `gunicorn` + `APP_MODULE` environment variable +- Format: `APP_MODULE=module:variable` (e.g., `main:app`) From 2f057a9209443dc208d63109f8c5f2c03125dae4 Mon Sep 17 00:00:00 2001 From: ikrispin Date: Sun, 8 Feb 2026 11:04:55 +0200 Subject: [PATCH 05/12] clarify systemd template and standardize tool naming --- .../skills/containerize-deploy/SKILL.md | 2 +- rh-developer/skills/helm-deploy/SKILL.md | 26 +++++++++---------- .../systemd/systemd-container-rootful.service | 2 +- .../systemd-container-rootless.service | 2 +- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/rh-developer/skills/containerize-deploy/SKILL.md b/rh-developer/skills/containerize-deploy/SKILL.md index 1e53438..107a7ff 100644 --- a/rh-developer/skills/containerize-deploy/SKILL.md +++ b/rh-developer/skills/containerize-deploy/SKILL.md @@ -479,5 +479,5 @@ All tools from child skills: | Connect | `resources_list` (namespaces) | | Build | `resources_create_or_update`, `pod_logs`, `events_list` | | Deploy | `resources_create_or_update`, `pod_list`, `pod_logs` | -| Helm | `helm_install`, `helm_upgrade`, `helm_status`, `helm_list`, `pod_list` | +| Helm | `helm_install`, `helm_upgrade`, `helm_status`, `helm_list`, `pods_list` | | Rollback | `resources_delete`, `helm_uninstall`, `helm_rollback` | diff --git a/rh-developer/skills/helm-deploy/SKILL.md b/rh-developer/skills/helm-deploy/SKILL.md index 863de54..69de16e 100644 --- a/rh-developer/skills/helm-deploy/SKILL.md +++ b/rh-developer/skills/helm-deploy/SKILL.md @@ -158,7 +158,7 @@ Before installing, check if a release with the same name exists: ```markdown ## Checking for Existing Release... -[Use mcp_kubernetes_helm_list to check] +[Use helm_list to check] ``` **If release exists:** @@ -269,7 +269,7 @@ helm install [release-name] [chart-path] -n [namespace] [--set options] ### Step 7: Execute Deployment -Use kubernetes MCP `mcp_kubernetes_helm_install` or `mcp_kubernetes_helm_upgrade`: +Use kubernetes MCP `helm_install` or `helm_upgrade`: ```markdown ## Deploying with Helm... @@ -296,7 +296,7 @@ Waiting for resources to be ready... --- ``` -Monitor pod status using `mcp_kubernetes_pods_list_in_namespace` until pods are ready or timeout. +Monitor pod status using `pods_list_in_namespace` until pods are ready or timeout. ### Step 8: Deployment Complete @@ -353,16 +353,16 @@ Your application is live! | Tool | Purpose | |------|---------| -| `mcp_kubernetes_helm_list` | Check existing releases | -| `mcp_kubernetes_helm_install` | Install new release | -| `mcp_kubernetes_helm_upgrade` | Upgrade existing release | -| `mcp_kubernetes_helm_status` | Get release status | -| `mcp_kubernetes_helm_history` | Get release history | -| `mcp_kubernetes_helm_rollback` | Rollback to revision | -| `mcp_kubernetes_helm_uninstall` | Remove release | -| `mcp_kubernetes_pods_list_in_namespace` | Monitor pod status | -| `mcp_kubernetes_pods_log` | View pod logs | -| `mcp_kubernetes_events_list` | Check for errors | +| `helm_list` | Check existing releases | +| `helm_install` | Install new release | +| `helm_upgrade` | Upgrade existing release | +| `helm_status` | Get release status | +| `helm_history` | Get release history | +| `helm_rollback` | Rollback to revision | +| `helm_uninstall` | Remove release | +| `pods_list_in_namespace` | Monitor pod status | +| `pods_log` | View pod logs | +| `events_list` | Check for errors | ## Output Variables diff --git a/rh-developer/templates/systemd/systemd-container-rootful.service b/rh-developer/templates/systemd/systemd-container-rootful.service index 75aed8b..c1e8fe8 100644 --- a/rh-developer/templates/systemd/systemd-container-rootful.service +++ b/rh-developer/templates/systemd/systemd-container-rootful.service @@ -3,7 +3,7 @@ # # Variables to replace: # ${APP_NAME} - Application name -# ${PORT} - Container port mapping (host:container) +# ${PORT} - Port number (used for both host and container binding) # ${IMAGE} - Container image reference [Unit] diff --git a/rh-developer/templates/systemd/systemd-container-rootless.service b/rh-developer/templates/systemd/systemd-container-rootless.service index e4185e2..ca9dc37 100644 --- a/rh-developer/templates/systemd/systemd-container-rootless.service +++ b/rh-developer/templates/systemd/systemd-container-rootless.service @@ -3,7 +3,7 @@ # # Variables to replace: # ${APP_NAME} - Application name -# ${PORT} - Container port mapping (host:container) +# ${PORT} - Port number (used for both host and container binding) # ${IMAGE} - Container image reference [Unit] From 20505f04cc2e1b29e8c92d6fb743638d5c3bcd28 Mon Sep 17 00:00:00 2001 From: ikrispin Date: Sun, 8 Feb 2026 11:08:41 +0200 Subject: [PATCH 06/12] remove language specific var from template --- rh-developer/templates/systemd/systemd-native.service | 1 - 1 file changed, 1 deletion(-) diff --git a/rh-developer/templates/systemd/systemd-native.service b/rh-developer/templates/systemd/systemd-native.service index 9e3eadc..c55cfc0 100644 --- a/rh-developer/templates/systemd/systemd-native.service +++ b/rh-developer/templates/systemd/systemd-native.service @@ -23,7 +23,6 @@ Wants=network-online.target Type=simple User=${SERVICE_USER} WorkingDirectory=${APP_PATH} -Environment=NODE_ENV=production Environment=PORT=${PORT} ExecStart=${START_COMMAND} Restart=always From e8a460a7f0baf7cea8f76c2b8399cf4fe29edff1 Mon Sep 17 00:00:00 2001 From: ikrispin Date: Sun, 8 Feb 2026 11:27:03 +0200 Subject: [PATCH 07/12] add prerequisites doc and env validation skill --- rh-developer/docs/prerequisites.md | 185 ++++++++++++++ .../skills/validate-environment/SKILL.md | 234 ++++++++++++++++++ 2 files changed, 419 insertions(+) create mode 100644 rh-developer/docs/prerequisites.md create mode 100644 rh-developer/skills/validate-environment/SKILL.md diff --git a/rh-developer/docs/prerequisites.md b/rh-developer/docs/prerequisites.md new file mode 100644 index 0000000..0cb5b3e --- /dev/null +++ b/rh-developer/docs/prerequisites.md @@ -0,0 +1,185 @@ +# Prerequisites + +This document lists all tools required by the rh-developer agentic collection. + +## Required Tools by Skill + +| Skill | Required Tools | Optional Tools | +|-------|----------------|----------------| +| `/detect-project` | `git` | - | +| `/s2i-build` | `oc` | `git` | +| `/deploy` | `oc` | - | +| `/helm-deploy` | `oc`, `helm` | - | +| `/containerize-deploy` | `oc` | `git`, `helm` | +| `/rhel-deploy` | `ssh`, `podman` or `docker` | `git`, `dnf` | +| `/recommend-image` | - | `skopeo`, `curl`, `jq` | + +## Tool Reference + +### OpenShift CLI (oc) + +**Required for:** Cluster operations, S2I builds, deployments + +```bash +# Check installation +oc version + +# Installation +# Download from: https://mirror.openshift.com/pub/openshift-v4/clients/ocp/latest/ +# Or via package manager: +sudo dnf install openshift-clients # Fedora/RHEL +brew install openshift-cli # macOS +``` + +### Helm + +**Required for:** Helm chart deployments + +```bash +# Check installation +helm version + +# Installation +curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash +# Or via package manager: +sudo dnf install helm # Fedora/RHEL +brew install helm # macOS +``` + +### Podman + +**Required for:** Container builds, RHEL container deployments + +```bash +# Check installation +podman --version + +# Installation +sudo dnf install podman # Fedora/RHEL/CentOS +sudo apt install podman # Ubuntu/Debian +brew install podman # macOS +``` + +### Docker (alternative to Podman) + +**Required for:** Container builds (if Podman not available) + +```bash +# Check installation +docker --version + +# Installation +# See: https://docs.docker.com/engine/install/ +``` + +### Skopeo + +**Required for:** Image inspection, tag verification + +```bash +# Check installation +skopeo --version + +# Installation +sudo dnf install skopeo # Fedora/RHEL/CentOS +sudo apt install skopeo # Ubuntu/Debian +brew install skopeo # macOS +``` + +### Git + +**Required for:** Repository cloning + +```bash +# Check installation +git --version + +# Installation +sudo dnf install git # Fedora/RHEL/CentOS +sudo apt install git # Ubuntu/Debian +brew install git # macOS (or Xcode Command Line Tools) +``` + +### SSH + +**Required for:** RHEL remote deployments + +```bash +# Check installation +ssh -V + +# Usually pre-installed on Linux/macOS +# Windows: Use OpenSSH or WSL +``` + +### curl and jq + +**Required for:** API calls and JSON parsing + +```bash +# Check installation +curl --version +jq --version + +# Installation +sudo dnf install curl jq # Fedora/RHEL/CentOS +sudo apt install curl jq # Ubuntu/Debian +brew install curl jq # macOS +``` + +## Cluster Requirements + +### OpenShift Cluster Access + +For S2I builds and deployments, you need: + +1. **Logged in to cluster:** + ```bash + oc login + # or + oc login --token= --server= + ``` + +2. **Namespace with edit permissions:** + ```bash + # Verify access + oc auth can-i create deployments + oc auth can-i create buildconfigs + ``` + +3. **Image registry accessible:** + ```bash + # Verify internal registry + oc get route -n openshift-image-registry + ``` + +### RHEL/Fedora Host Access + +For RHEL deployments, you need: + +1. **SSH access to target host:** + ```bash + ssh user@target-host + ``` + +2. **sudo privileges on target** (for systemd services) + +3. **Firewall ports open** (for application access) + +## Quick Validation + +Run these commands to check your environment: + +```bash +# Core tools +which oc helm podman git ssh curl jq skopeo + +# Cluster connection (if using OpenShift) +oc whoami +oc project + +# Container runtime +podman info || docker info +``` + +Use the `/validate-environment` skill for automated checking. diff --git a/rh-developer/skills/validate-environment/SKILL.md b/rh-developer/skills/validate-environment/SKILL.md new file mode 100644 index 0000000..1248afb --- /dev/null +++ b/rh-developer/skills/validate-environment/SKILL.md @@ -0,0 +1,234 @@ +--- +name: validate-environment +description: | + Check and report the status of required tools and environment for rh-developer skills. Validates tool installation (oc, helm, podman, git, skopeo, etc.), cluster connectivity, and permissions. Use this skill before running other deployment skills to ensure prerequisites are met. Triggers on /validate-environment command or when user asks to check their environment setup. +user_invocable: true +--- + +# Validate Environment Skill + +Check that required tools and environment are properly configured. + +## Trigger + +- User types `/validate-environment` +- User asks "check my environment", "what tools do I need", "am I ready to deploy" + +## Input Parameters + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `TARGET` | What to validate: `all`, `openshift`, `rhel`, `containers` | `all` | + +## Execution Flow + +### Step 1: Determine Validation Scope + +Ask user if not clear: + +```markdown +## Environment Validation + +What would you like to validate? + +1. **All** - Check all tools and connections +2. **OpenShift** - Check oc, helm, cluster connectivity +3. **RHEL/Containers** - Check podman, ssh, container tools +4. **Minimal** - Just check core tools (git, curl) + +Select an option (1-4): +``` + +### Step 2: Check Core Tools + +Run these checks using Bash: + +```bash +# Check each tool and capture version +check_tool() { + if command -v "$1" &> /dev/null; then + echo "INSTALLED: $1 ($($1 --version 2>&1 | head -1))" + else + echo "MISSING: $1" + fi +} +``` + +**Tools to check:** + +| Tool | Check Command | Required For | +|------|---------------|--------------| +| `git` | `git --version` | Repository cloning | +| `curl` | `curl --version` | API calls | +| `jq` | `jq --version` | JSON parsing | +| `oc` | `oc version --client` | OpenShift operations | +| `helm` | `helm version --short` | Helm deployments | +| `podman` | `podman --version` | Container builds | +| `docker` | `docker --version` | Container builds (alt) | +| `skopeo` | `skopeo --version` | Image inspection | +| `ssh` | `ssh -V` | RHEL deployments | + +### Step 3: Check OpenShift Connectivity (if TARGET includes openshift) + +```bash +# Check if logged in +oc whoami + +# Check current project +oc project + +# Check permissions +oc auth can-i create deployments +oc auth can-i create buildconfigs +oc auth can-i create imagestreams +``` + +### Step 4: Check Container Runtime (if TARGET includes containers) + +```bash +# Check Podman +podman info --format '{{.Host.OS}} {{.Host.Arch}}' + +# Or Docker +docker info --format '{{.OSType}} {{.Architecture}}' + +# Check if can pull images +podman pull --quiet registry.access.redhat.com/ubi9/ubi-minimal:latest || echo "WARN: Cannot pull images" +``` + +### Step 5: Generate Report + +Present results in this format: + +```markdown +## Environment Validation Report + +### Core Tools + +| Tool | Status | Version | +|------|--------|---------| +| git | OK | 2.43.0 | +| curl | OK | 8.5.0 | +| jq | OK | 1.7.1 | +| oc | OK | 4.14.0 | +| helm | OK | 3.14.0 | +| podman | OK | 4.9.0 | +| skopeo | MISSING | - | +| ssh | OK | OpenSSH_9.6 | + +### OpenShift Cluster + +| Check | Status | Details | +|-------|--------|---------| +| Logged in | OK | user@cluster.example.com | +| Project | OK | my-project | +| Create Deployments | OK | Allowed | +| Create BuildConfigs | OK | Allowed | +| Create ImageStreams | OK | Allowed | + +### Container Runtime + +| Check | Status | Details | +|-------|--------|---------| +| Runtime | OK | Podman 4.9.0 | +| Pull images | OK | Can access registries | + +--- + +### Summary + +**Ready for:** /detect-project, /s2i-build, /deploy, /helm-deploy, /containerize-deploy + +**Missing tools for:** +- /recommend-image (dynamic mode) - Install: `sudo dnf install skopeo` + +### Quick Fix Commands + +```bash +# Install missing tools +sudo dnf install skopeo +``` +``` + +### Step 6: Offer Next Steps + +```markdown +## Next Steps + +Your environment is ready for deployment. + +Would you like to: +1. Run `/detect-project` to analyze your application +2. Run `/containerize-deploy` for end-to-end deployment +3. See detailed prerequisites documentation + +Select an option or describe what you'd like to do: +``` + +--- + +## Validation Status Indicators + +| Status | Meaning | +|--------|---------| +| OK | Tool installed and working | +| MISSING | Tool not found in PATH | +| ERROR | Tool found but not working | +| WARN | Optional tool missing | +| SKIP | Check skipped (not in scope) | + +## Error Handling + +### Tool Not Found + +```markdown +**Missing: [tool-name]** + +This tool is required for [skill-names]. + +Install with: +- Fedora/RHEL: `sudo dnf install [package]` +- Ubuntu/Debian: `sudo apt install [package]` +- macOS: `brew install [package]` +``` + +### Cluster Connection Failed + +```markdown +**OpenShift cluster not accessible** + +You are not logged in to an OpenShift cluster. + +To connect: +1. Get login command from OpenShift console +2. Run: `oc login ` + +Or set KUBECONFIG: +```bash +export KUBECONFIG=/path/to/kubeconfig +``` +``` + +### Permission Denied + +```markdown +**Insufficient permissions in namespace [namespace]** + +You need 'edit' or 'admin' role to deploy applications. + +Options: +1. Contact cluster admin for permissions +2. Switch to a different namespace: `oc project ` +3. Create a new project: `oc new-project ` +``` + +--- + +## Output Variables + +| Variable | Description | Example | +|----------|-------------|---------| +| `TOOLS_OK` | List of installed tools | `git,curl,oc,helm` | +| `TOOLS_MISSING` | List of missing tools | `skopeo` | +| `CLUSTER_CONNECTED` | OpenShift connectivity | `true` / `false` | +| `READY_FOR_SKILLS` | Skills that can run | `/deploy,/s2i-build` | From 6a4b130d17276341ee78021c0d60d670c45f654d Mon Sep 17 00:00:00 2001 From: ikrispin Date: Sun, 8 Feb 2026 11:36:52 +0200 Subject: [PATCH 08/12] add parsable headers to docs --- rh-developer/docs/builder-images.md | 18 +++++++++++++++ rh-developer/docs/dynamic-validation.md | 14 ++++++++++++ rh-developer/docs/image-selection-criteria.md | 14 ++++++++++++ rh-developer/docs/prerequisites.md | 22 +++++++++++++++++++ rh-developer/docs/python-s2i-entrypoints.md | 14 ++++++++++++ rh-developer/docs/rhel-deployment.md | 18 +++++++++++++++ rh-developer/docs/session-state-patterns.md | 6 +++++ 7 files changed, 106 insertions(+) diff --git a/rh-developer/docs/builder-images.md b/rh-developer/docs/builder-images.md index dc4e091..6561c5c 100644 --- a/rh-developer/docs/builder-images.md +++ b/rh-developer/docs/builder-images.md @@ -1,3 +1,21 @@ +--- +title: S2I Builder Image Reference +category: containers +sources: + - title: Red Hat Container Catalog + url: https://catalog.redhat.com/software/containers/search + sections: UBI images, S2I builders + date_accessed: 2026-02-08 + - title: OpenShift Source-to-Image (S2I) + url: https://docs.openshift.com/container-platform/latest/openshift_images/using_images/using-s21-images.html + sections: S2I builder images, Language detection + date_accessed: 2026-02-08 + - title: Red Hat Universal Base Images + url: https://developers.redhat.com/products/rhel/ubi + sections: UBI9 images, Language runtimes + date_accessed: 2026-02-08 +--- + # S2I Builder Image Reference Use this reference when recommending S2I builder images to users. diff --git a/rh-developer/docs/dynamic-validation.md b/rh-developer/docs/dynamic-validation.md index a1b754c..a027f0c 100644 --- a/rh-developer/docs/dynamic-validation.md +++ b/rh-developer/docs/dynamic-validation.md @@ -1,3 +1,17 @@ +--- +title: Dynamic Image Validation Reference +category: containers +sources: + - title: Skopeo Documentation + url: https://github.com/containers/skopeo + sections: Inspecting images, Copying images + date_accessed: 2026-02-08 + - title: Red Hat Security Data API + url: https://access.redhat.com/documentation/en-us/red_hat_security_data_api/1.0 + sections: CVE queries, Product filtering + date_accessed: 2026-02-08 +--- + # Dynamic Image Validation Reference This document provides detailed patterns for validating container images using Skopeo and the Red Hat Security Data API. diff --git a/rh-developer/docs/image-selection-criteria.md b/rh-developer/docs/image-selection-criteria.md index 6c4cb1a..184b7f5 100644 --- a/rh-developer/docs/image-selection-criteria.md +++ b/rh-developer/docs/image-selection-criteria.md @@ -1,3 +1,17 @@ +--- +title: Image Selection Criteria Reference +category: containers +sources: + - title: Red Hat Container Best Practices + url: https://developers.redhat.com/articles/2023/02/14/best-practices-building-images-pass-red-hat-container-certification + sections: Image sizing, Security considerations + date_accessed: 2026-02-08 + - title: OpenShift Image Guidelines + url: https://docs.openshift.com/container-platform/latest/openshift_images/create-images.html + sections: Image creation, Optimization + date_accessed: 2026-02-08 +--- + # Image Selection Criteria Reference This document provides detailed criteria for selecting the optimal container image based on use case requirements. diff --git a/rh-developer/docs/prerequisites.md b/rh-developer/docs/prerequisites.md index 0cb5b3e..c1d1b70 100644 --- a/rh-developer/docs/prerequisites.md +++ b/rh-developer/docs/prerequisites.md @@ -1,3 +1,25 @@ +--- +title: Prerequisites +category: setup +sources: + - title: OpenShift CLI (oc) Installation + url: https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/getting-started-cli.html + sections: Installing the CLI, Logging in + date_accessed: 2026-02-08 + - title: Helm Installation Guide + url: https://helm.sh/docs/intro/install/ + sections: From script, From package managers + date_accessed: 2026-02-08 + - title: Podman Installation + url: https://podman.io/docs/installation + sections: Linux, macOS, Windows + date_accessed: 2026-02-08 + - title: Skopeo Installation + url: https://github.com/containers/skopeo/blob/main/install.md + sections: Distribution packages, Building from source + date_accessed: 2026-02-08 +--- + # Prerequisites This document lists all tools required by the rh-developer agentic collection. diff --git a/rh-developer/docs/python-s2i-entrypoints.md b/rh-developer/docs/python-s2i-entrypoints.md index 015bb58..bb29398 100644 --- a/rh-developer/docs/python-s2i-entrypoints.md +++ b/rh-developer/docs/python-s2i-entrypoints.md @@ -1,3 +1,17 @@ +--- +title: Python S2I Entry Point Requirements +category: containers +sources: + - title: UBI Python S2I Builder + url: https://github.com/sclorg/s2i-python-container + sections: Run script logic, APP_MODULE configuration + date_accessed: 2026-02-08 + - title: Red Hat Python S2I Documentation + url: https://catalog.redhat.com/software/containers/ubi9/python-311 + sections: Environment variables, Startup behavior + date_accessed: 2026-02-08 +--- + # Python S2I Entry Point Requirements The UBI Python S2I builder has specific startup logic that must be understood to avoid deployment failures. diff --git a/rh-developer/docs/rhel-deployment.md b/rh-developer/docs/rhel-deployment.md index 36f9848..06eda27 100644 --- a/rh-developer/docs/rhel-deployment.md +++ b/rh-developer/docs/rhel-deployment.md @@ -1,3 +1,21 @@ +--- +title: RHEL Deployment Reference +category: deployment +sources: + - title: RHEL System Administrator's Guide - systemd + url: https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_basic_system_settings/managing-system-services-with-systemctl_configuring-basic-system-settings + sections: Managing services, Unit files + date_accessed: 2026-02-08 + - title: RHEL SELinux Guide + url: https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/using_selinux + sections: Contexts, Port labeling + date_accessed: 2026-02-08 + - title: RHEL Firewall Configuration + url: https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_firewalls_and_packet_filters + sections: firewalld, Opening ports + date_accessed: 2026-02-08 +--- + # RHEL Deployment Reference Reference material for deploying applications to standalone RHEL systems. diff --git a/rh-developer/docs/session-state-patterns.md b/rh-developer/docs/session-state-patterns.md index 28fee1b..11606ec 100644 --- a/rh-developer/docs/session-state-patterns.md +++ b/rh-developer/docs/session-state-patterns.md @@ -1,3 +1,9 @@ +--- +title: Session State Patterns +category: architecture +sources: [] +--- + # Session State Patterns This reference defines the state management patterns used across deployment skills. From 9ed33c9d6ecbaba92f8df2bd6fdc6e8ea06ce9c4 Mon Sep 17 00:00:00 2001 From: ikrispin Date: Sun, 8 Feb 2026 11:42:36 +0200 Subject: [PATCH 09/12] docs: add simple rh-developer readme --- rh-developer/README.md | 35 ++++++++++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/rh-developer/README.md b/rh-developer/README.md index 4830226..18d291d 100644 --- a/rh-developer/README.md +++ b/rh-developer/README.md @@ -1,6 +1,35 @@ # Red Hat Developer Agentic Pack -Development tools and skills for building applications on Red Hat platforms. This pack provides automation capabilities for development workflows including application deployment, CI/CD integration, containerization, and developer productivity. +A Claude Code plugin for building and deploying applications on Red Hat platforms. -**Persona**: Developer -**Marketplaces**: Claude Code, Cursor +## Skills + +| Command | Description | +| ------------------------ | ------------------------------------------------------------------------------------------ | +| `/detect-project` | Analyze project to detect language, framework, and version | +| `/recommend-image` | Recommend optimal S2I builder or base image | +| `/s2i-build` | Build container images using Source-to-Image on OpenShift | +| `/deploy` | Deploy container images to OpenShift with Service and Route | +| `/helm-deploy` | Deploy applications using Helm charts | +| `/rhel-deploy` | Deploy to standalone RHEL/Fedora systems via SSH | +| `/containerize-deploy` | End-to-end workflow from source to running app (use if not sure which strategy to choose)) | + +## Prerequisites + +- OpenShift cluster access (for S2I and OpenShift deployments) +- Podman installed locally +- GitHub personal access token (for GitHub integration) + +## MCP Servers + +- **kubernetes** - Cluster management and Helm deployments +- **podman** - Container image management and local builds +- **github** - Repository browsing and code analysis + +## Supported Languages + +Node.js, Python, Java, Go, Ruby, .NET, PHP, Perl + +## Installation + +Add this plugin to your Claude Code configuration. From 2059c4b7a5356e1af64227475aa5193309359bdf Mon Sep 17 00:00:00 2001 From: ikrispin Date: Sun, 8 Feb 2026 16:36:10 +0200 Subject: [PATCH 10/12] migrate to downstream openshift mcp and update docs --- rh-developer/.mcp.json | 15 ++++++++++----- rh-developer/README.md | 2 +- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/rh-developer/.mcp.json b/rh-developer/.mcp.json index d5767d1..f2c8038 100644 --- a/rh-developer/.mcp.json +++ b/rh-developer/.mcp.json @@ -1,14 +1,19 @@ { "mcpServers": { - "kubernetes": { - "command": "npx", - "args": ["-y", "kubernetes-mcp-server@latest"], + "openshift": { + "command": "podman", + "args": [ + "run", "-i", "--rm", + "-v", "${HOME}/.kube:/home/nonroot/.kube:ro", + "-e", "KUBECONFIG=/home/nonroot/.kube/config", + "quay.io/redhat-user-workloads/ocp-mcp-server-tenant/openshift-mcp-server-release-010:latest" + ], "env": { "KUBECONFIG": "${KUBECONFIG}" }, - "description": "Kubernetes/OpenShift MCP server for cluster management, resource operations, and Helm deployments", + "description": "OpenShift MCP server for cluster management, resource operations, and Helm deployments", "security": { - "isolation": "process", + "isolation": "container", "network": "local", "credentials": "env-only" } diff --git a/rh-developer/README.md b/rh-developer/README.md index 18d291d..cdfd06f 100644 --- a/rh-developer/README.md +++ b/rh-developer/README.md @@ -22,7 +22,7 @@ A Claude Code plugin for building and deploying applications on Red Hat platform ## MCP Servers -- **kubernetes** - Cluster management and Helm deployments +- **openshift** - OpenShift cluster management and Helm deployments - **podman** - Container image management and local builds - **github** - Repository browsing and code analysis From a1e4d079fe22098397d4ea0e9b92680cba82cee3 Mon Sep 17 00:00:00 2001 From: ikrispin Date: Mon, 9 Feb 2026 15:36:57 +0200 Subject: [PATCH 11/12] docs: update mcp.json with mcp tools used in the scope of rh-developer --- docs/mcp.json | 383 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 383 insertions(+) diff --git a/docs/mcp.json b/docs/mcp.json index 3e94948..4aafb3c 100644 --- a/docs/mcp.json +++ b/docs/mcp.json @@ -1,4 +1,387 @@ { + "openshift-mcp-server": { + "repository": "https://github.com/openshift/openshift-mcp-server", + "tools": [ + { + "name": "events_list", + "description": "List Kubernetes events from all or specific namespaces" + }, + { + "name": "namespaces_list", + "description": "List all Kubernetes namespaces in the cluster" + }, + { + "name": "projects_list", + "description": "List all OpenShift projects in the cluster" + }, + { + "name": "nodes_log", + "description": "Get logs from Kubernetes nodes (kubelet, kube-proxy, system logs)" + }, + { + "name": "nodes_stats_summary", + "description": "Get detailed resource usage statistics from nodes" + }, + { + "name": "nodes_top", + "description": "List CPU and memory consumption for nodes" + }, + { + "name": "pods_list", + "description": "List all pods in the cluster from all namespaces" + }, + { + "name": "pods_list_in_namespace", + "description": "List pods in a specific namespace" + }, + { + "name": "pods_get", + "description": "Get a specific pod by name and namespace" + }, + { + "name": "pods_delete", + "description": "Delete a pod by name and namespace" + }, + { + "name": "pods_top", + "description": "List resource consumption for pods" + }, + { + "name": "pods_exec", + "description": "Execute commands in pod containers" + }, + { + "name": "pods_log", + "description": "Get logs from pod containers" + }, + { + "name": "pods_run", + "description": "Run a new pod with specified container image" + }, + { + "name": "resources_list", + "description": "List Kubernetes resources by apiVersion and kind" + }, + { + "name": "resources_get", + "description": "Get specific Kubernetes resources" + }, + { + "name": "resources_create_or_update", + "description": "Create or update resources from YAML/JSON" + }, + { + "name": "resources_delete", + "description": "Delete Kubernetes resources" + }, + { + "name": "resources_scale", + "description": "Get or update resource scale (replicas)" + }, + { + "name": "configuration_contexts_list", + "description": "List available kubeconfig contexts and server URLs" + }, + { + "name": "targets_list", + "description": "List all available targets" + }, + { + "name": "configuration_view", + "description": "Get current Kubernetes configuration as YAML" + }, + { + "name": "helm_install", + "description": "Install Helm charts with optional values" + }, + { + "name": "helm_list", + "description": "List Helm releases in namespaces" + }, + { + "name": "helm_uninstall", + "description": "Uninstall Helm releases" + }, + { + "name": "prometheus_query", + "description": "Execute instant PromQL queries for current metrics" + }, + { + "name": "prometheus_query_range", + "description": "Execute range PromQL queries for time-series data" + }, + { + "name": "alertmanager_alerts", + "description": "Query active and pending alerts from Alertmanager" + }, + { + "name": "vm_create", + "description": "Create virtual machines with instance types and preferences (KubeVirt)" + }, + { + "name": "vm_lifecycle", + "description": "Manage VM lifecycle - start, stop, restart (KubeVirt)" + }, + { + "name": "kcp_workspaces_list", + "description": "List available kcp workspaces" + }, + { + "name": "kcp_workspace_describe", + "description": "Get detailed workspace information" + }, + { + "name": "ossm_mesh_graph", + "description": "Get mesh topology and health overview (OpenShift Service Mesh)" + }, + { + "name": "ossm_manage_istio_config_read", + "description": "List or get Istio configuration objects" + }, + { + "name": "ossm_manage_istio_config", + "description": "Create, patch, or delete Istio configurations" + }, + { + "name": "ossm_get_resource_details", + "description": "Get details for mesh services and workloads" + }, + { + "name": "ossm_get_metrics", + "description": "Get traffic metrics for mesh resources" + }, + { + "name": "ossm_workload_logs", + "description": "Get logs for workload pods" + }, + { + "name": "ossm_get_traces", + "description": "Get distributed traces for mesh resources" + } + ] + }, + "podman-mcp-server": { + "repository": "https://github.com/containers/podman-mcp-server", + "tools": [ + { + "name": "container_inspect", + "description": "Displays the low-level information and configuration of a Docker or Podman container with the specified container ID or name" + }, + { + "name": "container_list", + "description": "Prints out information about the running Docker or Podman containers" + }, + { + "name": "container_logs", + "description": "Displays the logs of a Docker or Podman container with the specified container ID or name" + }, + { + "name": "container_remove", + "description": "Removes a Docker or Podman container with the specified container ID or name" + }, + { + "name": "container_run", + "description": "Runs a Docker or Podman container with the specified image name" + }, + { + "name": "container_stop", + "description": "Stops a Docker or Podman running container with the specified container ID or name" + }, + { + "name": "image_build", + "description": "Build a Docker or Podman image from a Dockerfile, Podmanfile, or Containerfile" + }, + { + "name": "image_list", + "description": "List the Docker or Podman images on the local machine" + }, + { + "name": "image_pull", + "description": "Copies (pulls) a Docker or Podman container image from a registry onto the local machine storage" + }, + { + "name": "image_push", + "description": "Pushes a Docker or Podman container image from local machine storage to a registry" + }, + { + "name": "image_remove", + "description": "Removes a Docker or Podman image from the local machine storage" + }, + { + "name": "network_list", + "description": "List all the available Docker or Podman networks" + }, + { + "name": "volume_list", + "description": "List all the available Docker or Podman volumes" + } + ] + }, + "github-mcp-server": { + "repository": "https://github.com/github/github-mcp-server", + "tools": [ + { + "name": "add_comment_to_pending_review", + "description": "Add review comment to the requester's latest pending pull request review" + }, + { + "name": "add_issue_comment", + "description": "Add a comment to a specific issue in a GitHub repository" + }, + { + "name": "assign_copilot_to_issue", + "description": "Assign Copilot to a specific issue in a GitHub repository" + }, + { + "name": "create_branch", + "description": "Create a new branch in a GitHub repository" + }, + { + "name": "create_or_update_file", + "description": "Create or update a single file in a GitHub repository" + }, + { + "name": "create_pull_request", + "description": "Create a new pull request in a GitHub repository" + }, + { + "name": "create_repository", + "description": "Create a new GitHub repository in your account or specified organization" + }, + { + "name": "delete_file", + "description": "Delete a file from a GitHub repository" + }, + { + "name": "fork_repository", + "description": "Fork a GitHub repository to your account or specified organization" + }, + { + "name": "get_commit", + "description": "Get details for a commit from a GitHub repository" + }, + { + "name": "get_file_contents", + "description": "Get the contents of a file or directory from a GitHub repository" + }, + { + "name": "get_label", + "description": "Get a specific label from a repository" + }, + { + "name": "get_latest_release", + "description": "Get the latest release in a GitHub repository" + }, + { + "name": "get_me", + "description": "Get details of the authenticated GitHub user" + }, + { + "name": "get_release_by_tag", + "description": "Get a specific release by its tag name in a GitHub repository" + }, + { + "name": "get_tag", + "description": "Get details about a specific git tag in a GitHub repository" + }, + { + "name": "get_team_members", + "description": "Get member usernames of a specific team in an organization" + }, + { + "name": "get_teams", + "description": "Get details of the teams the user is a member of" + }, + { + "name": "issue_read", + "description": "Get information about a specific issue in a GitHub repository" + }, + { + "name": "issue_write", + "description": "Create a new or update an existing issue in a GitHub repository" + }, + { + "name": "list_branches", + "description": "List branches in a GitHub repository" + }, + { + "name": "list_commits", + "description": "Get list of commits of a branch in a GitHub repository" + }, + { + "name": "list_issue_types", + "description": "List supported issue types for repository owner (organization)" + }, + { + "name": "list_issues", + "description": "List issues in a GitHub repository" + }, + { + "name": "list_pull_requests", + "description": "List pull requests in a GitHub repository" + }, + { + "name": "list_releases", + "description": "List releases in a GitHub repository" + }, + { + "name": "list_tags", + "description": "List git tags in a GitHub repository" + }, + { + "name": "merge_pull_request", + "description": "Merge a pull request in a GitHub repository" + }, + { + "name": "pull_request_read", + "description": "Get information on a specific pull request in GitHub repository" + }, + { + "name": "pull_request_review_write", + "description": "Create and/or submit, delete review of a pull request" + }, + { + "name": "push_files", + "description": "Push multiple files to a GitHub repository in a single commit" + }, + { + "name": "request_copilot_review", + "description": "Request a GitHub Copilot code review for a pull request" + }, + { + "name": "search_code", + "description": "Fast and precise code search across ALL GitHub repositories using GitHub's native search engine" + }, + { + "name": "search_issues", + "description": "Search for issues in GitHub repositories using issues search syntax" + }, + { + "name": "search_pull_requests", + "description": "Search for pull requests in GitHub repositories using issues search syntax" + }, + { + "name": "search_repositories", + "description": "Find GitHub repositories by name, description, readme, topics, or other metadata" + }, + { + "name": "search_users", + "description": "Find GitHub users by username, real name, or other profile information" + }, + { + "name": "sub_issue_write", + "description": "Add a sub-issue to a parent issue in a GitHub repository" + }, + { + "name": "update_pull_request", + "description": "Update an existing pull request in a GitHub repository" + }, + { + "name": "update_pull_request_branch", + "description": "Update the branch of a pull request with the latest changes from the base branch" + } + ] + }, "lightspeed-mcp": { "repository": "https://github.com/RedHatInsights/insights-mcp/tree/main", "tools": [ From 60df7695cc15def36a686a6994cbdf9ad6eea003 Mon Sep 17 00:00:00 2001 From: ikrispin Date: Mon, 9 Feb 2026 16:21:13 +0200 Subject: [PATCH 12/12] remove unnecessary internal doc file --- rh-developer/docs/session-state-patterns.md | 168 -------------------- 1 file changed, 168 deletions(-) delete mode 100644 rh-developer/docs/session-state-patterns.md diff --git a/rh-developer/docs/session-state-patterns.md b/rh-developer/docs/session-state-patterns.md deleted file mode 100644 index 11606ec..0000000 --- a/rh-developer/docs/session-state-patterns.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: Session State Patterns -category: architecture -sources: [] ---- - -# Session State Patterns - -This reference defines the state management patterns used across deployment skills. - -## Common State Properties - -All deployment workflows share these core state properties: - -``` -COMMON_STATE = { - phase: string, // Current workflow phase - - // Project detection - app_name: string, - language: string, - framework: string, - version: string, - container_port: number, - - // Build configuration - builder_image: string, - build_strategy: "Source" | "Podman", - - // Tracking - created_resources: [ - { type: string, name: string, path?: string, status?: string } - ] -} -``` - -## OpenShift Deployment State - -For `/containerize-deploy` and `/s2i-build` workflows: - -``` -OPENSHIFT_STATE = { - ...COMMON_STATE, - - phase: "intro" | "detect" | "target" | "strategy" | "image-select" | - "connect" | "helm" | "git" | "pre-build" | "build" | - "pre-deploy" | "deploy" | "complete", - - // Target - deployment_target: "openshift" | "rhel", - deployment_strategy: "S2I" | "Podman" | "Helm", - - // Cluster connection - cluster: string, - namespace: string, - user: string, - - // Git source - git_url: string, - git_branch: string, - - // Image selection - image_variant: "full" | "minimal" | "runtime", - selection_rationale: string, - - // Helm (if applicable) - helm_chart_detected: boolean, - helm_chart_path: string, - helm_chart_name: string, - helm_chart_version: string, - helm_release_name: string, - helm_release_revision: number, - - // Deployment config - replicas: number, - create_route: boolean, - - // Results - build_name: string, - route_host: string -} -``` - -## RHEL Deployment State - -For `/rhel-deploy` workflows: - -``` -RHEL_STATE = { - ...COMMON_STATE, - - phase: "intro" | "ssh" | "analyze" | "strategy" | - "container-*" | "native-*" | "complete", - - // SSH connection - rhel_host: string, - rhel_user: string, - rhel_port: number, // default: 22 - - // Target analysis - rhel_version: string, // e.g., "RHEL 9.3" - rhel_arch: string, // e.g., "x86_64" - podman_available: boolean, - podman_version: string, - selinux_status: "enforcing" | "permissive" | "disabled", - firewall_status: "active" | "inactive", - - // Deployment strategy - deployment_strategy: "container" | "native", - - // Container-specific - container_mode: "rootless" | "rootful", - container_name: string, - container_image: string, - - // Native-specific - app_install_path: string, // e.g., "/opt/[app-name]" - service_user: string, - - // Common service - systemd_unit_name: string, - exposed_port: number -} -``` - -## State Transitions - -### OpenShift Path -``` -intro → detect → target → strategy → image-select → connect → - ├── (S2I/Podman) → git → pre-build → build → pre-deploy → deploy → complete - └── (Helm) → helm → complete -``` - -### RHEL Path -``` -intro → ssh → analyze → strategy → - ├── (Container) → container-image → container-config → container-systemd → firewall → complete - └── (Native) → native-deps → native-deploy → native-systemd → firewall → complete -``` - -## Resource Tracking - -Track created resources for rollback support: - -```javascript -created_resources: [ - { type: "file", path: "/etc/systemd/system/app.service" }, - { type: "service", name: "app.service" }, - { type: "firewall_rule", port: 8080 }, - { type: "selinux_context", path: "/opt/app" }, - { kind: "Deployment", name: "app", namespace: "default" }, - { kind: "Service", name: "app", namespace: "default" }, - { kind: "Route", name: "app", namespace: "default" } -] -``` - -## Passing State Between Skills - -When delegating between skills, pass these values: - -| From | To | Values Passed | -|------|-----|---------------| -| `/containerize-deploy` | `/detect-project` | (none - detect provides values) | -| `/detect-project` | `/recommend-image` | `LANGUAGE`, `FRAMEWORK`, `VERSION` | -| `/recommend-image` | caller | `BUILDER_IMAGE`, `IMAGE_VARIANT`, `SELECTION_RATIONALE` | -| `/containerize-deploy` | `/rhel-deploy` | `APP_NAME`, `LANGUAGE`, `FRAMEWORK`, `VERSION`, `BUILDER_IMAGE`, `CONTAINER_PORT` | -| `/containerize-deploy` | `/helm-deploy` | `APP_NAME`, `NAMESPACE`, `HELM_CHART_PATH` |