{ "schema": "aaes/capability-pack/1", "provider": "kubernetes", "version": "1.0.0", "description": "List Kubernetes namespaces, deployments, and pods; create and scale deployments, delete deployments, and delete entire namespaces. Creation runs caller-chosen code, and namespace deletion removes the objects it contains.", "notes": "The endpoint host 'k8s-apiserver.invalid' is a reserved non-production placeholder (an RFC 2606 reserved TLD): substitute the customer's cluster API server endpoint (host and, where non-standard, host:port) before enabling, in every endpoint, in the resource locator and in every egress allowlist entry. The allowlist matches exactly, so endpoints and allowlist must be substituted together, and substitution is a required deployment step.\n\nNAMESPACE and NAME in the endpoint paths are placeholders the deployment binds to concrete objects before enabling; this pack registers namespaced collection reads only — the cluster-wide list forms (GET /apis/apps/v1/deployments, GET /api/v1/pods across all namespaces) are not registered.\n\nThe Kubernetes API is served over HTTPS with the cluster's own certificate authority, so the executor must trust the cluster CA; the egress allowlist governs the destination only and is not a TLS-trust statement.\n\nApproval classification: deployment creation registers as create and deploy at the minimum R3 tier, judged by effect — the body is an unrestricted Deployment spec (according to the reviewed Deployment API reference), which selects container images, replica counts, service accounts, volume mounts and security contexts, so creating a Deployment is running caller-chosen code on the cluster, and deploy is one of the designated actions requiring human approval; an installer's intention to pass only benign specs is not a restriction.\n\nDeployment deletion and namespace deletion register as delete at the minimum R3 tier: deleting a Deployment deletes its ReplicaSets and Pods through the cascade, and deleting a namespace deletes every object in the namespace. Scaling registers as update and deploy at the minimum R3 tier: the scale subresource replaces the running replica count of a live workload — a deploy-equivalent reconfiguration of live infrastructure (scaling to zero takes the workload offline) — and the count's practical reversibility is not grounds for avoiding the deploy verb.\n\nDocumented exclusions — this pack does not register: reading Secrets (GET /api/v1/namespaces/{ns}/secrets — the response is the cluster's stored credentials, and according to the reviewed authentication reference anyone who can read those Secrets can authenticate as the corresponding service account), pods/exec, pods/attach and pods/portforward (arbitrary command execution and network tunneling into containers — a different registration requiring its own review), pods/log, the deletecollection forms of every resource (bulk deletion by label selector), create/update/delete of RBAC objects (Roles, ClusterRoles and their bindings — privilege grant), node operations (cordon, drain, taints), PersistentVolumes and PersistentVolumeClaims, ServiceAccount and token creation, and every other Kubernetes API.", "credential": { "secret_ref_id": "secret-ref-kubernetes-sa-token", "custody": "customer_vault", "inject": "header", "inject_name": "Authorization", "note": "Store the complete Authorization header for a dedicated Kubernetes ServiceAccount in the client's secret manager: 'Bearer ', containing the signed JWT. A cluster administrator creates the account and issues tokens externally with kubectl create token (the TokenRequest API), optionally specifying audience and lifetime. Service accounts authenticate as system:serviceaccount:(NAMESPACE):(SERVICEACCOUNT), and these tokens can authenticate from outside the cluster.\n\nPrefer short-lived bound TokenRequest tokens. They expire according to exp and fail closed afterward. Legacy Secret-based tokens do not expire; with service-account lookup enabled, deleting their Secret revokes them.\n\nStopping new TokenRequest issuance does not invalidate issued, unexpired tokens. A token using boundObjectRef remains valid only while its bound Pod or Secret exists; deleting that object invalidates it. A token bound only to the service account cannot be individually revoked before expiry: revocation requires deleting the account or rotating cluster signing keys.\n\nAn external custody process reissues tokens and updates the reference before expiry. The executor injects the stored header unchanged and performs no token lifecycle.\n\nGrant permissions at the required scope. Namespaces are cluster-scoped, so listing or deleting them requires a ClusterRole/ClusterRoleBinding. Deployments, Pods, and the scale subresource are namespaced; use Role/RoleBinding only in the bound namespaces.\n\nGrant list, rather than only get, for registered namespace, deployment, and Pod collection reads. Grant create on deployments for creation, update specifically on deployments/scale for scaling, and delete on deployments or namespaces only where those delete capabilities are enabled. General deployment update is unnecessary for scaling and must not be granted; never grant cluster-admin.\n\nKeep the value only in executor memory for a call, never in logs, traces, diagnostics, or crash dumps. Do not enable the pack if the deployment cannot meet those requirements." }, "capabilities": [ { "capability_id": "kubernetes.namespaces.read", "version": "1.0.0", "kind": "tool", "risk_tier": "R0", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN", "data_class": "internal", "egress_allowlist": [ "k8s-apiserver.invalid" ], "endpoint": "https://k8s-apiserver.invalid/api/v1/namespaces", "method": "GET", "connector": "http", "custody": "customer_vault", "secret_ref_id": "secret-ref-kubernetes-sa-token", "inject": "header", "inject_name": "Authorization", "actions": [ "read" ], "resource_id": "kubernetes-cluster", "description": "List the cluster's namespaces: names, phases and labels, which reveal internal tenancy topology. Per the retrieved Namespace API reference the endpoint supports label and field selectors and pagination; the registered path covers the collection read only — single-namespace reads (GET /api/v1/namespaces/{name}) are not registered by this pack.\n\nThe host is a reserved placeholder: substitute the cluster's API server endpoint before enabling.", "requires_review": true }, { "capability_id": "kubernetes.deployments.read", "version": "1.0.0", "kind": "tool", "risk_tier": "R0", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN", "data_class": "internal", "egress_allowlist": [ "k8s-apiserver.invalid" ], "endpoint": "https://k8s-apiserver.invalid/apis/apps/v1/namespaces/NAMESPACE/deployments", "method": "GET", "connector": "http", "custody": "customer_vault", "secret_ref_id": "secret-ref-kubernetes-sa-token", "inject": "header", "inject_name": "Authorization", "actions": [ "read" ], "resource_id": "kubernetes-cluster", "description": "List the Deployments in one namespace: names, replica counts, rollout strategy and the full pod template, which reveals images, volume wiring — and, according to the reviewed Pod API reference embedded in the template, literal environment-variable values, command arguments and annotations. Secret references appear by name only and are not dereferenced, but plaintext credentials written as literal env values in the template would be exposed by this read.\n\nPer the retrieved Deployment API reference the endpoint supports label and field selectors and pagination; the registered path covers the namespaced collection read only — the cluster-wide list (GET /apis/apps/v1/deployments) and single-object reads are not registered. NAMESPACE is a placeholder the deployment binds before enabling.", "requires_review": true }, { "capability_id": "kubernetes.pods.read", "version": "1.0.0", "kind": "tool", "risk_tier": "R0", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN", "data_class": "internal", "egress_allowlist": [ "k8s-apiserver.invalid" ], "endpoint": "https://k8s-apiserver.invalid/api/v1/namespaces/NAMESPACE/pods", "method": "GET", "connector": "http", "custody": "customer_vault", "secret_ref_id": "secret-ref-kubernetes-sa-token", "inject": "header", "inject_name": "Authorization", "actions": [ "read" ], "resource_id": "kubernetes-cluster", "description": "List the Pods in one namespace: names, phases, container specs and status.\n\nData exposure: according to the reviewed Pod API reference the returned specifications include literal environment-variable values (env value fields), command and argument arrays, annotations and node placement, alongside secret and configmap references — secret values are not dereferenced by this read (secretKeyRef entries appear by name only), but a workload that carries credentials as literal env values or command arguments exposes them in this response, so the absence of dereferencing is no guarantee that no plaintext credentials are returned.\n\nThe registered path covers the namespaced collection read only — the cluster-wide list (GET /api/v1/pods), single-pod reads and pods/log are not registered; reading Secrets is a documented exclusion of this pack. NAMESPACE is a placeholder the deployment binds before enabling.", "requires_review": true }, { "capability_id": "kubernetes.deployment.create", "version": "1.0.0", "kind": "tool", "risk_tier": "R3", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN", "data_class": "internal", "egress_allowlist": [ "k8s-apiserver.invalid" ], "endpoint": "https://k8s-apiserver.invalid/apis/apps/v1/namespaces/NAMESPACE/deployments", "method": "POST", "connector": "http", "custody": "customer_vault", "secret_ref_id": "secret-ref-kubernetes-sa-token", "inject": "header", "inject_name": "Authorization", "actions": [ "create", "deploy" ], "resource_id": "kubernetes-cluster", "description": "Create one Deployment in one namespace.\n\nJudged by effect: the body is an unrestricted Deployment spec (according to the reviewed Deployment API reference) that selects container images, replica counts, the pod's service account, volume mounts including host paths, and security contexts — creating a Deployment is running caller-chosen code on the cluster — so the capability declares create and deploy at the minimum R3 tier, and deploy is one of the designated actions requiring human approval; an installer's intention to submit only benign specs is not a restriction.\n\nThe dryRun query parameter exists in the API but does not change what this registration permits. NAMESPACE is a placeholder the deployment binds before enabling.", "requires_review": true }, { "capability_id": "kubernetes.deployment.scale", "version": "1.0.0", "kind": "tool", "risk_tier": "R3", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN", "data_class": "internal", "egress_allowlist": [ "k8s-apiserver.invalid" ], "endpoint": "https://k8s-apiserver.invalid/apis/apps/v1/namespaces/NAMESPACE/deployments/NAME/scale", "method": "PUT", "connector": "http", "custody": "customer_vault", "secret_ref_id": "secret-ref-kubernetes-sa-token", "inject": "header", "inject_name": "Authorization", "actions": [ "update", "deploy" ], "resource_id": "kubernetes-cluster", "description": "Replace one Deployment's replica count through its scale subresource (a Scale object body, not a full Deployment spec). Registered as update and deploy at the minimum R3 tier: scaling a live workload changes running production capacity immediately — scaling to zero takes the workload offline and a large scale-up consumes cluster capacity — a deploy-equivalent reconfiguration of live infrastructure, and deploy is one of the designated actions requiring human approval; the previous replica count being re-settable does not remove the live-traffic effect.\n\nThe generic PATCH on the Deployment object is deliberately not registered (its unrestricted body would admit the same code-selection effects as creation); this registration covers the scale subresource only. NAMESPACE and NAME are placeholders the deployment binds before enabling.", "requires_review": true }, { "capability_id": "kubernetes.deployment.delete", "version": "1.0.0", "kind": "tool", "risk_tier": "R3", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN", "data_class": "internal", "egress_allowlist": [ "k8s-apiserver.invalid" ], "endpoint": "https://k8s-apiserver.invalid/apis/apps/v1/namespaces/NAMESPACE/deployments/NAME", "method": "DELETE", "connector": "http", "custody": "customer_vault", "secret_ref_id": "secret-ref-kubernetes-sa-token", "inject": "header", "inject_name": "Authorization", "actions": [ "delete" ], "resource_id": "kubernetes-cluster", "description": "Delete one Deployment; according to the reviewed Deployment API reference the call accepts a DeleteOptions body, a grace period and a propagation policy, and the default cascade deletes the Deployment's ReplicaSets and Pods with it — the running workload stops. Delete is one of the designated actions requiring human approval at the minimum R3 tier; re-applying the manifest later is a new creation, not an undo, and any pod state that was not persisted elsewhere is gone.\n\nThe deletecollection form (DELETE on the collection, bulk deletion by label selector) is deliberately not registered. NAMESPACE and NAME are placeholders the deployment binds before enabling.", "requires_review": true }, { "capability_id": "kubernetes.namespace.delete", "version": "1.0.0", "kind": "tool", "risk_tier": "R3", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN", "data_class": "internal", "egress_allowlist": [ "k8s-apiserver.invalid" ], "endpoint": "https://k8s-apiserver.invalid/api/v1/namespaces/NAME", "method": "DELETE", "connector": "http", "custody": "customer_vault", "secret_ref_id": "secret-ref-kubernetes-sa-token", "inject": "header", "inject_name": "Authorization", "actions": [ "delete" ], "resource_id": "kubernetes-cluster", "description": "Delete one namespace and, through the namespace controller, every object in it — workloads, services, configmaps, secrets and volume claims — with the namespace passing through the Terminating phase documented in the retrieved Namespace API reference while finalizers complete. This is among the most extensive operations a cluster offers; delete is one of the designated actions requiring human approval at the minimum R3 tier.\n\nOn supported AAES-mediated execution paths, irreversible actions require approval by an authorized person; this does not prevent calls through bypass or observation-only paths. The /finalize subresource (which can force-remove finalizers from a stuck namespace and strand its resources) is deliberately not registered. NAME is a placeholder the deployment binds before enabling.", "requires_review": true } ], "resources": [ { "resource_id": "kubernetes-cluster", "kind": "api", "locator": "https://k8s-apiserver.invalid", "data_class": "internal", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN" } ], "review": { "state": "library", "date": "2026-09-22", "sources": [ "https://kubernetes.io/docs/reference/kubernetes-api/ (retrieved 2026-09-21)", "https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/deployment-v1/ (retrieved 2026-09-21)", "https://kubernetes.io/docs/reference/kubernetes-api/cluster-resources/namespace-v1/ (retrieved 2026-09-21)", "https://kubernetes.io/docs/reference/access-authn-authz/authentication/ (retrieved 2026-09-21)", "https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/ (retrieved 2026-09-21)", "https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-request-v1/ (retrieved 2026-09-21)" ], "reviewer_id": "aaes-eng" } }