# How kubectl_rollout Manages Deployment Rollouts in the MCP Kubernetes Server

> Learn how kubectl_rollout in mcp-server-kubernetes simplifies deployment rollouts with a type-safe interface, execution timeouts, and structured errors.

- Repository: [Suyog Sonwalkar/mcp-server-kubernetes](https://github.com/flux159/mcp-server-kubernetes)
- Tags: how-to-guide
- Published: 2026-03-02

---

**The `kubectl_rollout` tool in `flux159/mcp-server-kubernetes` wraps native `kubectl rollout` subcommands into a type-safe MCP interface, handling command construction, execution timeouts, and structured error responses.**

The `kubectl_rollout` implementation provides Model Context Protocol (MCP) clients with declarative control over Kubernetes deployment lifecycle operations. Located in the `flux159/mcp-server-kubernetes` repository, this tool abstracts complex CLI syntax into validated JSON-RPC calls, supporting operations like status monitoring, restart, pause, resume, and revision history.

## Architecture of the kubectl_rollout Tool

### Schema Definition and Validation

The tool advertises its capabilities through a Zod-compatible JSON schema defined in [`src/tools/kubectl-rollout.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-rollout.ts). This schema enumerates the supported `subCommand` values: `history`, `pause`, `restart`, `resume`, `status`, and `undo`. It also defines valid `resourceType` options and optional parameters including `revision`, `timeout`, `watch`, and `context`.

The strict typing ensures that MCP clients receive immediate validation feedback before any kubectl execution occurs, preventing malformed commands from reaching the cluster.

### Command Construction Logic

The core `kubectlRollout` function receives a `KubernetesManager` instance and validated input arguments. It constructs the kubectl command array incrementally:

1. **Base arguments**: `["rollout", subCommand, "<resourceType>/<name>", "-n", namespace]`
2. **Conditional flags**:
   - `--to-revision` for `undo` operations
   - `--revision` for `history` queries
   - `--timeout` when specified
   - `--context` for multi-cluster environments

This assembly pattern in [`src/tools/kubectl-rollout.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-rollout.ts) (lines 78-104) ensures that only relevant flags are appended, keeping the command clean and avoiding kubectl errors from empty string arguments.

## Implementation Details in kubectl-rollout.ts

### Handling Watch Mode and Timeouts

The implementation includes specialized logic for the `status` subcommand when combined with `watch: true`. In [`src/tools/kubectl-rollout.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-rollout.ts) (lines 110-118), the tool appends the `--watch` flag and enforces a hard 15-second timeout using `execFileSync` options. This prevents the MCP server from hanging indefinitely while still allowing real-time status observation for short intervals.

For all other operations, the tool respects user-provided timeouts or uses default `maxBuffer` settings from [`src/config/max-buffer.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/config/max-buffer.ts) to handle large output streams without memory issues.

### Error Handling Strategy

The tool implements a two-tier error handling approach. First, it catches `execFileSync` exceptions and wraps them in `McpError` instances with `ErrorCode.InternalError`, preserving the original stderr message (lines 147-151). Second, a broader catch block ensures that any unexpected non-McpError exceptions are also converted to proper MCP error responses (lines 153-161).

This guarantees that clients always receive structured error objects rather than raw stack traces, maintaining protocol compliance even when kubectl binaries are missing or cluster credentials are invalid.

## Practical Usage Examples

### Checking Rollout Status

To verify whether a deployment has completed successfully:

```typescript
const response = await client.request(
  {
    method: "tools/call",
    params: {
      name: "kubectl_rollout",
      arguments: {
        subCommand: "status",
        resourceType: "deployment",
        name: "my-app",
        namespace: "production",
        watch: false,
      },
    },
  },
  z.any()
);

```

This corresponds to the test implementation in [`tests/kubectl-rollout.test.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/tests/kubectl-rollout.test.ts) (lines 97-107).

### Restarting a Deployment

To trigger a rolling restart of all pods:

```typescript
await client.request(
  {
    method: "tools/call",
    params: {
      name: "kubectl_rollout",
      arguments: {
        subCommand: "restart",
        resourceType: "deployment",
        name: "my-app",
        namespace: "staging",
      },
    },
  },
  z.any()
);

```

As verified in [`tests/kubectl-rollout.test.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/tests/kubectl-rollout.test.ts) (lines 178-196), this executes `kubectl rollout restart deployment/my-app -n staging`.

### Pausing and Resuming Rollouts

To temporarily halt and later resume a deployment:

```typescript
// Pause rollout
await client.request({
  method: "tools/call",
  params: {
    name: "kubectl_rollout",
    arguments: {
      subCommand: "pause",
      resourceType: "deployment",
      name: "my-app",
      namespace: "dev",
    },
  },
}, z.any());

// Resume rollout
await client.request({
  method: "tools/call",
  params: {
    name: "kubectl_rollout",
    arguments: {
      subCommand: "resume",
      resourceType: "deployment",
      name: "my-app",
      namespace: "dev",
    },
  },
}, z.any());

```

These operations are tested in [`tests/kubectl-rollout.test.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/tests/kubectl-rollout.test.ts) (lines 264-324).

### Retrieving Rollout History

To inspect previous revisions:

```typescript
await client.request(
  {
    method: "tools/call",
    params: {
      name: "kubectl_rollout",
      arguments: {
        subCommand: "history",
        resourceType: "deployment",
        name: "my-app",
        namespace: "dev",
        toRevision: 2,
      },
    },
  },
  z.any()
);

```

As shown in [`tests/kubectl-rollout.test.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/tests/kubectl-rollout.test.ts) (lines 447-466), this maps to `kubectl rollout history deployment/my-app --to-revision=2 -n dev`.

## Summary

- **`kubectl_rollout`** wraps native `kubectl rollout` subcommands into a structured MCP tool interface defined in [`src/tools/kubectl-rollout.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-rollout.ts).
- The implementation supports six primary operations: **status**, **restart**, **pause**, **resume**, **history**, and **undo**, with conditional flags for revision targeting and timeouts.
- **Watch mode** for status checks includes a mandatory 15-second timeout to prevent server blocking, while other commands respect configurable buffer limits from [`src/config/max-buffer.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/config/max-buffer.ts).
- All errors are normalized to **McpError** instances with proper error codes, ensuring clients receive predictable JSON-RPC error responses rather than raw shell output.
- Integration tests in [`tests/kubectl-rollout.test.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/tests/kubectl-rollout.test.ts) verify end-to-end functionality for each subcommand against live cluster resources.

## Frequently Asked Questions

### What Kubernetes resource types does kubectl_rollout support?

The tool supports **deployments**, **daemonsets**, and **statefulsets** as valid `resourceType` values. These are the only workload resources that implement the Kubernetes rollout API. The schema validation in [`src/tools/kubectl-rollout.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-rollout.ts) restricts inputs to these types, ensuring that commands like `kubectl rollout status` only target resources that maintain revision history and support progressive deployment strategies.

### How does kubectl_rollout handle long-running watch operations?

When the `status` subcommand is invoked with `watch: true`, the tool appends the `--watch` flag to the kubectl command and enforces a **15-second execution timeout** via `execFileSync` options. This prevents the MCP server from hanging indefinitely while still allowing real-time observation of rollout progress. For non-watch operations, the tool relies on the default buffer size from [`src/config/max-buffer.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/config/max-buffer.ts) to handle large outputs without memory constraints.

### Can kubectl_rollout target specific cluster contexts?

Yes, the tool accepts an optional `context` parameter that maps to the `--context` kubectl flag. When provided, the implementation in [`src/tools/kubectl-rollout.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-rollout.ts) (lines 101-104) appends `--context <value>` to the argument array, allowing MCP clients to execute rollout commands against specific clusters defined in the kubeconfig. This is essential for multi-cluster environments where deployments with identical names exist across different contexts.

### What happens when a kubectl_rollout command fails?

All execution errors are caught and normalized to **McpError** instances with `ErrorCode.InternalError`. The error handling logic in [`src/tools/kubectl-rollout.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-rollout.ts) (lines 147-161) preserves the original stderr message while wrapping it in a structured JSON-RPC error response. This ensures that MCP clients receive predictable error objects rather than raw stack traces or shell output, maintaining protocol compliance even when kubectl binaries are missing, cluster credentials are invalid, or network timeouts occur.