How kubectl_rollout Manages Deployment Rollouts in the MCP Kubernetes Server

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. 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 (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 (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 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:

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 (lines 97-107).

Restarting a Deployment

To trigger a rolling restart of all pods:

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 (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:

// 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 (lines 264-324).

Retrieving Rollout History

To inspect previous revisions:

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 (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.
• 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.
• 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 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 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 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 (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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}