/ 
MCP-K8s-0.001
/ MCP::K8s::Permissions

NAME

MCP::K8s::Permissions - RBAC discovery and permission checking for Kubernetes

VERSION

version 0.001

SYNOPSIS

use MCP::K8s::Permissions;

my $perms = MCP::K8s::Permissions->new(
  api        => $kubernetes_rest_api,
  namespaces => ['default', 'production'],
);

# Discover what the current service account can do
$perms->discover;

# Check specific permissions
if ($perms->can_do('list', 'pods', 'default')) {
  say "Can list pods in default namespace";
}

# Get all resources allowed for a verb
my @listable = $perms->allowed_resources('list', 'default');

# Check pod log access
if ($perms->can_read_logs('production')) {
  say "Can read pod logs in production";
}

# Human-readable summary (Markdown formatted)
say $perms->summary;

DESCRIPTION

MCP::K8s::Permissions encapsulates Kubernetes RBAC discovery using the SelfSubjectRulesReview API. On "discover", it submits a review request for each configured namespace (plus cluster scope), parses the returned ResourceRule entries, and builds an internal permission map.

This map powers permission checks throughout MCP::K8s — every tool verifies access before making API calls, providing clear error messages when a service account lacks the required permissions.

Wildcard handling: The * wildcard in verbs or resources is expanded at discovery time. A rule with verbs: ["*"] grants all standard Kubernetes verbs (get, list, watch, create, update, patch, delete). A rule with resources: ["*"] grants access to all resource types.

api

Required. A Kubernetes::REST instance used to submit SelfSubjectRulesReview requests. Stored as a weak reference to avoid circular references with the parent MCP::K8s object.

namespaces

Required. ArrayRef of namespace names to discover permissions for. Typically comes from $ENV{MCP_K8S_NAMESPACES} or auto-discovery in MCP::K8s.

discover

$perms->discover;

Submit SelfSubjectRulesReview requests for each namespace in "namespaces" plus an empty-namespace request for cluster-scoped resources. Populates the internal permission map.

Returns $self for chaining.

Failures for individual namespaces are warned and skipped — a single inaccessible namespace won't prevent discovery of the others.

can_do

my $allowed = $perms->can_do('list', 'pods', 'default');
my $allowed = $perms->can_do('create', 'deployments', 'production');

Check whether the current service account is allowed to perform $verb on $resource_plural in $namespace. Returns a boolean.

$namespace defaults to '' (cluster scope) if not provided.

Handles wildcards: if the account has * on verbs or resources for the given namespace, the check succeeds.

allowed_resources

my @resources = $perms->allowed_resources('list', 'default');
# => ('configmaps', 'deployments', 'pods', 'services')

Return a sorted list of resource plurals that are allowed for $verb in $namespace. If the account has wildcard resource access, '*' is prepended to the list.

Subresources (e.g. pods/log) are excluded from the returned list.

allowed_namespaces

my @ns = $perms->allowed_namespaces;

Return a sorted list of namespaces that have any discovered permissions. Excludes the cluster scope (empty string).

can_read_logs

if ($perms->can_read_logs('default')) { ... }

Check whether pod log access is available in $namespace. This checks for the pods/log subresource get permission, wildcard resource access, or general pods get access (which in practice implies log access on most clusters).

summary

my $text = $perms->summary;

Generate a human-readable Markdown-formatted summary of all discovered permissions. Organized by namespace, with verbs grouped and their allowed resources listed.

This is the output returned by the k8s_permissions MCP tool — designed to give an LLM a quick overview of what it can and cannot do.

Example output:

# Kubernetes RBAC Permissions

## Namespace: default

- **get**: deployments, pods, services
- **list**: deployments, pods, services
- **create**: configmaps
- **delete**: configmaps

## Namespace: admin

Full access (all resources, all verbs)

SEE ALSO

MCP::K8s — Main module that uses this for tool registration

IO::K8s::Api::Authorization::V1::SelfSubjectRulesReview — The K8s API object used for discovery

IO::K8s::Api::Authorization::V1::ResourceRule — Individual permission rules

https://kubernetes.io/docs/reference/access-authn-authz/rbac/ — Kubernetes RBAC documentation

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-mcp-k8s/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.