diff --git a/rh-developer/skills/containerize-deploy/SKILL.md b/rh-developer/skills/containerize-deploy/SKILL.md index a64bd459..f3565dd9 100644 --- a/rh-developer/skills/containerize-deploy/SKILL.md +++ b/rh-developer/skills/containerize-deploy/SKILL.md @@ -2,6 +2,10 @@ name: containerize-deploy description: | Complete end-to-end workflow for containerizing and deploying applications to OpenShift or standalone RHEL systems. Orchestrates /detect-project, /s2i-build, /deploy, /helm-deploy, and /rhel-deploy skills with user confirmation checkpoints at each phase. Supports S2I, Podman, Helm deployment strategies for OpenShift, and Podman/native deployments for RHEL hosts. Use this skill when user wants to go from source code to running application in one guided workflow. Supports resume after interruption and rollback on failure. Triggers on /containerize-deploy command. +model: inherit +color: green +metadata: + user_invocable: "true" --- # /containerize-deploy Skill @@ -11,119 +15,25 @@ Provide a complete, guided workflow from local source code to running applicatio ## Overview ``` -[Intro] → [Detect] → [Target] → [Strategy] ──┬─→ [OpenShift Path] ─────┬─→ [Complete] - │ │ [S2I/Podman/Helm] │ - │ │ │ - │ └─→ [RHEL Path] ───────────┘ - │ (/rhel-deploy) - │ - User chooses target: - - OpenShift → Strategy selection (S2I/Podman/Helm) - - RHEL → Delegate to /rhel-deploy skill +[Intro] → [Detect] → [Target] → [Strategy] ──┬─→ [OpenShift: S2I/Podman/Helm] ──┬─→ [Complete] + └─→ [RHEL: /rhel-deploy] ──────────┘ ``` -**Deployment Targets:** -- **OpenShift** - Deploy to OpenShift/Kubernetes cluster (S2I, Podman, or Helm strategies) -- **RHEL Host** - Deploy to standalone RHEL system via SSH (delegates to /rhel-deploy) +## When to Use This Skill -**OpenShift Deployment Strategies (if OpenShift target selected):** -- **S2I** - Source-to-Image build on OpenShift, then deploy (Phases 3-7) -- **Podman** - Build from Containerfile/Dockerfile on OpenShift, then deploy (Phases 3-7) -- **Helm** - Deploy using Helm chart (Phase 2-H) +Use `/containerize-deploy` when a user wants a complete guided workflow from source code to running application on OpenShift or standalone RHEL systems. This skill orchestrates project detection, build strategy selection, and deployment with user confirmation at each phase. ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. - -**IMPORTANT:** This skill requires explicit user confirmation at each phase. You MUST: - -1. **Wait for user confirmation** before executing any actions -2. **Do NOT proceed** to the next phase until the user explicitly approves -3. **Present options clearly** (yes/no/modify) and wait for response -4. **Never auto-execute** resource creation, builds, or deployments -5. **Never skip configuration questions** even if user seems to know what they want - -If the user says "no" or wants modifications, address their concerns before proceeding. - -### Anti-Patterns to Avoid - -**CRITICAL - DO NOT DO THIS:** - -- If user says "yes do helm deployment to namespace X" - do NOT skip configuration questions -- If user seems experienced or decisive - do NOT assume they've considered all options -- If user provides strategy choice early - do NOT skip environment type question -- If user gives multiple answers at once - still ask each checkpoint question individually - -**The user specifying WHAT to deploy does not mean they've decided HOW to configure it.** - -Strategy choice ≠ Configuration approval. Always ask: -1. Environment type (dev/staging/prod) -2. Resource limits appropriate for environment -3. Runtime vs build-time configuration -4. Replicas and scaling -5. Any customizations before proceeding - -## Phase Execution Rules - -**MANDATORY:** Execute phases in order. Each phase MUST: - -1. Display the phase information to the user -2. Ask the specific question for that phase -3. Wait for user response -4. Only then proceed to next phase - -**Even if user provides information for multiple phases at once:** -- Acknowledge what they said -- But still display each phase's confirmation prompt -- Get explicit "yes" for each phase before executing - -Example: -- User: "yes do helm to test-app namespace" -- AI: "Great, you've chosen Helm strategy and test-app namespace. Let me confirm the configuration details..." -- [Still show Phase 1.7 Configuration Review] -- [Still ask environment type, config approach, etc.] +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow ### Phase 0: Introduction -```markdown -# Containerize & Deploy - -I'll help you containerize and deploy your application to OpenShift or a standalone RHEL system. +Present the workflow overview and available deployment targets/strategies. Ask: **Ready to begin?** (yes/no) -**What this workflow does:** -1. **Detect** - Analyze your project and determine the best deployment strategy -2. **Choose Target** - Deploy to OpenShift cluster or RHEL host -3. **Build** - Build container image (S2I or Podman) or skip if using Helm with existing image -4. **Deploy** - Deploy using Kubernetes resources, Helm chart, or systemd services - -**Deployment Targets:** -- **OpenShift** - Deploy to OpenShift/Kubernetes cluster -- **RHEL Host** - Deploy directly to a RHEL system via SSH - -**OpenShift Strategies:** -- **S2I (Source-to-Image)** - Build and deploy from source code -- **Podman** - Build from existing Containerfile/Dockerfile -- **Helm** - Deploy using Helm chart - -**RHEL Strategies:** -- **Container** - Run with Podman + systemd -- **Native** - Install with dnf + systemd - -**What I need from you:** -- Confirmation at each step before I make changes -- Access to an OpenShift cluster OR SSH access to a RHEL host -- Your project source code - -**Ready to begin?** (yes/no) -``` - -**WAIT for user confirmation before proceeding.** Do NOT continue to Phase 1 until user explicitly confirms. - -- If user says "yes" → Proceed to Phase 1 -- If user says "no" → Ask what concerns they have -- If user gives multiple answers at once (e.g., "yes helm to namespace X") → Acknowledge their choices but still proceed through each phase individually +**WAIT for user confirmation before proceeding.** ### Phase 1: Project Detection @@ -169,7 +79,7 @@ Where would you like to deploy this application? Store `DEPLOYMENT_TARGET` in session state. -**WAIT for user confirmation before proceeding.** Do NOT assume target based on earlier statements. +**WAIT for user confirmation before proceeding.** **If user selects "RHEL":** - Store `DEPLOYMENT_TARGET = "rhel"` in session state @@ -209,7 +119,7 @@ Based on my analysis, you have these options: Store `DEPLOYMENT_STRATEGY` in session state. -**WAIT for user confirmation before proceeding.** Do NOT skip to Phase 1.7 without explicit strategy selection. +**WAIT for user confirmation before proceeding.** ### Phase 1.6: Image Selection (S2I/Podman only) @@ -288,10 +198,7 @@ Before I proceed, let me confirm the deployment configuration: 2. Customize resources ``` -**WAIT for user to answer ALL questions above before proceeding.** Do NOT continue to Phase 2 until user has confirmed: -- Environment type -- Configuration approach -- Resource settings +**WAIT for user to answer ALL questions above before proceeding.** Store: `ENVIRONMENT_TYPE`, `CONFIG_APPROACH`, `RESOURCE_PROFILE` in session state. @@ -543,102 +450,28 @@ Proceeding with Helm deployment... ### Phase 8: Completion -```markdown -## Deployment Complete! - -Your application is now running on OpenShift. - ---- - -**Application Summary:** - -| Setting | Value | -|---|---| -| Name | [app-name] | -| Namespace | [namespace] | -| Language | [language] | -| Framework | [framework] | - ---- - -**Access URLs:** - -| Type | URL | -|---|-----| -| **External** | https://[route-host] | -| Internal | http://[app-name].[namespace].svc.cluster.local:[port] | - ---- - -**Resources Created:** - -| Resource | Name | Status | -|----|---|-----| -| ImageStream | [app-name] | Ready | -| BuildConfig | [app-name] | Ready | -| Deployment | [app-name] | 1/1 Running | -| Service | [app-name] | Active | -| Route | [app-name] | Admitted | - ---- - -**Quick Commands:** - -```bash -# View logs -oc logs -f deployment/[app-name] -n [namespace] - -# Scale up -oc scale deployment/[app-name] --replicas=3 -n [namespace] - -# Trigger rebuild (after code changes) -oc start-build [app-name] -n [namespace] - -# Delete everything -oc delete all -l app=[app-name] -n [namespace] -``` - ---- - -**Next Steps:** -- Open your app: [route-url] -- Set up Git webhooks for automatic builds -- Add environment variables: `oc set env deployment/[app-name] KEY=value` -- Configure autoscaling: `oc autoscale deployment/[app-name] --min=1 --max=5` - ---- - -Congratulations! Your application is live. -``` - -## MCP Tools Used - -All tools from child skills: - -| Phase | Tools | -|---|---| -| Detect | `run_terminal_cmd` (optional clone) | -| 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`, `pods_list` | -| Rollback | `resources_delete`, `helm_uninstall`, `helm_rollback` | - -## Related Skills - -| Skill | Use When | -|-------|----------| -| `/debug-pod` | Pod failures (CrashLoopBackOff, OOMKilled, ImagePullBackOff) | -| `/debug-build` | S2I or Podman build failures | -| `/debug-network` | Service connectivity issues (no endpoints, 503 errors) | -| `/debug-rhel` | RHEL deployment failures (systemd, SELinux, firewall) | - -## Reference Documentation - -For detailed guidance, see: -- [docs/builder-images.md](../docs/builder-images.md) - Language detection, S2I builder images -- [docs/image-selection-criteria.md](../docs/image-selection-criteria.md) - Image variant selection, LTS timelines -- [docs/python-s2i-entrypoints.md](../docs/python-s2i-entrypoints.md) - Python S2I configuration -- [docs/rhel-deployment.md](../docs/rhel-deployment.md) - RHEL host deployment (when delegating to /rhel-deploy) -- [docs/debugging-patterns.md](../docs/debugging-patterns.md) - Common error patterns and troubleshooting -- [docs/prerequisites.md](../docs/prerequisites.md) - All required tools by skill +Present a summary including: +- Application name, namespace, language, framework +- Access URLs (external route, internal service DNS) +- Resources created with status (ImageStream, BuildConfig, Deployment, Service, Route) +- Quick commands: view logs, scale, rebuild, delete +- Next steps: open app URL, set up webhooks, add env vars, configure autoscaling + +## Dependencies + +### Required MCP Servers +- `openshift` - cluster resource management for OpenShift deployments + +### Related Skills +- `/debug-pod` - Pod failures (CrashLoopBackOff, OOMKilled, ImagePullBackOff) +- `/debug-build` - S2I or Podman build failures +- `/debug-network` - Service connectivity issues (no endpoints, 503 errors) +- `/debug-rhel` - RHEL deployment failures (systemd, SELinux, firewall) + +### Reference Documentation +- [docs/builder-images.md](../../docs/builder-images.md) - Language detection, S2I builder images +- [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md) - Image variant selection, LTS timelines +- [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python S2I configuration +- [docs/rhel-deployment.md](../../docs/rhel-deployment.md) - RHEL host deployment +- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting +- [docs/prerequisites.md](../../docs/prerequisites.md) - All required tools by skill diff --git a/rh-developer/skills/debug-build/SKILL.md b/rh-developer/skills/debug-build/SKILL.md index e62c7284..61801bc6 100644 --- a/rh-developer/skills/debug-build/SKILL.md +++ b/rh-developer/skills/debug-build/SKILL.md @@ -2,6 +2,8 @@ name: debug-build description: | Diagnose OpenShift build failures including S2I builds, Docker/Podman builds, and BuildConfig issues. Automates multi-step diagnosis: BuildConfig validation, build pod logs, registry authentication, and source repository access. Use this skill when builds fail, hang, or produce unexpected results. Triggers on /debug-build command or phrases like "build failed", "S2I error", "can't pull builder image", "can't push to registry", "build timeout". +model: inherit +color: cyan metadata: user_invocable: "true" --- @@ -17,39 +19,13 @@ Before running this skill: 2. User has access to the target namespace 3. Build or BuildConfig name is known (or can be identified from recent builds) -## Critical: Human-in-the-Loop Requirements - -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. - -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing diagnostic actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present findings clearly** and ask if user wants deeper analysis -4. **Never auto-execute** remediation actions without user approval - -If the user says "no" or wants to focus on specific areas, address their concerns before proceeding. - -## Critical: Prefer MCP Tools +## When to Use This Skill -**IMPORTANT:** Prefer MCP tools over CLI commands for better integration and user experience: -1. **Search for MCP tools first** - Use `ToolSearch` to load OpenShift MCP tools (e.g., `+openshift pods_get`) before diagnostic actions -2. **Use MCP when available** - Prefer `pods_get`, `pods_log`, `events_list`, `resources_get` over `oc`/`kubectl` commands +Use this skill when OpenShift builds fail, hang, or produce unexpected results. It diagnoses S2I builds, Docker/Podman builds, and BuildConfig issues by analyzing build pod logs, registry authentication, and source repository access. -## Trigger - -- User types `/debug-build` -- User says "build failed", "S2I error", "build won't complete" -- User says "can't pull builder image", "can't push to registry" -- User says "build timeout", "build stuck", "assemble failed" -- After `/s2i-build` reports a failure - -## Input Parameters +## Critical: Human-in-the-Loop Requirements -| Parameter | Description | Default | -|-----------|-------------|---------| -| `BUILD_NAME` | Name of specific build to debug | Latest failed build | -| `BUILDCONFIG_NAME` | BuildConfig to analyze | Auto-detect | -| `NAMESPACE` | Target namespace | Current namespace | +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -71,7 +47,7 @@ Which build would you like me to debug? Select an option or enter a build name: ``` -**WAIT for user response.** Do NOT proceed until user identifies the target build. +**WAIT for user confirmation before proceeding.** If user selects "List failed builds": Use kubernetes MCP `resources_list` for builds, filter by Failed phase: @@ -320,74 +296,19 @@ Select an option: ## Build Failure Categories -### Common S2I Build Failures - -| Phase | Failure Type | Key Indicators | Common Fix | -|-------|--------------|----------------|------------| -| **fetch-source** | Auth failure | 401/403 in logs | Add/fix source secret | -| **fetch-source** | Repo not found | 404 in logs | Check git URL | -| **pull-builder** | Image not found | ImagePullBackOff | Import builder image | -| **pull-builder** | Auth failure | unauthorized | Add pull secret | -| **assemble** | Dependency error | npm ERR, pip error | Fix package.json/requirements | -| **assemble** | Build script fail | Non-zero exit | Check application code | -| **assemble** | Out of memory | OOMKilled | Increase build resources | -| **push** | Registry auth | unauthorized | Check push secret | -| **push** | Registry full | quota exceeded | Clean up old images | - -### Python S2I Specific Issues - -| Issue | Symptom | Solution | -|-------|---------|----------| -| Wrong entry point | "No module named app" | Set APP_MODULE or rename to app.py | -| Missing gunicorn | "gunicorn: command not found" | Add gunicorn to requirements.txt | -| Version mismatch | Import errors | Match Python version to builder | - -See [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) for detailed Python guidance. - -### Node.js S2I Specific Issues - -| Issue | Symptom | Solution | -|-------|---------|----------| -| Build script missing | "npm run build" fails | Add build script or set NPM_RUN | -| Node version mismatch | Syntax errors | Match engines.node in package.json | -| Private npm registry | 401 Unauthorized | Configure .npmrc or NPM_MIRROR | - -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `resources_list` | List builds, find failed builds | -| `resources_get` | Get Build spec, BuildConfig details | -| `pod_logs` | Get build pod logs | -| `events_list` | Get build events | -| `resources_list` | Check secrets, imagestreams | -| `get_file_contents` (github) | Verify source repository access | - -## Output Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `BUILD_NAME` | Debugged build name | `myapp-1` | -| `BUILDCONFIG_NAME` | Associated BuildConfig | `myapp` | -| `BUILD_NAMESPACE` | Namespace | `my-project` | -| `FAILURE_PHASE` | Phase where build failed | `assemble` | -| `FAILURE_CATEGORY` | Categorized failure type | `DependencyError` | -| `ROOT_CAUSE` | Identified root cause | `npm package not found` | +For S2I build phase failures, common error patterns (Node.js, Python, Java), and troubleshooting decision trees, see [docs/debugging-patterns.md](../../docs/debugging-patterns.md). ## Dependencies ### Required MCP Servers -- `openshift` (kubernetes MCP server) -- `github` (optional, for source repository verification) +- `openshift` - Kubernetes/OpenShift resource access for builds, BuildConfigs, and build pod logs ### Related Skills - `/s2i-build` - To retry build after fixing issues - `/debug-pod` - To debug the builder pod directly -- `/detect-project` - To re-analyze project and builder image selection - -## Reference Documentation +- `/deploy` - To deploy after a successful build -For detailed guidance, see: +### Reference Documentation - [docs/builder-images.md](../../docs/builder-images.md) - S2I builder image selection, version mapping - [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python APP_MODULE configuration - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns diff --git a/rh-developer/skills/debug-container/SKILL.md b/rh-developer/skills/debug-container/SKILL.md index 0669b610..71e48194 100644 --- a/rh-developer/skills/debug-container/SKILL.md +++ b/rh-developer/skills/debug-container/SKILL.md @@ -2,6 +2,8 @@ name: debug-container description: | Diagnose local container issues with Podman/Docker including image pull errors, container startup failures, OOM kills, and networking problems. Automates multi-step diagnosis: container inspect, logs retrieval, image analysis, and resource constraint checking. Use this skill when containers fail to run locally before deployment. Triggers on /debug-container command or phrases like "container won't start", "podman run fails", "local container crashing", "container exits immediately". +model: inherit +color: cyan metadata: user_invocable: "true" --- @@ -33,34 +35,9 @@ Diagnose local Podman/Docker container issues by automatically gathering contain See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing diagnostic actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present findings clearly** and ask if user wants deeper analysis -4. **Never auto-execute** remediation actions without user approval +## When to Use This Skill -If the user says "no" or wants to focus on specific areas, address their concerns before proceeding. - -## Critical: Prefer MCP Tools - -**IMPORTANT:** Prefer MCP tools over CLI commands for better integration and user experience: -1. **Search for MCP tools first** - Use `ToolSearch` to load Podman MCP tools (e.g., `+podman container_inspect`) before diagnostic actions -2. **Use MCP when available** - Prefer `container_list`, `container_inspect`, `container_logs` over `podman`/`docker` commands - -## Trigger - -- User types `/debug-container` -- User says "container won't start", "podman run fails" -- User says "container exits immediately", "container crashing" -- User says "can't pull image", "image not found" -- User says "OOM", "out of memory", "exit code 137" - -## Input Parameters - -| Parameter | Description | Default | -|-----------|-------------|---------| -| `CONTAINER` | Container name or ID | Auto-detect from recent | -| `IMAGE` | Image name to debug | From container | +Use `/debug-container` when local Podman or Docker containers fail to run, crash on startup, get OOM killed, or have image pull errors. This skill automates container inspection, log retrieval, image analysis, and resource constraint checking. ## Workflow @@ -79,7 +56,7 @@ What would you like me to debug? Select an option or enter a container name/ID: ``` -**WAIT for user response.** Do NOT proceed until user identifies the target. +**WAIT for user confirmation before proceeding.** If user selects "List containers": Use Podman MCP `container_list`: @@ -96,7 +73,7 @@ Use Podman MCP `container_list`: Which container would you like me to debug? ``` -**WAIT for user to select a container.** +**WAIT for user confirmation before proceeding.** ### Step 2: Inspect Container @@ -308,17 +285,7 @@ Continue to diagnosis summary? (yes/no) - Evidence: [from logs] - Impact: [application cannot access data] -### Exit Code Reference - -| Exit Code | Meaning | Your Container | -|-----------|---------|----------------| -| 0 | Success | [match?] | -| 1 | General error | [match?] | -| 126 | Permission problem | [match?] | -| 127 | Command not found | [match?] | -| 137 | SIGKILL (OOM) | [match?] | -| 139 | Segfault | [match?] | -| 143 | SIGTERM | [match?] | +See [debugging-patterns.md](../../docs/debugging-patterns.md) for exit code reference. ### Recommended Actions @@ -361,84 +328,17 @@ Select an option: **WAIT for user to select next action.** -## Exit Code Reference - -| Exit Code | Signal | Meaning | Common Cause | -|-----------|--------|---------|--------------| -| 0 | - | Success | Normal exit | -| 1 | - | General error | Application error, unhandled exception | -| 2 | - | Misuse of shell | Invalid arguments | -| 126 | - | Permission denied | Cannot execute entrypoint | -| 127 | - | Command not found | Entrypoint binary missing | -| 128+N | Signal N | Killed by signal | See signal table | -| 137 | SIGKILL (9) | Force killed | OOM kill, `podman kill` | -| 139 | SIGSEGV (11) | Segmentation fault | Memory corruption | -| 143 | SIGTERM (15) | Terminated | `podman stop`, graceful shutdown | - -## Common Container Issues - -### Startup Failures - -| Issue | Symptom | Diagnosis | Fix | -|-------|---------|-----------|-----| -| Missing entrypoint | Exit 127 | "executable not found" | Check ENTRYPOINT/CMD | -| Wrong command | Exit 127 | "no such file" | Verify command path | -| Permission denied | Exit 126 | "permission denied" | Check file permissions | -| Missing dependency | Exit 1 | "cannot find module" | Add dependency to image | -| Port conflict | Exit 1 | "address in use" | Use different port | - -### Runtime Issues - -| Issue | Symptom | Diagnosis | Fix | -|-------|---------|-----------|-----| -| OOM killed | Exit 137 | OOMKilled=true | Increase memory limit | -| Volume permission | Exit 1 | "permission denied" | Use :Z/:z labels or fix perms | -| Missing env var | Exit 1 | "undefined" errors | Add -e VAR=value | -| Network issue | Exit 1 | "connection refused" | Check network mode | - -### SELinux Volume Issues - -On RHEL/Fedora with SELinux, volume mounts may need labels: - -```bash -# Shared label (multiple containers can access) -podman run -v /host/path:/container/path:z [image] - -# Private label (only this container) -podman run -v /host/path:/container/path:Z [image] -``` - -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `container_list` | List containers | -| `container_inspect` | Get container details | -| `container_logs` | Get container output | -| `image_list` | Check image info | - -## Output Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `CONTAINER_ID` | Container ID | `abc123def456` | -| `CONTAINER_NAME` | Container name | `myapp` | -| `CONTAINER_IMAGE` | Image used | `myapp:latest` | -| `EXIT_CODE` | Exit code | `137` | -| `OOM_KILLED` | OOM status | `true` / `false` | -| `ROOT_CAUSE` | Identified cause | `Out of memory` | +For exit codes, common container issues, and SELinux volume guidance, see [debugging-patterns.md](../../docs/debugging-patterns.md). ## Dependencies ### Required MCP Servers -- `podman` (Podman MCP server) +- `podman` - container inspection, logs, and image analysis ### Related Skills -- `/debug-rhel` - For systemd service issues on RHEL hosts -- `/recommend-image` - To select a better base image - -## Reference Documentation +- `/debug-rhel` - systemd service issues on RHEL hosts +- `/recommend-image` - select a better base image -For detailed guidance, see: +### Reference Documentation - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns, exit codes - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (podman) diff --git a/rh-developer/skills/debug-network/SKILL.md b/rh-developer/skills/debug-network/SKILL.md index b084e790..81656d80 100644 --- a/rh-developer/skills/debug-network/SKILL.md +++ b/rh-developer/skills/debug-network/SKILL.md @@ -2,6 +2,8 @@ name: debug-network description: | Diagnose OpenShift service connectivity issues including DNS resolution, service endpoints, route ingress, and network policies. Automates multi-step diagnosis: service endpoint verification, pod selector matching, route status, and network policy analysis. Use this skill when services can't communicate, routes return 503/502 errors, or external access fails. Triggers on /debug-network command or phrases like "can't reach service", "route returning 503", "pods can't communicate", "no endpoints". +model: inherit +color: cyan metadata: user_invocable: "true" --- @@ -17,39 +19,13 @@ Before running this skill: 2. User has access to the target namespace 3. Service, Route, or application name is known -## Critical: Human-in-the-Loop Requirements - -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. - -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing diagnostic actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present findings clearly** and ask if user wants deeper analysis -4. **Never auto-execute** remediation actions without user approval - -If the user says "no" or wants to focus on specific areas, address their concerns before proceeding. - -## Critical: Prefer MCP Tools +## When to Use This Skill -**IMPORTANT:** Prefer MCP tools over CLI commands for better integration and user experience: -1. **Search for MCP tools first** - Use `ToolSearch` to load OpenShift MCP tools (e.g., `+openshift pods_get`) before diagnostic actions -2. **Use MCP when available** - Prefer `pods_get`, `pods_log`, `events_list`, `resources_get` over `oc`/`kubectl` commands +Use this skill when services cannot communicate, routes return 503/502 errors, or external access fails. It automates checking service endpoints, pod selector matching, route status, and network policy analysis to pinpoint connectivity issues. -## Trigger - -- User types `/debug-network` -- User says "can't reach service", "service not working" -- User says "route returning 503", "502 Bad Gateway" -- User says "pods can't communicate", "network timeout" -- User says "no endpoints", "service has no backends" - -## Input Parameters +## Critical: Human-in-the-Loop Requirements -| Parameter | Description | Default | -|-----------|-------------|---------| -| `SERVICE_NAME` | Service to debug | Auto-detect | -| `ROUTE_NAME` | Route to debug | Same as service | -| `NAMESPACE` | Target namespace | Current namespace | +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -339,66 +315,17 @@ Select an option: ## Common Connectivity Issues -### Service Issues - -| Issue | Symptom | Diagnosis | Fix | -|-------|---------|-----------|-----| -| No endpoints | Connection refused | Empty endpoints list | Fix selector or pod labels | -| Selector mismatch | Some pods missing | Compare selector to labels | Update selector or labels | -| Wrong port | Connection refused | Check targetPort | Update service port mapping | -| Pod not ready | Intermittent failures | Readiness probe failing | Fix application or probe | - -### Route Issues - -| Issue | Symptom | Diagnosis | Fix | -|-------|---------|-----------|-----| -| 503 Service Unavailable | No healthy backends | Check endpoints | Ensure pods are ready | -| 502 Bad Gateway | Backend connection error | Pod crash or wrong port | Debug pod or fix port | -| 404 Not Found | Route not admitted | Check route status | Fix hostname conflict | -| TLS errors | Certificate issues | Check TLS config | Update certificates | -| Host not found | DNS issue | Check route host | Verify wildcard DNS | - -### Network Policy Issues - -| Issue | Symptom | Diagnosis | Fix | -|-------|---------|-----------|-----| -| Ingress blocked | Connection timeout | Check policy rules | Add ingress rule | -| Egress blocked | Can't reach external | Check egress rules | Add egress rule | -| Cross-namespace blocked | Namespace isolation | Check namespaceSelector | Add namespace rule | -| Port blocked | Specific port fails | Check port rules | Add port to policy | - -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `resources_get` | Get Service, Route, NetworkPolicy details | -| `resources_list` | List services, endpoints, pods, policies | -| `pod_list` | Check pod status and labels | -| `events_list` | Get route/service events | - -## Output Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `SERVICE_NAME` | Debugged service | `myapp` | -| `SERVICE_NAMESPACE` | Namespace | `my-project` | -| `HAS_ENDPOINTS` | Endpoints exist | `true` / `false` | -| `ENDPOINTS_READY` | Ready endpoint count | `2` | -| `ROUTE_ADMITTED` | Route status | `true` / `false` | -| `NETWORK_POLICY_BLOCKING` | Policy blocking traffic | `true` / `false` | -| `ROOT_CAUSE` | Identified root cause | `Selector mismatch` | +For detailed diagnosis and fix tables covering service, route, and network policy issues, see [docs/debugging-patterns.md](../../docs/debugging-patterns.md). ## Dependencies ### Required MCP Servers -- `openshift` (kubernetes MCP server) +- `openshift` - Kubernetes/OpenShift resource access for services, routes, endpoints, and network policies ### Related Skills - `/debug-pod` - To debug specific backend pods - `/deploy` - To fix and redeploy the service -## Reference Documentation - -For detailed guidance, see: +### Reference Documentation - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification diff --git a/rh-developer/skills/debug-pipeline/SKILL.md b/rh-developer/skills/debug-pipeline/SKILL.md index 8c8f3f6e..571167f5 100644 --- a/rh-developer/skills/debug-pipeline/SKILL.md +++ b/rh-developer/skills/debug-pipeline/SKILL.md @@ -2,6 +2,8 @@ name: debug-pipeline description: | Diagnose OpenShift Pipelines (Tekton) CI/CD failures including PipelineRun failures, TaskRun step errors, workspace/PVC binding issues, and authentication problems. Automates multi-step diagnosis: PipelineRun status, failed TaskRun analysis, step container logs, and related resource checks. Use this skill when pipelines fail, hang, or produce unexpected results. Triggers on /debug-pipeline command or phrases like "pipeline failed", "PipelineRun error", "TaskRun failed", "tekton error", "pipeline stuck", "pipeline timeout". +model: inherit +color: cyan metadata: user_invocable: "true" --- @@ -18,24 +20,6 @@ Before running this skill: 3. OpenShift Pipelines operator is installed on the cluster 4. PipelineRun name is known (or can be identified from recent runs) -## Critical: Human-in-the-Loop Requirements - -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. - -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing diagnostic actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present findings clearly** and ask if user wants deeper analysis -4. **Never auto-execute** remediation actions without user approval - -If the user says "no" or wants to focus on specific areas, address their concerns before proceeding. - -## Critical: Prefer MCP Tools - -**IMPORTANT:** Prefer MCP tools over CLI commands for better integration and user experience: -1. **Search for MCP tools first** - Use `ToolSearch` to load OpenShift MCP tools (e.g., `+openshift resources_get`) before diagnostic actions -2. **Use MCP when available** - Prefer `resources_get`, `resources_list`, `pod_logs`, `events_list` over `oc`/`kubectl` commands - ### Tekton CRD Access via MCP Tekton resources are standard Kubernetes CRDs. Use the generic MCP tools with these parameters: @@ -51,22 +35,13 @@ Tekton resources are standard Kubernetes CRDs. Use the generic MCP tools with th | TriggerTemplate | `TriggerTemplate` | `triggers.tekton.dev/v1beta1` | | TriggerBinding | `TriggerBinding` | `triggers.tekton.dev/v1beta1` | -## Trigger +## When to Use This Skill -- User types `/debug-pipeline` -- User says "pipeline failed", "PipelineRun failed", "PipelineRun error" -- User says "TaskRun failed", "task step failed", "tekton error" -- User says "pipeline stuck", "pipeline timeout", "pipeline hanging" -- User says "CI/CD failed", "CI pipeline broken" -- After a CI/CD pipeline reports a failure +Use this skill when OpenShift Pipelines (Tekton) fail, hang, or produce unexpected results. It diagnoses PipelineRun failures, TaskRun step errors, workspace/PVC binding issues, and authentication problems by analyzing run status, step container logs, and related resources. -## Input Parameters +## Critical: Human-in-the-Loop Requirements -| Parameter | Description | Default | -|-----------|-------------|---------| -| `PIPELINERUN_NAME` | Name of specific PipelineRun to debug | Latest failed PipelineRun | -| `PIPELINE_NAME` | Pipeline name to find runs for | Auto-detect | -| `NAMESPACE` | Target namespace | Current namespace | +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -88,7 +63,7 @@ Which PipelineRun would you like me to debug? Select an option or enter a PipelineRun name: ``` -**WAIT for user response.** Do NOT proceed until user identifies the target PipelineRun. +**WAIT for user confirmation before proceeding.** If user selects "List failed PipelineRuns": Use kubernetes MCP `resources_list` with kind `PipelineRun`, filter by Failed status: @@ -313,75 +288,12 @@ Select an option: ## Pipeline Failure Reference -### Failure Categories - -| Category | Failure Type | Key Indicators | Common Fix | -|----------|--------------|----------------|------------| -| **Authentication** | git-clone auth | `could not read Username`, `Permission denied (publickey)` | Add git secret to ServiceAccount | -| **Authentication** | Image push | `unauthorized: access denied` | Add dockerconfigjson secret to ServiceAccount | -| **Workspace** | PVC not bound | `persistentvolumeclaim "X" not found` | Create PVC or use emptyDir | -| **Workspace** | Permission denied | `permission denied` in step logs | Check fsGroup, runAsUser, PVC access mode | -| **Workspace** | Contention | Parallel tasks fail on RWO PVC | Use RWX PVC or separate workspaces | -| **Timeout** | PipelineRun timeout | `PipelineRunTimeout` condition | Increase `spec.timeouts.pipeline` | -| **Timeout** | TaskRun timeout | `TaskRunTimeout` condition | Increase `spec.timeouts.tasks` | -| **Parameter** | Missing param | `missing required parameter` | Add param to PipelineRun spec | -| **Task Step** | Build/test failure | Non-zero exit in step | Check step logs for specific error | -| **Resource** | Pod scheduling | `FailedScheduling` event | Increase quotas or reduce step resource requests | -| **Image** | Step image pull | `ImagePullBackOff` on step container | Fix step image reference or add pull secret | -| **Pipeline** | Task not found | `task "X" not found` | Verify Task name, kind (Task vs ClusterTask), namespace | -| **Trigger** | EventListener down | No PipelineRuns created | Check EventListener pod logs | -| **Trigger** | Binding mismatch | Wrong params extracted | Fix TriggerBinding param paths in CEL expressions | - -### git-clone Task Failures - -| Issue | Symptom | Solution | -|-------|---------|----------| -| Private repo, no credentials | `could not read Username` | Add `kubernetes.io/basic-auth` secret annotated with `tekton.dev/git-0: https://github.com` to SA | -| SSH key missing | `Permission denied (publickey)` | Add `kubernetes.io/ssh-auth` secret annotated with `tekton.dev/git-0: github.com` to SA | -| Branch not found | `couldn't find remote ref` | Verify `revision` parameter | - -### buildah/kaniko Task Failures - -| Issue | Symptom | Solution | -|-------|---------|----------| -| Containerfile not found | `unable to open Containerfile/Dockerfile` | Check `DOCKERFILE` parameter path relative to workspace | -| Base image pull | `unauthorized` or `not found` for FROM image | Fix base image ref or add pull secret | -| Build context wrong | `file not found` during COPY/ADD | Fix `CONTEXT` parameter to correct subdirectory | - -### Image Push Failures - -| Issue | Symptom | Solution | -|-------|---------|----------| -| Registry auth | `unauthorized: access denied` | Add `kubernetes.io/dockerconfigjson` secret annotated with `tekton.dev/docker-0: ` to SA | -| Registry unreachable | `connection refused` / `no such host` | Check registry URL, network policies, egress rules | - -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `resources_list` | List PipelineRuns, TaskRuns, PVCs, Secrets, Pipelines, Tasks | -| `resources_get` | Get PipelineRun details, TaskRun details, Pipeline/Task definitions, ServiceAccount, EventListener | -| `pod_logs` | Get TaskRun pod logs for failed step containers (use container name `step-`) | -| `pod_list` | Find TaskRun pods | -| `events_list` | Get PipelineRun/TaskRun pod events for scheduling and binding errors | - -## Output Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `PIPELINERUN_NAME` | Debugged PipelineRun name | `build-and-deploy-run-abc123` | -| `PIPELINE_NAME` | Associated Pipeline | `build-and-deploy` | -| `PIPELINE_NAMESPACE` | Namespace | `my-project` | -| `FAILED_TASKRUN` | Name of the failed TaskRun | `build-and-deploy-run-abc123-build-task` | -| `FAILED_STEP` | Step that failed | `build-push` | -| `FAILURE_CATEGORY` | Categorized failure type | `Authentication` | -| `ROOT_CAUSE` | Identified root cause | `git-clone unauthorized - missing git secret on ServiceAccount` | +For failure categories, error patterns, and troubleshooting decision trees, see [docs/debugging-patterns.md](../../docs/debugging-patterns.md) (sections: Pipeline/Tekton Failure Patterns, Common Tekton Error Messages). ## Dependencies ### Required MCP Servers -- `openshift` (kubernetes MCP server) -- `github` (optional, for source repository verification) +- `openshift` - Kubernetes/OpenShift resource access for PipelineRuns, TaskRuns, and Tekton CRDs ### Related Skills - `/debug-pod` - To debug TaskRun pods directly @@ -389,8 +301,6 @@ Select an option: - `/debug-network` - If pipeline tasks fail due to network issues - `/validate-environment` - To verify OpenShift and pipeline operator setup -## Reference Documentation - -For detailed guidance, see: +### Reference Documentation - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and pipeline troubleshooting trees - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification diff --git a/rh-developer/skills/debug-pod/SKILL.md b/rh-developer/skills/debug-pod/SKILL.md index ca3cb66a..9b1a9c1d 100644 --- a/rh-developer/skills/debug-pod/SKILL.md +++ b/rh-developer/skills/debug-pod/SKILL.md @@ -2,6 +2,8 @@ name: debug-pod description: | Diagnose pod failures on OpenShift including CrashLoopBackOff, ImagePullBackOff, OOMKilled, and pending pods. Automates multi-step diagnosis: pod status, events, logs (current + previous), and resource constraint analysis. Use this skill when pods are not running, restarting frequently, or stuck in non-ready states. Triggers on /debug-pod command or phrases like "my pod is crashing", "pod won't start", "CrashLoopBackOff", "ImagePullBackOff", "OOMKilled". +model: inherit +color: cyan metadata: user_invocable: "true" --- @@ -17,38 +19,13 @@ Before running this skill: 2. User has access to the target namespace 3. Pod or deployment name is known (or can be identified from recent deployments) -## Critical: Human-in-the-Loop Requirements - -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. - -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing diagnostic actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present findings clearly** and ask if user wants deeper analysis -4. **Never auto-execute** remediation actions without user approval - -If the user says "no" or wants to focus on specific areas, address their concerns before proceeding. - -## Critical: Prefer MCP Tools - -**IMPORTANT:** Prefer MCP tools over CLI commands for better integration and user experience: -1. **Search for MCP tools first** - Use `ToolSearch` to load OpenShift MCP tools (e.g., `+openshift pods_get`) before diagnostic actions -2. **Use MCP when available** - Prefer `pods_get`, `pods_log`, `events_list`, `resources_get` over `oc`/`kubectl` commands - -## Trigger +## When to Use This Skill -- User types `/debug-pod` -- User says "my pod is crashing", "pod won't start", "CrashLoopBackOff" -- User says "ImagePullBackOff", "OOMKilled", "pod stuck pending" -- User says "container terminated", "pod restarting" +Use this skill when pods are not running, restarting frequently, or stuck in non-ready states such as CrashLoopBackOff, ImagePullBackOff, OOMKilled, or Pending. It automates gathering pod status, events, logs, and resource constraints to identify the root cause. -## Input Parameters +## Critical: Human-in-the-Loop Requirements -| Parameter | Description | Default | -|-----------|-------------|---------| -| `POD_NAME` | Name of pod to debug | Auto-detect from failed deployment | -| `NAMESPACE` | Target namespace | Current namespace | -| `CONTAINER` | Specific container (for multi-container pods) | All containers | +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -70,7 +47,7 @@ Which pod would you like me to debug? Select an option or enter a pod name: ``` -**WAIT for user response.** Do NOT proceed until user identifies the target pod. +**WAIT for user confirmation before proceeding.** If user selects "List failing pods": Use kubernetes MCP `pod_list` with namespace, then filter to show pods NOT in Running/Succeeded state: @@ -87,7 +64,7 @@ Use kubernetes MCP `pod_list` with namespace, then filter to show pods NOT in Ru Which pod would you like me to debug? ``` -**WAIT for user to select a pod.** +**WAIT for user confirmation before proceeding.** ### Step 2: Get Pod Status Overview @@ -264,65 +241,20 @@ Would you like me to: Select an option: ``` -**WAIT for user to select next action.** - -## Error Patterns Reference - -### Common Pod Failure Categories - -| Status | Likely Cause | Key Indicators | -|--------|--------------|----------------| -| **CrashLoopBackOff** | Application crash | Non-zero exit code, error in logs | -| **ImagePullBackOff** | Image access issue | Unauthorized, not found, registry timeout | -| **Pending** | Scheduling issue | Insufficient resources, node selector, taints | -| **OOMKilled** | Memory exhaustion | Exit code 137, memory limit reached | -| **CreateContainerError** | Container config issue | Invalid command, missing secrets/configmaps | -| **Init:Error** | Init container failed | Check init container logs | - -### Exit Code Reference - -| Exit Code | Meaning | Common Cause | -|-----------|---------|--------------| -| 0 | Success | Normal termination | -| 1 | General error | Application error, exception | -| 126 | Permission denied | Cannot execute entrypoint | -| 127 | Command not found | Invalid entrypoint/command | -| 137 | SIGKILL (OOM) | Memory limit exceeded | -| 139 | SIGSEGV | Segmentation fault | -| 143 | SIGTERM | Graceful shutdown | - -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `pod_list` | List pods, find failing pods | -| `resources_get` | Get pod spec, container status, node info | -| `events_list` | Get pod events for scheduling/pull/mount errors | -| `pod_logs` | Get current and previous container logs | -| `resources_list` | Check related resources (secrets, configmaps, PVCs) | - -## Output Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `POD_NAME` | Debugged pod name | `myapp-5d4f7b8c9-x2k4l` | -| `POD_NAMESPACE` | Pod namespace | `my-project` | -| `FAILURE_CATEGORY` | Categorized failure type | `OOMKilled`, `ImagePull`, `Scheduling` | -| `ROOT_CAUSE` | Identified root cause | `Memory limit 512Mi too low for Java app` | -| `REMEDIATION` | Suggested fix | `Increase memory limit to 1Gi` | +**WAIT for user confirmation before proceeding.** + +For pod failure categories and exit code reference, see [debugging-patterns.md](../../docs/debugging-patterns.md). ## Dependencies ### Required MCP Servers -- `openshift` (kubernetes MCP server) +- `openshift` - Kubernetes/OpenShift resource access for pod status, events, and logs ### Related Skills - `/debug-build` - If pod failure is due to bad image from build - `/debug-network` - If pod is running but service connectivity fails - `/deploy` - To redeploy after fixing issues -## Reference Documentation - -For detailed guidance, see: +### Reference Documentation - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting trees - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification diff --git a/rh-developer/skills/debug-rhel/SKILL.md b/rh-developer/skills/debug-rhel/SKILL.md index e62ca0e1..b0e23d86 100644 --- a/rh-developer/skills/debug-rhel/SKILL.md +++ b/rh-developer/skills/debug-rhel/SKILL.md @@ -2,6 +2,8 @@ name: debug-rhel description: | Diagnose RHEL system issues including systemd service failures, SELinux denials, firewall blocking, and system resource problems. Automates multi-step diagnosis: journalctl log analysis, SELinux denial detection (ausearch), firewall rule inspection, and systemd unit status. Use this skill when applications fail on standalone RHEL/Fedora/CentOS hosts deployed via /rhel-deploy. Triggers on /debug-rhel command or phrases like "service won't start on RHEL", "SELinux blocking", "systemd failed", "firewall blocking". +model: inherit +color: cyan metadata: user_invocable: "true" --- @@ -33,33 +35,13 @@ Diagnose RHEL system issues by automatically gathering systemd status, journal l See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing diagnostic commands -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present findings clearly** and ask if user wants deeper analysis -4. **Never auto-execute** remediation commands without user approval - -If the user says "no" or wants to focus on specific areas, address their concerns before proceeding. - ## Note: SSH/Bash Required This skill operates on **remote RHEL hosts** via SSH, not local MCP servers. Unlike OpenShift/Podman skills, direct Bash commands with SSH are the correct approach here since MCP servers run locally and cannot access remote systems. -## Trigger - -- User types `/debug-rhel` -- User says "service won't start on RHEL", "systemd failed" -- User says "SELinux blocking", "AVC denied" -- User says "firewall blocking", "can't access port" -- User says "permission denied on RHEL" -- After `/rhel-deploy` reports a failure +## When to Use This Skill -## Input Parameters - -| Parameter | Description | Default | -|-----------|-------------|---------| -| `RHEL_HOST` | SSH target (user@host) | From session state | -| `SERVICE_NAME` | systemd service to debug | Auto-detect | +Use `/debug-rhel` when applications fail on standalone RHEL, Fedora, or CentOS hosts. This skill automates multi-step diagnosis of systemd service failures, SELinux denials, firewall blocking, and system resource problems via SSH. ## Workflow @@ -455,82 +437,18 @@ Select an option: **WAIT for user to select next action.** -## Common RHEL Issues - -### systemd Service Issues - -| Issue | Symptom | Diagnosis | Fix | -|-------|---------|-----------|-----| -| Unit not found | "not-found" load state | Service file missing | Create or install unit file | -| Exit code 1 | "failed" status | Application error | Check application logs | -| Exit code 126 | Permission issue | Cannot execute | Check ExecStart path/perms | -| Exit code 127 | Command not found | Binary missing | Install dependency | -| Exit code 203 | Exec format error | Wrong architecture | Rebuild for target arch | -| Exit code 217 | User not found | Bad User= directive | Create user or fix unit | - -### SELinux Common Denials - -| Denial Type | Symptom | Common Fix | -|-------------|---------|------------| -| Port binding | Cannot bind to port | `semanage port -a -t http_port_t -p tcp [port]` | -| File read | Cannot read config | `semanage fcontext` + `restorecon` | -| File write | Cannot write data | `semanage fcontext` + `restorecon` | -| Network connect | Cannot connect out | `setsebool -P httpd_can_network_connect on` | -| Container | Podman issues | `setsebool -P container_manage_cgroup on` | - -See [docs/selinux-troubleshooting.md](../../docs/selinux-troubleshooting.md) for detailed guidance. - -### Firewall Issues - -| Issue | Symptom | Fix | -|-------|---------|-----| -| Port not open | Connection refused from outside | `firewall-cmd --add-port=[port]/tcp` | -| Service not enabled | Standard service blocked | `firewall-cmd --add-service=[service]` | -| Zone mismatch | Rules in wrong zone | Check active zone, add to correct zone | -| Rich rule blocking | Specific traffic blocked | Review/remove rich rules | - -## MCP Tools Used - -This skill primarily uses Bash (SSH commands) since it operates on remote RHEL hosts. - -**Optional Lightspeed MCP tools** (used in Phase 7 if `lightspeed-mcp` is available): - -| Tool | Purpose | -|------|---------| -| `find_host_by_name` | Look up the target system in Red Hat Insights inventory | -| `get_system_cves` | Get CVEs affecting the specific system | -| `get_active_rules` | Get advisor configuration recommendations | -| `get_rule_by_text_search` | Search advisor recommendations by error text from logs | - -## Output Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `RHEL_HOST` | Target host | `user@192.168.1.100` | -| `SERVICE_NAME` | Debugged service | `myapp.service` | -| `SERVICE_STATUS` | Current status | `failed` | -| `SELINUX_DENIALS` | AVC denial count | `3` | -| `FIREWALL_BLOCKING` | Port blocked | `true` / `false` | -| `ROOT_CAUSE` | Identified root cause | `SELinux port binding denied` | -| `INSIGHTS_SYSTEM_ID` | Insights system ID (if registered) | `abc-def-123` | -| `CVE_COUNT` | Number of CVEs affecting system | `3` | +For common RHEL issues (systemd exit codes, SELinux denials, firewall), see [debugging-patterns.md](../../docs/debugging-patterns.md) and [selinux-troubleshooting.md](../../docs/selinux-troubleshooting.md). ## Dependencies -### Required Tools -- SSH client with key-based authentication -- sudo access on target host - -### Optional MCP Servers -- `lightspeed-mcp` - Red Hat Insights vulnerability, advisor, and inventory data (Phase 7) +### Required MCP Servers +- `lightspeed-mcp` (optional) - Red Hat Insights CVE and advisor checks in Phase 7 ### Related Skills -- `/rhel-deploy` - To redeploy after fixing issues -- `/debug-container` - To debug Podman containers on the host - -## Reference Documentation +- `/rhel-deploy` - redeploy after fixing issues +- `/debug-container` - debug Podman containers on the host -For detailed guidance, see: +### Reference Documentation - [docs/selinux-troubleshooting.md](../../docs/selinux-troubleshooting.md) - SELinux denial analysis - [docs/rhel-deployment.md](../../docs/rhel-deployment.md) - RHEL deployment patterns - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns diff --git a/rh-developer/skills/deploy/SKILL.md b/rh-developer/skills/deploy/SKILL.md index ab9154f4..dfc93d53 100644 --- a/rh-developer/skills/deploy/SKILL.md +++ b/rh-developer/skills/deploy/SKILL.md @@ -2,6 +2,10 @@ name: deploy description: | Create Kubernetes Deployment, Service, and Route resources on OpenShift to deploy and expose an application. Use this skill after /s2i-build to make the built image accessible. Handles port detection, replica configuration, HTTPS route creation, rollout monitoring, and rollback on failure. Triggers on /deploy command when user wants to deploy a container image to OpenShift. +model: inherit +color: green +metadata: + user_invocable: "true" --- # /deploy Skill @@ -15,17 +19,13 @@ Before running this skill: 2. Container image exists (from ImageStream or external registry) 3. Target namespace exists -## Critical: Human-in-the-Loop Requirements +## When to Use This Skill -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +Use `/deploy` after building a container image (via `/s2i-build` or external registry) to create Deployment, Service, and Route resources on OpenShift. This skill handles port detection, replica configuration, rollout monitoring, and rollback on failure. -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing any actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present options clearly** (yes/no/modify) and wait for response -4. **Never auto-execute** resource creation or deployments +## Critical: Human-in-the-Loop Requirements -If the user says "no" or wants modifications, address their concerns before proceeding. +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -51,7 +51,7 @@ If the user says "no" or wants modifications, address their concerns before proc Confirm these settings or tell me what to change. ``` -**WAIT for user confirmation before proceeding.** Do NOT continue until user explicitly confirms these settings or provides corrections. +**WAIT for user confirmation before proceeding.** ### Step 2: Detect Container Port @@ -77,7 +77,7 @@ Is this correct? - no - Specify the correct port ``` -**WAIT for user confirmation.** Do NOT proceed until user confirms the port or provides the correct value. +**WAIT for user confirmation before proceeding.** If unable to detect: ```markdown @@ -102,67 +102,14 @@ Show the Deployment manifest: ```markdown ## Step 1 of 3: Create Deployment -A Deployment manages your application pods. - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: [app-name] - namespace: [namespace] - labels: - app: [app-name] - app.kubernetes.io/name: [app-name] - annotations: - image.openshift.io/triggers: | - [{"from":{"kind":"ImageStreamTag","name":"[app-name]:latest"},"fieldPath":"spec.template.spec.containers[0].image"}] -spec: - replicas: [replicas] - selector: - matchLabels: - app: [app-name] - template: - metadata: - labels: - app: [app-name] - spec: - containers: - - name: [app-name] - image: image-registry.openshift-image-registry.svc:5000/[namespace]/[app-name]:latest - ports: - - containerPort: [port] - protocol: TCP - resources: - requests: - memory: "128Mi" - cpu: "100m" - limits: - memory: "512Mi" - cpu: "500m" - livenessProbe: - httpGet: - path: / - port: [port] - initialDelaySeconds: 30 - periodSeconds: 10 - readinessProbe: - httpGet: - path: / - port: [port] - initialDelaySeconds: 5 - periodSeconds: 5 -``` +Read `templates/deployment.yaml.template` and substitute `${APP_NAME}`, `${NAMESPACE}`, `${PORT}`, `${REPLICAS}` with session state values. -**This Deployment will:** -- Run [replicas] replica(s) of your application -- Use image from ImageStream: `[app-name]:latest` -- Expose container port: [port] -- Auto-update when new images are pushed +Show the rendered YAML to user and confirm. **Proceed with creating this Deployment?** (yes/no) ``` -**WAIT for user confirmation.** Do NOT create the Deployment until user explicitly says "yes". +**WAIT for user confirmation before proceeding.** - If user says "yes" → Use kubernetes MCP `resources_create_or_update` to apply - If user says "no" → Ask what they would like to change @@ -173,35 +120,14 @@ spec: ```markdown ## Step 2 of 3: Create Service -A Service provides internal load balancing to your pods. +Read `templates/service.yaml.template` and substitute `${APP_NAME}`, `${NAMESPACE}`, `${PORT}`. -```yaml -apiVersion: v1 -kind: Service -metadata: - name: [app-name] - namespace: [namespace] - labels: - app: [app-name] -spec: - selector: - app: [app-name] - ports: - - name: http - port: [port] - targetPort: [port] - protocol: TCP - type: ClusterIP -``` - -**This Service will:** -- Create internal DNS: `[app-name].[namespace].svc.cluster.local` -- Load balance traffic to pods on port [port] +Show the rendered YAML to user and confirm. **Proceed with creating this Service?** (yes/no) ``` -**WAIT for user confirmation.** Do NOT create the Service until user explicitly says "yes". +**WAIT for user confirmation before proceeding.** - If user says "yes" → Use kubernetes MCP `resources_create_or_update` to apply - If user says "no" → Ask what they would like to change @@ -214,38 +140,14 @@ If user wants external exposure: ```markdown ## Step 3 of 3: Create Route -A Route exposes your application externally with HTTPS. - -```yaml -apiVersion: route.openshift.io/v1 -kind: Route -metadata: - name: [app-name] - namespace: [namespace] - labels: - app: [app-name] -spec: - to: - kind: Service - name: [app-name] - weight: 100 - port: - targetPort: http - tls: - termination: edge - insecureEdgeTerminationPolicy: Redirect - wildcardPolicy: None -``` +Read `templates/route.yaml.template` and substitute `${APP_NAME}`, `${NAMESPACE}`. -**This Route will:** -- Expose app at: `https://[app-name]-[namespace].[cluster-domain]` -- Enable TLS with edge termination -- Redirect HTTP to HTTPS +Show the rendered YAML to user and confirm. **Proceed with creating this Route?** (yes/no/skip) ``` -**WAIT for user confirmation.** Do NOT create the Route until user explicitly responds. +**WAIT for user confirmation before proceeding.** - If user says "yes" → Use kubernetes MCP `resources_create_or_update` to apply - If user says "skip" → Skip Route creation and proceed to rollout monitoring @@ -360,38 +262,16 @@ oc delete all -l app=[app-name] -n [namespace] Your application is now live! ``` -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `resources_list` | Check existing deployments/services/routes | -| `resources_get` | Get resource details, route host | -| `resources_create_or_update` | Create Deployment, Service, Route | -| `pod_list` | Check pod status during rollout | -| `pod_logs` | Debug pod issues | -| `events_list` | Check events for errors | - -## Required Inputs - -| Input | Auto-detected | Must Confirm | -|-------|---------------|--------------| -| App name | Yes (from build) | Yes | -| Image | Yes (from ImageStream) | Yes | -| Port | Yes (from project files) | Yes | -| Replicas | Yes (default: 1) | Optional | -| Create Route | Yes (default: yes) | Yes | -| Namespace | Yes (from kubeconfig) | Yes | - -## Related Skills - -| Skill | Use When | -|-------|----------| -| `/debug-pod` | Pod failures (CrashLoopBackOff, OOMKilled, ImagePullBackOff) | -| `/debug-network` | Service connectivity issues (no endpoints, 503 errors) | -| `/debug-build` | Build failures before deployment | - -## Reference Documentation - -For detailed guidance, see: -- [docs/prerequisites.md](../docs/prerequisites.md) - Required tools (oc), cluster access verification -- [docs/debugging-patterns.md](../docs/debugging-patterns.md) - Common error patterns and troubleshooting +## Dependencies + +### Required MCP Servers +- `openshift` - cluster resource creation and management + +### Related Skills +- `/debug-pod` - Pod failures (CrashLoopBackOff, OOMKilled, ImagePullBackOff) +- `/debug-network` - Service connectivity issues (no endpoints, 503 errors) +- `/debug-build` - Build failures before deployment + +### Reference Documentation +- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification +- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting diff --git a/rh-developer/skills/detect-project/SKILL.md b/rh-developer/skills/detect-project/SKILL.md index 5b7d3222..7ddfa256 100644 --- a/rh-developer/skills/detect-project/SKILL.md +++ b/rh-developer/skills/detect-project/SKILL.md @@ -2,6 +2,10 @@ name: detect-project description: | Analyze a project folder or GitHub repository to detect programming language, framework, and version requirements. Use this skill when containerizing an application, selecting an S2I builder image, deploying to OpenShift or RHEL, or determining a project's tech stack. Supports Node.js, Python, Java, Go, Ruby, .NET, PHP, and Perl. Triggers on /detect-project command or when user needs build strategy recommendations. Run before /s2i-build or /rhel-deploy. +model: inherit +color: cyan +metadata: + user_invocable: "true" --- # /detect-project Skill @@ -13,15 +17,15 @@ description: | Analyze the project to detect language/framework and recommend a build strategy. This skill handles both local project directories and remote Git repositories. -## Critical: Human-in-the-Loop Requirements +## When to Use This Skill + +- User wants to containerize or deploy an application and needs language/framework detection +- User asks what tech stack a project uses or needs a build strategy recommendation +- Run before `/s2i-build`, `/recommend-image`, or `/rhel-deploy` to identify project type -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +## Critical: Human-in-the-Loop Requirements -**IMPORTANT:** This skill requires user confirmation before proceeding. You MUST: -1. **Wait for user confirmation** on detected values before saving to session state -2. **Do NOT assume** detection is correct - always present findings and ask for confirmation -3. **Present options clearly** when multiple choices exist and wait for selection -4. **Never auto-select** deployment strategies or images without user approval +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -36,8 +40,9 @@ If the user provided a Git URL (e.g., `https://github.com/...`): Use the **github-mcp-server** to analyze the repository directly without cloning: -1. Use GitHub MCP to list repository contents (look for indicator files) -2. Use GitHub MCP to read key files (`package.json`, `pom.xml`, `requirements.txt`, `Dockerfile`, etc.) +1. Use `mcp_github_get_file_contents(owner, repo, path="/")` to list repository contents +2. Read key files using `fetch_mcp_resource` with URI format: `repo://{owner}/{repo}/contents/{file-path}` + - Example: `repo://myorg/myrepo/contents/package.json` 3. Proceed with analysis as if local files ```markdown @@ -79,7 +84,7 @@ I couldn't access the repository directly. Options: **Which approach do you prefer?** ``` -**WAIT for user to select an option.** Do NOT proceed until user makes a choice. +**WAIT for user confirmation before proceeding.** **Scenario C: No Context** If no files and no URL: @@ -233,7 +238,7 @@ Please confirm: Type 'yes' to confirm all with quick image selection, 'smart' for tailored recommendation, or tell me what to change. ``` -**WAIT for user confirmation.** Do NOT save configuration or proceed until user explicitly confirms or provides corrections. +**WAIT for user confirmation before proceeding.** - If user says "yes" → Save configuration with quick image selection - If user says "smart" → Invoke `/recommend-image` skill @@ -253,56 +258,20 @@ After successful detection, these values should be available for other skills: | `VERSION` | Language version | `20` | | `BUILDER_IMAGE` | Full S2I image reference | `registry.access.redhat.com/ubi9/nodejs-20` | | `BUILD_STRATEGY` | Build strategy | `Source` (S2I) or `Podman` | -| `DEPLOYMENT_TARGET` | Deployment target | `openshift` or `rhel` | -| `DEPLOYMENT_STRATEGY` | Deployment method | `S2I`, `Podman`, `Helm` (OpenShift) or `container`, `native` (RHEL) | +| `CONTAINER_PORT` | Application listen port | `8080` | | `HELM_CHART_PATH` | Path to Helm chart | `./chart` | -| `HELM_CHART_NAME` | Helm chart name | `my-app` | -| `HELM_CHART_VERSION` | Helm chart version | `0.1.0` | -| `HELM_CHART_DETECTED` | Whether Helm chart was found | `true` or `false` | -| `RHEL_HOST` | SSH target for RHEL deployment | `user@192.168.1.100` | -| `PYTHON_ENTRY_FILE` | Python entry point file (Python only) | `main.py` | -| `PYTHON_APP_MODULE` | APP_MODULE value for S2I (Python only) | `main:app` | -| `PYTHON_HAS_GUNICORN` | Whether gunicorn is in requirements (Python only) | `true` or `false` | - -## MCP Tools Used - -This skill uses: - -### github-mcp-server (for remote repositories) - -**IMPORTANT: GitHub MCP has two different patterns for browsing vs reading:** - -#### Browsing Repository Structure -Use `mcp_github_get_file_contents` to **list directories**: -``` -mcp_github_get_file_contents(owner="org", repo="repo", path="/") → root listing -mcp_github_get_file_contents(owner="org", repo="repo", path="src") → src/ contents -``` -Returns: JSON array with file metadata (name, path, sha, type, download_url) - -#### Reading File Contents -Use `fetch_mcp_resource` with GitHub resource URI to **read actual file content**: -``` -fetch_mcp_resource(server="github", uri="repo://owner/repo/contents/path/to/file") -``` -Returns: Actual file content as text - -**URI Format:** `repo://{owner}/{repo}/contents/{file-path}` - -**Examples:** -- `repo://RHEcosystemAppEng/sast-ai-frontend/contents/package.json` -- `repo://facebook/react/contents/README.md` -- `repo://myorg/myrepo/contents/src/index.ts` -### Local file reading (for local projects) -- Standard file reading capabilities (`read_file` tool) +## Dependencies -### Terminal (fallback) -- `run_terminal_cmd` - Only if user selects "Clone & Inspect" for private repos +### Required MCP Servers +- `github` - Remote repository analysis via GitHub API (for URL-based detection) -## Reference Documentation +### Related Skills +- `/s2i-build` - Build with the detected S2I builder image +- `/recommend-image` - Advanced image selection based on detection results +- `/rhel-deploy` - Deploy to RHEL using detected project info -For detailed guidance, see: -- [docs/builder-images.md](../docs/builder-images.md) - Language detection matrix, version-to-image mapping, S2I builder selection -- [docs/python-s2i-entrypoints.md](../docs/python-s2i-entrypoints.md) - Python entry point detection, APP_MODULE configuration -- [docs/prerequisites.md](../docs/prerequisites.md) - Required tools (git) +### Reference Documentation +- [docs/builder-images.md](../../docs/builder-images.md) - Language detection matrix, version-to-image mapping, S2I builder selection +- [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python entry point detection, APP_MODULE configuration +- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (git) diff --git a/rh-developer/skills/helm-deploy/SKILL.md b/rh-developer/skills/helm-deploy/SKILL.md index bafc43df..2ebbde3e 100644 --- a/rh-developer/skills/helm-deploy/SKILL.md +++ b/rh-developer/skills/helm-deploy/SKILL.md @@ -2,6 +2,10 @@ name: helm-deploy description: | Deploy applications to OpenShift using Helm charts. Use this skill when user wants to deploy with Helm, when a Helm chart is detected in the project, or when /helm-deploy command is invoked. Supports both existing charts and chart creation. Handles chart detection, values customization, install/upgrade operations, and rollback. Requires kubernetes MCP Helm tools. +model: inherit +color: green +metadata: + user_invocable: "true" --- # /helm-deploy Skill @@ -14,17 +18,15 @@ Deploy applications to OpenShift using Helm charts. Supports existing charts or 2. Helm chart exists OR user wants to create one 3. Container image available (from registry or will be built) -## Critical: Human-in-the-Loop Requirements +## When to Use This Skill -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +- User wants to deploy an application using Helm charts on OpenShift +- A Helm chart is detected in the project (Chart.yaml found) +- User invokes `/helm-deploy` or asks about Helm-based deployment -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing any actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present options clearly** and wait for response -4. **Never auto-execute** chart creation, Helm installations, or upgrades +## Critical: Human-in-the-Loop Requirements -If the user says "no" or wants modifications, address their concerns before proceeding. +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -42,9 +44,7 @@ Use kubernetes MCP to verify cluster connection: Is this the correct cluster and namespace? (yes/no) ``` -**WAIT for user confirmation before proceeding.** Do NOT continue until user explicitly confirms. - -If user says "no", wait for them to switch context and tell you to continue. +**WAIT for user confirmation before proceeding.** ### Step 2: Detect Helm Chart @@ -132,10 +132,7 @@ I'll create a Helm chart based on your project. Proceed with creating the Helm chart? (yes/no) ``` -**WAIT for user confirmation.** Do NOT create the chart until user explicitly says "yes". - -- If user says "yes" → Create chart files -- If user says "no" → Ask what they would like to change or use a different approach +**WAIT for user confirmation before proceeding.** Use templates from templates/helm/ to generate: 1. Chart.yaml @@ -259,10 +256,7 @@ helm install [release-name] [chart-path] -n [namespace] [--set options] **Proceed with Helm deployment?** (yes/no) ``` -**WAIT for user confirmation.** Do NOT execute the Helm install/upgrade until user explicitly says "yes". - -- If user says "yes" → Proceed with deployment -- If user says "no" → Ask what they would like to change +**WAIT for user confirmation before proceeding.** ### Step 7: Execute Deployment @@ -346,34 +340,17 @@ oc logs -l app.kubernetes.io/instance=[release-name] -n [namespace] -f Your application is live! ``` -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `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 - -| Variable | Description | Example | -|----------|-------------|---------| -| `RELEASE_NAME` | Helm release name | `my-app` | -| `CHART_PATH` | Path to chart | `./chart` | -| `CHART_VERSION` | Chart version | `0.1.0` | -| `RELEASE_REVISION` | Current revision | `1` | -| `ROUTE_HOST` | External URL | `my-app-ns.apps.cluster.com` | - -## Reference Documentation - -For detailed guidance, see: -- [docs/builder-images.md](../docs/builder-images.md) - Container image references for chart values -- [docs/image-selection-criteria.md](../docs/image-selection-criteria.md) - Image variant selection for production deployments -- [docs/prerequisites.md](../docs/prerequisites.md) - Required tools (oc, helm) +## Dependencies + +### Required MCP Servers +- `openshift` - Helm install, upgrade, list, and uninstall operations + +### Related Skills +- `/deploy` - Alternative deployment without Helm charts +- `/debug-pod` - Troubleshoot pods after Helm deployment +- `/debug-network` - Diagnose networking issues with deployed services + +### Reference Documentation +- [docs/builder-images.md](../../docs/builder-images.md) - Container image references for chart values +- [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md) - Image variant selection for production deployments +- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc, helm) diff --git a/rh-developer/skills/recommend-image/SKILL.md b/rh-developer/skills/recommend-image/SKILL.md index 5767a4d2..deedc55c 100644 --- a/rh-developer/skills/recommend-image/SKILL.md +++ b/rh-developer/skills/recommend-image/SKILL.md @@ -2,6 +2,10 @@ name: recommend-image description: | Intelligently recommend the optimal S2I builder image or container base image for a project based on detected language/framework, use-case requirements, security posture, and deployment target. Supports GitHub URLs for remote project analysis (delegates to /detect-project). Use this skill when the user needs a container image recommendation, wants to compare image options, or asks about production vs development images. Triggers on /recommend-image command, or when advanced image selection beyond basic version matching is needed. Supports Node.js, Python, Java, Go, Ruby, .NET, PHP, and Perl on Red Hat UBI. +model: inherit +color: cyan +metadata: + user_invocable: "true" --- # /recommend-image Skill @@ -18,13 +22,7 @@ Provide intelligent, use-case-aware container image recommendations that go beyo ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. - -**IMPORTANT:** This skill requires user input and confirmation. You MUST: -1. **Wait for user responses** to all questions before proceeding -2. **Do NOT assume** user preferences - always ask -3. **Present options clearly** and wait for selection -4. **Confirm final recommendation** before saving to session state +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -106,7 +104,7 @@ To recommend the optimal image, please tell me about your requirements: Please describe your use case or select from the options above. ``` -**WAIT for user to provide their requirements.** Do NOT proceed until user describes their use case or selects options. +**WAIT for user confirmation before proceeding.** ### Step 3: Evaluate Image Options @@ -116,7 +114,7 @@ For each language, evaluate available variants against user requirements. **Key Scoring Factors:** Image size, security posture, build tools availability, startup time, LTS status -> **See [docs/image-selection-criteria.md](../docs/image-selection-criteria.md)** for comprehensive scoring matrices with weighted criteria by environment (production/development/edge/serverless). +> **See [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md)** for comprehensive scoring matrices with weighted criteria by environment (production/development/edge/serverless). ### Step 3.5: Dynamic Image Validation @@ -143,7 +141,7 @@ To provide accurate image recommendations, I need `skopeo` to inspect container - Check architecture support (amd64, arm64) - Show when the image was last built -**Install skopeo:** See [docs/prerequisites.md](../docs/prerequisites.md) for installation commands by OS. +**Install skopeo:** See [docs/prerequisites.md](../../docs/prerequisites.md) for installation commands by OS. After installing, run `/recommend-image` again for enhanced recommendations. @@ -152,7 +150,7 @@ After installing, run `/recommend-image` again for enhanced recommendations. - **install** - I'll install skopeo first ``` -**WAIT for user to select an option.** Do NOT proceed until user chooses. +**WAIT for user confirmation before proceeding.** If user continues without skopeo, proceed with static data and note: "Image metadata from static reference (not verified)". @@ -233,7 +231,7 @@ Based on your requirements: - Tell me if you have different requirements ``` -**WAIT for user to confirm or select an alternative.** Do NOT save configuration until user explicitly confirms. +**WAIT for user confirmation before proceeding.** ### Step 5: Handle Confirmation @@ -266,23 +264,19 @@ Return to Step 2 with new inputs. - **Development** → Full variant - **Serverless** → Smallest available (minimal or native binary) -> **See [docs/image-selection-criteria.md](../docs/image-selection-criteria.md)** for comprehensive image size references, LTS timelines, decision trees, and framework-specific recommendations (Quarkus, Spring Boot, Next.js, Django/Flask). - -## Output Variables +> **See [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md)** for comprehensive image size references, LTS timelines, decision trees, and framework-specific recommendations (Quarkus, Spring Boot, Next.js, Django/Flask). -After successful recommendation: +## Dependencies -| Variable | Description | Example | -|----------|-------------|---------| -| `BUILDER_IMAGE` | Full image reference | `registry.access.redhat.com/ubi9/nodejs-20-minimal` | -| `IMAGE_VARIANT` | Variant type | `minimal` | -| `SELECTION_RATIONALE` | Why this image | "Minimal variant for production security" | -| `ALTERNATIVES` | Fallback options | `["ubi9/nodejs-20", "ubi9/nodejs-22-minimal"]` | +### Required MCP Servers +- None required (uses Bash for skopeo image inspection) -## Reference Documentation +### Related Skills +- `/detect-project` - Provides language/framework detection input for recommendations +- `/s2i-build` - Build with the recommended image -For detailed guidance, see: -- [docs/image-selection-criteria.md](../docs/image-selection-criteria.md) - Comprehensive scoring matrices, image size reference, LTS timelines, decision trees -- [docs/builder-images.md](../docs/builder-images.md) - UBI image registry, framework-specific recommendations, variant availability -- [docs/dynamic-validation.md](../docs/dynamic-validation.md) - Skopeo commands, Red Hat Security Data API, image verification patterns -- [docs/prerequisites.md](../docs/prerequisites.md) - Skopeo installation instructions +### Reference Documentation +- [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md) - Comprehensive scoring matrices, image size reference, LTS timelines, decision trees +- [docs/builder-images.md](../../docs/builder-images.md) - UBI image registry, framework-specific recommendations, variant availability +- [docs/dynamic-validation.md](../../docs/dynamic-validation.md) - Skopeo commands, Red Hat Security Data API, image verification patterns +- [docs/prerequisites.md](../../docs/prerequisites.md) - Skopeo installation instructions diff --git a/rh-developer/skills/rhel-deploy/SKILL.md b/rh-developer/skills/rhel-deploy/SKILL.md index d9b62cff..75237c99 100644 --- a/rh-developer/skills/rhel-deploy/SKILL.md +++ b/rh-developer/skills/rhel-deploy/SKILL.md @@ -2,6 +2,10 @@ name: rhel-deploy description: | CRITICAL: When user types /rhel-deploy, use THIS skill immediately. This skill deploys applications to standalone RHEL/Fedora/CentOS systems (NOT OpenShift) using Podman containers with systemd, or native dnf builds. Handles SSH connectivity, SELinux, firewall-cmd, and systemd unit creation. Triggers: /rhel-deploy command, 'deploy to RHEL', 'deploy to Fedora', 'deploy to my server via SSH'. +model: inherit +color: yellow +metadata: + user_invocable: "true" --- # /rhel-deploy Skill @@ -31,47 +35,21 @@ Deploy applications to standalone RHEL systems using Podman containers or native 3. For container deployments: Podman installed on target 4. For native deployments: Required development tools available via dnf -## Critical: Human-in-the-Loop Requirements +## When to Use This Skill -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +Use `/rhel-deploy` when deploying applications to standalone RHEL, Fedora, or CentOS systems via SSH. This skill handles Podman container or native dnf deployments with systemd service management, SELinux, and firewall configuration. -**IMPORTANT:** This skill requires explicit user confirmation at each phase. You MUST: -1. **Wait for user confirmation** before executing any actions -2. **Do NOT proceed** to the next phase until the user explicitly approves -3. **Present options clearly** (yes/no/modify) and wait for response -4. **Never auto-execute** SSH commands, file transfers, or service creation +## Critical: Human-in-the-Loop Requirements -If the user says "no" or wants modifications, address their concerns before proceeding. +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow ### Phase 0: Introduction -```markdown -# Deploy to RHEL Host - -I'll help you deploy your application to a RHEL system. - -**What this workflow does:** -1. **Connect** - Establish SSH connection to your RHEL host -2. **Analyze** - Check target system capabilities (Podman, SELinux, firewall) -3. **Build** - Build container image or prepare native deployment -4. **Deploy** - Configure systemd service and networking -5. **Verify** - Ensure application is running and accessible - -**Deployment Strategies:** -- **Container (Podman)** - Run your app in a container managed by systemd -- **Native** - Install and run your app directly on the host - -**What I need from you:** -- SSH access to the target RHEL host (user@host) -- sudo privileges on the target host -- Your application source code - -**Ready to begin?** (yes/no) -``` +Present the workflow overview: Connect → Analyze → Strategy → Build/Deploy → Verify. Describe Container (Podman + systemd) vs Native (dnf + systemd) strategies. Ask: **Ready to begin?** (yes/no) -Wait for user confirmation before proceeding. +**WAIT for user confirmation before proceeding.** ### Phase 1: SSH Connection @@ -96,15 +74,11 @@ Example: `user@192.168.1.100` or `deploy@myserver.example.com` **Connection verification:** ```bash -# Test SSH connection ssh -o BatchMode=yes -o ConnectTimeout=10 [user]@[host] "echo 'Connection successful'" - -# If connection fails, provide troubleshooting: -# - Check host is reachable: ping [host] -# - Verify SSH key is configured -# - Check firewall allows SSH (port 22) ``` +If connection fails, troubleshoot: host reachability, SSH key configuration, firewall port 22. + Store `RHEL_HOST`, `RHEL_USER`, `RHEL_PORT` in session state. ### Phase 2: Target Host Analysis @@ -114,46 +88,26 @@ Store `RHEL_HOST`, `RHEL_USER`, `RHEL_PORT` in session state. Checking capabilities of [host]... -**System Information:** | Setting | Value | |---------|-------| | OS | [cat /etc/redhat-release] | | Kernel | [uname -r] | | Architecture | [uname -m] | - -**Container Runtime:** -| Setting | Status | -|---------|--------| | Podman | [Installed v4.x / Not installed] | -| Container Storage | [/var/lib/containers] | - -**System Services:** -| Setting | Status | -|---------|--------| | SELinux | [Enforcing / Permissive / Disabled] | | Firewall | [Active / Inactive] | -| systemd | Running | Is this the correct target host? (yes/no) ``` -**WAIT for user confirmation before proceeding.** Do NOT continue to Phase 3 until user confirms. - -If user says "no", ask what needs to be changed or allow them to specify a different host. +**WAIT for user confirmation before proceeding.** **Commands to gather information:** ```bash -# RHEL version ssh [target] "cat /etc/redhat-release" - -# Podman check ssh [target] "podman --version 2>/dev/null || echo 'Not installed'" - -# SELinux status ssh [target] "getenforce" - -# Firewall status ssh [target] "firewall-cmd --state 2>/dev/null || echo 'Not running'" ``` @@ -188,14 +142,6 @@ Append to Phase 2 output: These are informational warnings only — they do not block deployment. -**MCP tools used:** - -| Tool | Purpose | -|------|---------| -| `find_host_by_name` | Look up target system in Red Hat Insights | -| `get_system_cves` | Check CVEs on target system | -| `get_rhel_lifecycle` | Verify RHEL version support status | - ### Phase 3: Strategy Selection ```markdown @@ -215,7 +161,7 @@ Based on your project ([language]/[framework]) and target capabilities: 2. Native - Deploy directly on host ``` -**WAIT for user to select a strategy.** Do NOT proceed until user makes a choice. +**WAIT for user confirmation before proceeding.** **If Podman not installed and user selects Container:** ```markdown @@ -228,7 +174,7 @@ sudo dnf install -y podman Proceed with Podman installation? (yes/no) ``` -**WAIT for user confirmation.** Only install Podman if user explicitly says "yes". +**WAIT for user confirmation before proceeding.** Store `DEPLOYMENT_STRATEGY` in session state. @@ -250,7 +196,7 @@ Store `DEPLOYMENT_STRATEGY` in session state. Which approach would you prefer? ``` -**WAIT for user to select an option.** Do NOT proceed until user makes a choice. +**WAIT for user confirmation before proceeding.** **For options 1 and 2 (building an image):** @@ -268,26 +214,14 @@ Use the `BUILDER_IMAGE` output from `/recommend-image` as the base image in the **For build on target:** ```bash -# Transfer source +# Transfer source and build rsync -avz --exclude node_modules --exclude .git ./ [target]:/tmp/[app-name]-build/ - -# If no Containerfile exists, create one with recommended base image -ssh [target] "test -f /tmp/[app-name]-build/Containerfile -o -f /tmp/[app-name]-build/Dockerfile" || \ -ssh [target] "cat > /tmp/[app-name]-build/Containerfile << 'EOF' -FROM [BUILDER_IMAGE] -# Containerfile generated using /recommend-image -WORKDIR /app -COPY . . -# Add language-specific build and run commands -EOF" - -# Build on target +# If no Containerfile exists, generate one using BUILDER_IMAGE from /recommend-image ssh [target] "cd /tmp/[app-name]-build && podman build -t [app-name]:latest ." ``` **For existing image:** ```bash -# Pull image on target ssh [target] "podman pull [image-reference]" ``` @@ -306,16 +240,12 @@ ssh [target] "podman pull [image-reference]" | Environment | [list env vars] | | Run Mode | [rootless / rootful] | -**SELinux Volume Labels:** Use `:z` for shared volumes, `:Z` for private volumes. See [docs/rhel-deployment.md](../docs/rhel-deployment.md) for SELinux configuration details. +**SELinux Volume Labels:** Use `:z` for shared volumes, `:Z` for private volumes. See [docs/rhel-deployment.md](../../docs/rhel-deployment.md) for SELinux configuration details. Proceed with this configuration? (yes/modify/cancel) ``` -**WAIT for user confirmation.** Do NOT proceed until user explicitly approves. - -- If user says "yes" → Continue to systemd unit creation -- If user says "modify" → Ask what they would like to change -- If user says "cancel" → Stop and preserve current state +**WAIT for user confirmation before proceeding.** ### Phase 4a-3: Systemd Unit Creation @@ -342,10 +272,7 @@ Creating systemd unit for Podman container. Proceed with creating this service? (yes/no) ``` -**WAIT for user confirmation.** Do NOT create the systemd unit until user explicitly says "yes". - -- If user says "yes" → Read the appropriate template, substitute variables, and create the service -- If user says "no" → Ask what they would like to change +**WAIT for user confirmation before proceeding.** **Steps to execute:** @@ -355,17 +282,9 @@ Proceed with creating this service? (yes/no) 4. Enable and start the service ```bash -# For rootful: -ssh [target] "sudo tee /etc/systemd/system/[app-name].service" < [generated-unit-file] -ssh [target] "sudo systemctl daemon-reload" -ssh [target] "sudo systemctl enable --now [app-name]" - -# For rootless: -ssh [target] "mkdir -p ~/.config/systemd/user" -ssh [target] "tee ~/.config/systemd/user/[app-name].service" < [generated-unit-file] -ssh [target] "systemctl --user daemon-reload" -ssh [target] "systemctl --user enable --now [app-name]" -ssh [target] "loginctl enable-linger [user]" # Keep user services running +# Rootful: transfer to /etc/systemd/system/, daemon-reload, enable --now +# Rootless: transfer to ~/.config/systemd/user/, daemon-reload, enable --now, enable-linger +ssh [target] "sudo systemctl daemon-reload && sudo systemctl enable --now [app-name]" ``` ### Phase 4a-4: Firewall Configuration @@ -390,10 +309,7 @@ sudo firewall-cmd --list-ports Proceed with firewall configuration? (yes/skip) ``` -**WAIT for user confirmation.** Do NOT modify firewall until user explicitly responds. - -- If user says "yes" → Configure firewall -- If user says "skip" → Skip firewall configuration and continue +**WAIT for user confirmation before proceeding.** --- @@ -406,7 +322,7 @@ Proceed with firewall configuration? (yes/skip) **Runtime packages for [language]:** -See [docs/rhel-deployment.md](../docs/rhel-deployment.md) for the complete runtime package mapping by language and RHEL version (Node.js, Python, Java, Go, Ruby, PHP). +See [docs/rhel-deployment.md](../../docs/rhel-deployment.md) for the complete runtime package mapping by language and RHEL version (Node.js, Python, Java, Go, Ruby, PHP). **Commands to execute:** ```bash @@ -416,7 +332,7 @@ ssh [target] "sudo dnf install -y [packages]" Proceed with installation? (yes/no) ``` -**WAIT for user confirmation.** Do NOT install packages until user explicitly says "yes". +**WAIT for user confirmation before proceeding.** ### Phase 4b-2: Application Deployment @@ -433,21 +349,11 @@ Proceed with installation? (yes/no) 5. Configure SELinux context ```bash -# Create directory ssh [target] "sudo mkdir -p /opt/[app-name]" - -# Transfer files -rsync -avz --exclude node_modules --exclude .git --exclude __pycache__ \ - ./ [target]:/tmp/[app-name]-deploy/ +rsync -avz --exclude node_modules --exclude .git --exclude __pycache__ ./ [target]:/tmp/[app-name]-deploy/ ssh [target] "sudo cp -r /tmp/[app-name]-deploy/* /opt/[app-name]/" - -# Install dependencies (example for Node.js) -ssh [target] "cd /opt/[app-name] && npm install --production" - -# Set permissions +ssh [target] "cd /opt/[app-name] && npm install --production" # language-specific ssh [target] "sudo chown -R [service-user]:[service-user] /opt/[app-name]" - -# SELinux context ssh [target] "sudo semanage fcontext -a -t bin_t '/opt/[app-name](/.*)?'" ssh [target] "sudo restorecon -Rv /opt/[app-name]" ``` @@ -455,7 +361,7 @@ ssh [target] "sudo restorecon -Rv /opt/[app-name]" Proceed with deployment? (yes/no) ``` -**WAIT for user confirmation.** Do NOT transfer files or deploy until user explicitly says "yes". +**WAIT for user confirmation before proceeding.** ### Phase 4b-3: Native Systemd Unit @@ -473,7 +379,7 @@ Proceed with deployment? (yes/no) | `${PORT}` | [container-port] | Application listen port | | `${START_COMMAND}` | [see below] | Language-specific start command | -**Start commands by language:** See [docs/rhel-deployment.md](../docs/rhel-deployment.md) for language-specific systemd unit templates (Node.js, Python, Java, Go). +**Start commands by language:** See [docs/rhel-deployment.md](../../docs/rhel-deployment.md) for language-specific systemd unit templates (Node.js, Python, Java, Go). **Target location:** `/etc/systemd/system/[app-name].service` @@ -482,7 +388,7 @@ Proceed with deployment? (yes/no) Proceed with creating this service? (yes/no) ``` -**WAIT for user confirmation.** Do NOT create the systemd unit until user explicitly says "yes". +**WAIT for user confirmation before proceeding.** **Steps to execute:** @@ -506,8 +412,6 @@ Same as container path - open required port with firewall-cmd. Your application is now running on [host]. ---- - **Application Summary:** | Setting | Value | |---------|-------| @@ -516,51 +420,17 @@ Your application is now running on [host]. | Strategy | [Container/Native] | | Service | [app-name].service | ---- - **Access URLs:** | Type | URL | |------|-----| | HTTP | http://[host]:[port] | | SSH | ssh [user]@[host] | ---- - -**Service Status:** -``` -[systemctl status output] -``` - ---- +**Service Status:** [systemctl status output] **Quick Commands:** -```bash -# View logs -sudo journalctl -u [app-name] -f - -# Restart service -sudo systemctl restart [app-name] - -# Stop service -sudo systemctl stop [app-name] - -# Check status -sudo systemctl status [app-name] - -# View container logs (if container deployment) -podman logs -f [app-name] - -# Remove deployment -sudo systemctl disable --now [app-name] -sudo rm /etc/systemd/system/[app-name].service -# For container: podman rm [app-name] -# For native: sudo rm -rf /opt/[app-name] -``` - ---- - -Your application is live! +Show quick commands for: view logs (journalctl), restart/stop/status (systemctl), container logs (if container), and removal steps. ``` ### Phase 5a: Handle Deployment Failure @@ -572,33 +442,19 @@ If the service fails to start or is not accessible: The service did not start successfully. -**Service Status:** -``` -[systemctl status output showing failure] -``` +**Service Status:** [systemctl status output showing failure] **Recent Errors:** | Time | Error | |------|-------| | [time] | [error from journalctl] | ---- - **Would you like me to diagnose the issue?** - -1. **Debug RHEL** (`/debug-rhel`) - Full system diagnosis - - Analyzes systemd status, journal logs, SELinux denials, firewall rules - - Identifies root cause and suggests remediation - -2. **Debug Container** (`/debug-container`) - If using container deployment - - Analyzes container state, logs, exit codes - -3. **View full logs** - Show complete journalctl output - +1. **Debug RHEL** (`/debug-rhel`) - Full system diagnosis (systemd, journal, SELinux, firewall) +2. **Debug Container** (`/debug-container`) - Container state, logs, exit codes +3. **View full logs** - Complete journalctl output 4. **Check SELinux** - Quick SELinux denial check - 5. **Check firewall** - Quick firewall port check - 6. **Stop and clean up** Select an option: @@ -610,34 +466,17 @@ Select an option: - If user selects "Debug Container" → Invoke `/debug-container` skill - After debugging → Offer to retry deployment -## Delegated Skills - -This skill delegates to other skills when needed: - -| Scenario | Delegated Skill | Purpose | -|----------|-----------------|---------| -| Building container image (no Containerfile) | `/recommend-image` | Get optimal UBI base image for the detected language/framework | - -When delegating to `/recommend-image`: -1. Provide detected `LANGUAGE`, `FRAMEWORK`, and `VERSION` from project analysis -2. Receive back: `BUILDER_IMAGE`, `IMAGE_VARIANT`, `SELECTION_RATIONALE` -3. Use `BUILDER_IMAGE` as the FROM image in generated Containerfile - -## Related Skills - -| Skill | Use When | -|-------|----------| -| `/debug-rhel` | systemd failures, SELinux denials, firewall blocking, Insights CVE/advisor analysis | -| `/debug-container` | Container startup issues on RHEL host | - -## Optional MCP Servers +## Dependencies -- `lightspeed-mcp` - Red Hat Insights vulnerability and planning data (Phase 2b) +### Required MCP Servers +- `lightspeed-mcp` (optional) - Red Hat Insights pre-deploy checks -## Reference Documentation +### Related Skills +- `/debug-rhel` - systemd failures, SELinux denials, firewall blocking +- `/debug-container` - Container startup issues on RHEL host -For detailed guidance, see: -- [docs/rhel-deployment.md](../docs/rhel-deployment.md) - Comprehensive RHEL deployment reference: systemd unit templates, SELinux configuration, firewall commands, runtime package mapping -- [docs/selinux-troubleshooting.md](../docs/selinux-troubleshooting.md) - SELinux denial analysis and fixes -- [docs/debugging-patterns.md](../docs/debugging-patterns.md) - Common error patterns and troubleshooting -- [docs/prerequisites.md](../docs/prerequisites.md) - Required tools (ssh, podman) +### Reference Documentation +- [docs/rhel-deployment.md](../../docs/rhel-deployment.md) - Systemd templates, SELinux, firewall, runtime packages +- [docs/selinux-troubleshooting.md](../../docs/selinux-troubleshooting.md) - SELinux denial analysis and fixes +- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting +- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (ssh, podman) diff --git a/rh-developer/skills/s2i-build/SKILL.md b/rh-developer/skills/s2i-build/SKILL.md index 105a9408..5e0b6efa 100644 --- a/rh-developer/skills/s2i-build/SKILL.md +++ b/rh-developer/skills/s2i-build/SKILL.md @@ -2,6 +2,10 @@ name: s2i-build description: | Create BuildConfig and ImageStream resources on OpenShift and trigger a Source-to-Image (S2I) build. Use this skill after /detect-project to build container images from source code on the cluster. Handles namespace verification, resource creation with user confirmation, build monitoring with log streaming, and failure recovery. Triggers on /s2i-build command. Run before /deploy. +model: inherit +color: green +metadata: + user_invocable: "true" --- # /s2i-build Skill @@ -15,17 +19,13 @@ Before running this skill, ensure: 2. Target namespace/project exists or can be created 3. Git repository URL is available (or will use binary build) -## Critical: Human-in-the-Loop Requirements +## When to Use This Skill -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +Use this skill after `/detect-project` to build container images from source code on OpenShift using Source-to-Image. It creates BuildConfig and ImageStream resources, triggers the build, and monitors progress with log streaming. -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing any actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present options clearly** (yes/no/modify) and wait for response -4. **Never auto-execute** resource creation, builds, or deployments +## Critical: Human-in-the-Loop Requirements -If the user says "no" or wants modifications, address their concerns before proceeding. +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -45,9 +45,7 @@ Is this the correct cluster and namespace for the build? - no - Let me switch context ``` -**WAIT for user confirmation before proceeding.** Do NOT continue to Step 2 until user confirms. - -If user says "no", wait for them to switch context and tell you to continue. +**WAIT for user confirmation before proceeding.** ### Step 2: Gather Build Information @@ -93,9 +91,7 @@ Your application uses `[PYTHON_ENTRY_FILE]` as entry point, but `gunicorn` is no 3. **Continue anyway** - Proceed (build will likely fail) ``` -**WAIT for user to resolve the issue before proceeding.** - -**WAIT for user confirmation before proceeding.** Do NOT continue until user explicitly confirms these values or provides corrections. +**WAIT for user confirmation before proceeding.** **To detect Git URL:** - Read `.git/config` and extract `[remote "origin"]` url @@ -118,7 +114,7 @@ Namespace `[namespace]` does not exist. Would you like me to create it? (yes/no) ``` -**WAIT for user confirmation.** Only create the namespace if user explicitly says "yes". +**WAIT for user confirmation before proceeding.** If creating namespace, use `resources_create_or_update`: ```yaml @@ -154,11 +150,7 @@ spec: **Proceed with creating this ImageStream?** (yes/no) ``` -**WAIT for user confirmation.** Do NOT create the ImageStream until user explicitly says "yes". - -- If user says "yes" → Use kubernetes MCP `resources_create_or_update` to apply -- If user says "no" → Ask what they would like to change -- If user wants modifications → Update the YAML and show again for confirmation +**WAIT for user confirmation before proceeding.** ### Step 5: Create BuildConfig @@ -265,11 +257,7 @@ spec: **Proceed with creating this BuildConfig?** (yes/no) ``` -**WAIT for user confirmation.** Do NOT create the BuildConfig until user explicitly says "yes". - -- If user says "yes" → Use kubernetes MCP `resources_create_or_update` to apply -- If user says "no" → Ask what they would like to change -- If user wants modifications → Update the YAML and show again for confirmation +**WAIT for user confirmation before proceeding.** ### Step 6: Start Build @@ -288,10 +276,7 @@ Resources created successfully! (You can also trigger builds later with: oc start-build [app-name]) ``` -**WAIT for user confirmation.** Do NOT start the build until user explicitly says "yes". - -- If user says "yes" → Create a Build resource as shown below -- If user says "no" → Complete this step and inform user how to start build manually later +**WAIT for user confirmation before proceeding.** If yes, create a Build resource: ```yaml @@ -390,48 +375,17 @@ What would you like to do? - If user selects "Debug Build" → Invoke `/debug-build` skill with build name - After debugging → Offer to retry build -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `resources_list` | Check namespaces, existing ImageStreams/BuildConfigs | -| `resources_get` | Get specific resource details | -| `resources_create_or_update` | Create ImageStream, BuildConfig, Build | -| `pod_logs` | Stream build logs (builds run as pods) | -| `pod_list` | Find builder pod | -| `events_list` | Check for build events/errors | - -## Required Inputs - -| Input | Auto-detected | Must Confirm | -|-------|---------------|--------------| -| App name | Yes (from detect-project) | Yes | -| Git URL | Yes (from .git/config) | Yes | -| Git branch | Yes (default: main) | Optional | -| S2I image | Yes (from detect-project) | Yes | -| Namespace | Yes (from kubeconfig) | Yes | - -## Output - -On success, these values are available for `/deploy`: - -| Variable | Value | -|----------|-------| -| `IMAGE_REF` | `image-registry.openshift-image-registry.svc:5000/[ns]/[app]:latest` | -| `IMAGESTREAM_TAG` | `[app]:latest` | -| `BUILD_NAME` | `[app]-1` | - -## Related Skills +## Dependencies -| Skill | Use When | -|-------|----------| -| `/debug-build` | Build failures (source access, dependencies, registry issues) | -| `/deploy` | After successful build, to deploy the image | +### Required MCP Servers +- `openshift` - Kubernetes/OpenShift resource access for BuildConfigs, ImageStreams, and build monitoring -## Reference Documentation +### Related Skills +- `/debug-build` - Build failures (source access, dependencies, registry issues) +- `/deploy` - After successful build, to deploy the image -For detailed guidance, see: -- [docs/builder-images.md](../docs/builder-images.md) - S2I builder image selection, version mapping -- [docs/python-s2i-entrypoints.md](../docs/python-s2i-entrypoints.md) - Python APP_MODULE configuration, entry point troubleshooting -- [docs/debugging-patterns.md](../docs/debugging-patterns.md) - Common build error patterns and troubleshooting -- [docs/prerequisites.md](../docs/prerequisites.md) - Required tools (oc) +### Reference Documentation +- [docs/builder-images.md](../../docs/builder-images.md) - S2I builder image selection, version mapping +- [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python APP_MODULE configuration, entry point troubleshooting +- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common build error patterns and troubleshooting +- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc) diff --git a/rh-developer/skills/validate-environment/SKILL.md b/rh-developer/skills/validate-environment/SKILL.md index 74b97072..85cf8d8a 100644 --- a/rh-developer/skills/validate-environment/SKILL.md +++ b/rh-developer/skills/validate-environment/SKILL.md @@ -2,6 +2,8 @@ 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. +model: inherit +color: cyan metadata: user_invocable: "true" --- @@ -10,27 +12,22 @@ metadata: Check that required tools and environment are properly configured. +## When to Use This Skill + +- User wants to verify their environment before running deployment skills +- User encounters tool-related errors and needs a diagnostic check +- First-time setup or after environment changes to confirm readiness + ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. **Key Rules:** 1. WAIT for user to select validation scope before running checks 2. Present results clearly and ask if user wants to proceed with fixes 3. Never auto-fix issues without user approval -## 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 +## Workflow ### Step 1: Determine Validation Scope @@ -66,7 +63,7 @@ check_tool() { **Tools to check:** git, curl, jq, oc, helm, podman, docker, skopeo, ssh -> **See [docs/prerequisites.md](../docs/prerequisites.md)** for the complete tool requirements by skill, check commands, and installation instructions. +> **See [docs/prerequisites.md](../../docs/prerequisites.md)** for the complete tool requirements by skill, check commands, and installation instructions. ### Step 3: Check OpenShift Connectivity (if TARGET includes openshift) @@ -186,7 +183,7 @@ Select an option or describe what you'd like to do: This tool is required for [skill-names]. -See [docs/prerequisites.md](../docs/prerequisites.md) for installation commands by OS. +See [docs/prerequisites.md](../../docs/prerequisites.md) for installation commands by OS. ``` ### Cluster Connection Failed @@ -221,16 +218,15 @@ Options: --- -## Output Variables +## Dependencies -| 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` | +### Required MCP Servers +- None required (uses Bash to check tool availability and cluster connectivity) -## Reference Documentation +### Related Skills +- `/containerize-deploy` - End-to-end deployment workflow (validate environment first) +- `/s2i-build` - S2I build requiring oc and cluster access +- `/deploy` - Deployment requiring oc and cluster access -For detailed guidance, see: -- [docs/prerequisites.md](../docs/prerequisites.md) - Comprehensive tool requirements by skill, installation commands, cluster access verification +### Reference Documentation +- [docs/prerequisites.md](../../docs/prerequisites.md) - Comprehensive tool requirements by skill, installation commands, cluster access verification