Skip to content

Commit 9d601d4

Browse files
swghoshswghosh
committed
update docs and README with openshift tools
Signed-off-by: Swarup Ghosh <swghosh@redhat.com>
1 parent eaf3a3c commit 9d601d4

File tree

3 files changed

+244
-0
lines changed

3 files changed

+244
-0
lines changed

‎.claude/settings.local.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Bash(*)"
5+
]
6+
}
7+
}

‎README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -403,6 +403,7 @@ The following sets of tools are available (toolsets marked with ✓ in the Defau
403403
| config | View and manage the current local Kubernetes configuration (kubeconfig) | ✓ |
404404
| core | Most common tools for Kubernetes management (Pods, Generic Resources, Events, etc.) | ✓ |
405405
| kcp | Manage kcp workspaces and multi-tenancy features | |
406+
| openshift | OpenShift-specific tools for cluster management and troubleshooting, check the [OpenShift documentation](docs/OPENSHIFT.md) for more details. | |
406407
| ossm | Most common tools for managing OSSM, check the [OSSM documentation](https://github.com/openshift/openshift-mcp-server/blob/main/docs/OSSM.md) for more details. | |
407408
| kubevirt | KubeVirt virtual machine management tools | |
408409
| observability | Cluster observability tools for querying Prometheus metrics and Alertmanager alerts | ✓ |
@@ -696,6 +697,25 @@ Common use cases:
696697

697698
</details>
698699

700+
<details>
701+
702+
<summary>openshift</summary>
703+
704+
- **plan_mustgather** - Plan for collecting a must-gather archive from an OpenShift cluster, must-gather is a tool for collecting cluster data related to debugging and troubleshooting like logs, kubernetes resources, etc.
705+
- `node_name` (`string`) - Optional node to run the mustgather pod. If not provided, a random control-plane node will be selected automatically
706+
- `node_selector` (`string`) - Optional node label selector to use, only relevant when specifying a command and image which needs to capture data on a set of cluster nodes simultaneously
707+
- `host_network` (`boolean`) - Optionally run the must-gather pods in the host network of the node. This is only relevant if a specific gather image needs to capture host-level data
708+
- `gather_command` (`string`) - Optionally specify a custom gather command to run a specialized script, eg. /usr/bin/gather_audit_logs (default: /usr/bin/gather)
709+
- `all_component_images` (`boolean`) - Optional when enabled, collects and runs multiple must gathers for all operators and components on the cluster that have an annotated must-gather image available
710+
- `images` (`array`) - Optional list of images to use for gathering custom information about specific operators or cluster components. If not specified, OpenShift's default must-gather image will be used by default
711+
- `source_dir` (`string`) - Optional to set a specific directory where the pod will copy gathered data from (default: /must-gather)
712+
- `timeout` (`string`) - Timeout of the gather process eg. 30s, 6m20s, or 2h10m30s
713+
- `namespace` (`string`) - Optional to specify an existing privileged namespace where must-gather pods should run. If not provided, a temporary namespace will be created
714+
- `keep_resources` (`boolean`) - Optional to retain all temporary resources when the mustgather completes, otherwise temporary resources created will be advised to be cleaned up
715+
- `since` (`string`) - Optional to collect logs newer than a relative duration like 5s, 2m5s, or 3h6m10s. If unspecified, all available logs will be collected
716+
717+
</details>
718+
699719

700720
<!-- AVAILABLE-TOOLSETS-TOOLS-END -->
701721

‎docs/OPENSHIFT.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# OpenShift Toolset
2+
3+
This toolset provides OpenShift-specific tools for cluster management and troubleshooting.
4+
5+
## Tools
6+
7+
### plan_mustgather
8+
9+
Plan for collecting a must-gather archive from an OpenShift cluster. Must-gather is a tool for collecting cluster data related to debugging and troubleshooting like logs, Kubernetes resources, and more.
10+
11+
**Parameters:**
12+
- `node_name` (optional) - Node to run the must-gather pod. If not provided, a random control-plane node will be selected automatically
13+
- `node_selector` (optional) - Node label selector to use, only relevant when specifying a command and image which needs to capture data on a set of cluster nodes simultaneously
14+
- `host_network` (optional) - Run the must-gather pods in the host network of the node. This is only relevant if a specific gather image needs to capture host-level data
15+
- `gather_command` (optional) - Custom gather command to run a specialized script (default: `/usr/bin/gather`)
16+
- `all_component_images` (optional) - When enabled, collects and runs multiple must gathers for all operators and components on the cluster that have an annotated must-gather image available
17+
- `images` (optional) - List of images to use for gathering custom information about specific operators or cluster components. If not specified, OpenShift's default must-gather image will be used
18+
- `source_dir` (optional) - Directory where the pod will copy gathered data from (default: `/must-gather`)
19+
- `timeout` (optional) - Timeout of the gather process (e.g., `30s`, `6m20s`, `2h10m30s`)
20+
- `namespace` (optional) - Existing privileged namespace where must-gather pods should run. If not provided, a temporary namespace will be created
21+
- `keep_resources` (optional) - Retain all temporary resources when the must-gather completes
22+
- `since` (optional) - Collect logs newer than a relative duration like `5s`, `2m5s`, or `3h6m10s`
23+
24+
**Example:**
25+
```
26+
# Basic must-gather collection
27+
{}
28+
29+
# Collect with custom timeout and since
30+
{
31+
"timeout": "30m",
32+
"since": "1h"
33+
}
34+
35+
# Collect from all component images
36+
{
37+
"all_component_images": true
38+
}
39+
40+
# Collect from specific operator image
41+
{
42+
"images": ["registry.redhat.io/openshift-logging/cluster-logging-rhel9-operator@sha256:..."]
43+
}
44+
```
45+
46+
## Enable the OpenShift Toolset
47+
48+
### Option 1: Command Line
49+
50+
```bash
51+
kubernetes-mcp-server --toolsets core,config,helm,openshift
52+
```
53+
54+
### Option 2: Configuration File
55+
56+
```toml
57+
toolsets = ["core", "config", "helm", "openshift"]
58+
```
59+
60+
### Option 3: MCP Client Configuration
61+
62+
```json
63+
{
64+
"mcpServers": {
65+
"kubernetes": {
66+
"command": "npx",
67+
"args": ["-y", "kubernetes-mcp-server@latest", "--toolsets", "core,config,helm,openshift"]
68+
}
69+
}
70+
}
71+
```
72+
73+
## Prerequisites
74+
75+
The OpenShift toolset requires:
76+
77+
1. **OpenShift cluster** - These tools are designed for OpenShift and automatically detect the cluster type
78+
2. **Proper RBAC** - The user/service account must have permissions to:
79+
- Create namespaces
80+
- Create service accounts
81+
- Create cluster role bindings
82+
- Create pods with privileged access
83+
- List ClusterOperators and ClusterServiceVersions (for `all_component_images`)
84+
85+
## How It Works
86+
87+
### Must-Gather Plan Generation
88+
89+
The `plan_mustgather` tool generates YAML manifests for collecting diagnostic data from an OpenShift cluster:
90+
91+
1. **Namespace** - A temporary namespace (e.g., `openshift-must-gather-xyz`) is created unless an existing namespace is specified
92+
2. **ServiceAccount** - A service account with cluster-admin permissions is created for the must-gather pod
93+
3. **ClusterRoleBinding** - Binds the service account to the cluster-admin role
94+
4. **Pod** - Runs the must-gather container(s) with the specified configuration
95+
96+
### Component Image Discovery
97+
98+
When `all_component_images` is enabled, the tool discovers must-gather images from:
99+
- **ClusterOperators** - Looks for the `operators.openshift.io/must-gather-image` annotation
100+
- **ClusterServiceVersions** - Checks OLM-installed operators for the same annotation
101+
102+
### Multiple Images Support
103+
104+
Up to 8 gather images can be run concurrently. Each image runs in a separate container within the same pod, sharing the output volume.
105+
106+
## Common Use Cases
107+
108+
### Basic Cluster Diagnostics
109+
110+
Collect general cluster diagnostics:
111+
```json
112+
{}
113+
```
114+
115+
### Audit Logs Collection
116+
117+
Collect audit logs with a custom gather command:
118+
```json
119+
{
120+
"gather_command": "/usr/bin/gather_audit_logs",
121+
"timeout": "2h"
122+
}
123+
```
124+
125+
### Recent Logs Only
126+
127+
Collect logs from the last 30 minutes:
128+
```json
129+
{
130+
"since": "30m"
131+
}
132+
```
133+
134+
### Specific Operator Diagnostics
135+
136+
Collect diagnostics for a specific operator:
137+
```json
138+
{
139+
"images": ["registry.redhat.io/openshift-logging/cluster-logging-rhel9-operator@sha256:..."]
140+
}
141+
```
142+
143+
### Host Network Access
144+
145+
For tools that need host-level network access:
146+
```json
147+
{
148+
"host_network": true
149+
}
150+
```
151+
152+
### All Component Diagnostics
153+
154+
Collect diagnostics from all operators with must-gather images:
155+
```json
156+
{
157+
"all_component_images": true,
158+
"timeout": "1h"
159+
}
160+
```
161+
162+
## Troubleshooting
163+
164+
### Permission Errors
165+
166+
If you see permission warnings, ensure your user has the required RBAC permissions:
167+
```bash
168+
oc auth can-i create namespaces
169+
oc auth can-i create clusterrolebindings
170+
oc auth can-i create pods --as=system:serviceaccount:openshift-must-gather-xxx:must-gather-collector
171+
```
172+
173+
### Pod Not Starting
174+
175+
Check if the node has enough resources and can pull the must-gather image:
176+
```bash
177+
oc get pods -n openshift-must-gather-xxx
178+
oc describe pod <pod-name> -n openshift-must-gather-xxx
179+
```
180+
181+
### Timeout Issues
182+
183+
For large clusters or audit log collection, increase the timeout:
184+
```json
185+
{
186+
"timeout": "2h"
187+
}
188+
```
189+
190+
### Image Pull Errors
191+
192+
Ensure the must-gather image is accessible:
193+
```bash
194+
oc get secret -n openshift-config pull-secret
195+
```
196+
197+
## Security Considerations
198+
199+
### Privileged Access
200+
201+
The must-gather pods run with:
202+
- `cluster-admin` ClusterRoleBinding
203+
- `system-cluster-critical` priority class
204+
- Tolerations for all taints
205+
- Optional host network access
206+
207+
### Temporary Resources
208+
209+
By default, all created resources (namespace, service account, cluster role binding) should be cleaned up after the must-gather collection is complete. Use `keep_resources: true` to retain them for debugging.
210+
211+
### Image Sources
212+
213+
The tool uses these default images:
214+
- **Must-gather**: `registry.redhat.io/openshift4/ose-must-gather:latest`
215+
- **Wait container**: `registry.redhat.io/ubi9/ubi-minimal`
216+
217+
Custom images should be from trusted sources.

0 commit comments

Comments
 (0)