view release on metacpan or  search on metacpan

lib/MCP/K8s.pm  view on Meta::CPAN

Kubeconfig context to use. Default: the kubeconfig's C<current-context>.

=item C<MCP_K8S_TOKEN>

Bearer token for direct authentication. Bypasses kubeconfig entirely.
Useful for CI/CD pipelines or when you have a service account token.

=item C<MCP_K8S_SERVER>

Kubernetes API server URL. Used with C<MCP_K8S_TOKEN> or in-cluster auth.
Default when in-cluster: C<https://kubernetes.default.svc.cluster.local>.

=item C<MCP_K8S_NAMESPACES>

Comma-separated list of namespaces to operate on.
Default: auto-discovered from the cluster (lists all namespaces the
service account can see). Falls back to C<default> if discovery fails.

=back

=head1 AUTHENTICATION

MCP::K8s supports three authentication methods, tried in order:

=over 4

=item 1. B<Direct token> — Set C<MCP_K8S_TOKEN> (and optionally C<MCP_K8S_SERVER>)

=item 2. B<In-cluster> — Auto-detected when running as a Kubernetes pod (reads mounted service account token from C</var/run/secrets/kubernetes.io/serviceaccount/token>)

=item 3. B<Kubeconfig> — Reads C<~/.kube/config> (or C<$KUBECONFIG>), optionally filtered by C<MCP_K8S_CONTEXT>

=back

For in-cluster and direct token auth, the CA certificate at
C</var/run/secrets/kubernetes.io/serviceaccount/ca.crt> is automatically
used if present.

=head1 RBAC SETUP

Use a dedicated ServiceAccount with minimal permissions for AI access.
Example RBAC manifests are included in the C<examples/> directory:

=over 4

=item C<examples/readonly-serviceaccount.yaml> — Read-only access (recommended starting point)

=item C<examples/deployer-serviceaccount.yaml> — Read + deploy/restart capabilities

=item C<examples/full-ops-serviceaccount.yaml> — Full access except secrets

=back

RBAC is the single source of truth — if the service account shouldn't have
access, don't grant it via RBAC. MCP::K8s does B<not> implement
application-layer permission filtering.

=head1 CLAUDE DESKTOP INTEGRATION

Add this to your Claude Desktop MCP configuration
(C<~/.config/claude/claude_desktop_config.json>):

  {
    "mcpServers": {
      "kubernetes": {
        "command": "mcp-k8s",
        "env": {
          "MCP_K8S_CONTEXT": "my-cluster",
          "MCP_K8S_NAMESPACES": "default,production"
        }
      }
    }
  }

=head1 CLAUDE CODE INTEGRATION

Add to your project's C<.mcp.json> or global MCP settings:

  {
    "mcpServers": {
      "kubernetes": {
        "command": "mcp-k8s",
        "env": {
          "MCP_K8S_CONTEXT": "dev-cluster"
        }
      }
    }
  }

=head1 LANGERTHA RAIDER INTEGRATION

Use L<Langertha::Raider> to build an autonomous AI agent that can
interact with your Kubernetes cluster using MCP::K8s as its tool source:

  use IO::Async::Loop;
  use Future::AsyncAwait;
  use Net::Async::MCP;
  use Langertha::Engine::Anthropic;
  use Langertha::Raider;
  use MCP::K8s;

  my $k8s = MCP::K8s->new(
    namespaces => ['default', 'production'],
  );

  my $loop = IO::Async::Loop->new;
  my $mcp = Net::Async::MCP->new(server => $k8s->server);
  $loop->add($mcp);

  async sub main {
    await $mcp->initialize;

    my $engine = Langertha::Engine::Anthropic->new(
      api_key     => $ENV{ANTHROPIC_API_KEY},
      model       => 'claude-sonnet-4-6',
      mcp_servers => [$mcp],
    );

    my $raider = Langertha::Raider->new(
      engine  => $engine,
      mission => 'You are a Kubernetes operations assistant. '