MAQPNADocs

BudgetPolicy

BudgetPolicy (maqpna.com/v1alpha1): every field, type, default and validation rule, generated from the CRD schema.

BudgetPolicy sets namespace and user budgets enforced by the gateway on MCP tool calls and model traffic. When several BudgetPolicies set a limit for the same key, the smallest limit wins.

At a glance#

Property Value
API version maqpna.com/v1alpha1
Kind BudgetPolicy
Scope Cluster
Plural budgetpolicies
Short names bp
Categories maqpna
Status subresource yes 
kubectl get budgetpolicies
kubectl get bp <name> -o yaml
kubectl explain budgetpolicies.spec

Columns in kubectl get#

Column Type From
OnExceed string .spec.onExceed
Age date .metadata.creationTimestamp

Example#

From config/samples/budgetpolicy-default.yaml:

# Namespace and user budgets (F-14), enforced by the gateway on MCP tool calls
# and /llm model traffic. Per-agent limits live on the Agent:
#   spec.budget: {perSessionUSD, perDayUSD, perMonthUSD}
#   spec.maxConcurrentSessions
#   spec.model: {tokensPerMinute, maxTokensPerRequest}
apiVersion: maqpna.com/v1alpha1
kind: BudgetPolicy
metadata:
  name: default
spec:
  namespaces:
    team-a: {perDayUSD: "200", perMonthUSD: "3000", maxConcurrentSessions: 20}
    "*": {perDayUSD: "50"}
  users:
    "*": {perDayUSD: "25"}
  onExceed: deny            # deny | require_approval | alert
  alertAtPercent: [80, 100]

Spec fields#

BudgetPolicySpec sets namespace and user budgets.

Field Type Required Description
alertAtPercent []integer (int32) alertAtPercent emits a budget.threshold alert (log + metric) the first time spend crosses each percentage of a limit within a period. Max items: 10.
namespaces map[string]object namespaces maps a namespace name (or "*" for every namespace without its own entry) to its limits.
namespaces.<key>.currency string currency is the ISO 4217 code of the perUSD amounts (default USD; the USD field names are legacy, see docs/api-conventions.md). It must equal the gateway's budgetCurrency: amounts are never converted and the gateway rejects budgets in another currency. Pattern: ^[A-Z]{3}$.
namespaces.<key>.maxConcurrentSessions integer (int32) maxConcurrentSessions caps the non-terminal, admitted sessions of a namespace (namespaces only; ignored for users). Extra sessions stay Pending with condition QuotaExceeded. Minimum: 0.
namespaces.<key>.perDayUSD int or string perDayUSD caps the scope's spend per day. Pattern: ^(\+\|-)?(([0-9]+(\.[0-9]*)?)\|(\.[0-9]+))(([KMGTPE]i)\|[numkMGTPE]\|([eE](\+\|-)?(([0-9]+(\.[0-9]*)?)\|(\.[0-9]+))))?$.
namespaces.<key>.perMonthUSD int or string perMonthUSD caps the scope's spend per month. Pattern: ^(\+\|-)?(([0-9]+(\.[0-9]*)?)\|(\.[0-9]+))(([KMGTPE]i)\|[numkMGTPE]\|([eE](\+\|-)?(([0-9]+(\.[0-9]*)?)\|(\.[0-9]+))))?$.
namespaces.<key>.perSessionUSD int or string perSessionUSD caps the spend of each session in scope. Pattern: ^(\+\|-)?(([0-9]+(\.[0-9]*)?)\|(\.[0-9]+))(([KMGTPE]i)\|[numkMGTPE]\|([eE](\+\|-)?(([0-9]+(\.[0-9]*)?)\|(\.[0-9]+))))?$.
onExceed string onExceed: deny (default), require_approval (MCP tool calls are held for a human; model calls are denied) or alert (log + metric only). One of: deny, require_approval, alert. Default: "deny".
users map[string]object users maps an on-behalf-of user (or "*" for every user without its own entry) to its limits.
users.<key>.currency string currency is the ISO 4217 code of the perUSD amounts (default USD; the USD field names are legacy, see docs/api-conventions.md). It must equal the gateway's budgetCurrency: amounts are never converted and the gateway rejects budgets in another currency. Pattern: ^[A-Z]{3}$.
users.<key>.maxConcurrentSessions integer (int32) maxConcurrentSessions caps the non-terminal, admitted sessions of a namespace (namespaces only; ignored for users). Extra sessions stay Pending with condition QuotaExceeded. Minimum: 0.
users.<key>.perDayUSD int or string perDayUSD caps the scope's spend per day. Pattern: ^(\+\|-)?(([0-9]+(\.[0-9]*)?)\|(\.[0-9]+))(([KMGTPE]i)\|[numkMGTPE]\|([eE](\+\|-)?(([0-9]+(\.[0-9]*)?)\|(\.[0-9]+))))?$.
users.<key>.perMonthUSD int or string perMonthUSD caps the scope's spend per month. Pattern: ^(\+\|-)?(([0-9]+(\.[0-9]*)?)\|(\.[0-9]+))(([KMGTPE]i)\|[numkMGTPE]\|([eE](\+\|-)?(([0-9]+(\.[0-9]*)?)\|(\.[0-9]+))))?$.
users.<key>.perSessionUSD int or string perSessionUSD caps the spend of each session in scope. Pattern: ^(\+\|-)?(([0-9]+(\.[0-9]*)?)\|(\.[0-9]+))(([KMGTPE]i)\|[numkMGTPE]\|([eE](\+\|-)?(([0-9]+(\.[0-9]*)?)\|(\.[0-9]+))))?$.

Status fields#

BudgetPolicyStatus is the observed state of a BudgetPolicy.

The operator writes status; do not set it yourself.

Field Type Required Description
conditions []object
conditions[].lastTransitionTime string (date-time) yes lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
conditions[].message string yes message is a human readable message indicating details about the transition. This may be an empty string. Max length: 32768.
conditions[].observedGeneration integer (int64) observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. Minimum: 0.
conditions[].reason string yes reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. Min length: 1. Max length: 1024. Pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$.
conditions[].status string yes status of the condition, one of True, False, Unknown. One of: True, False, Unknown.
conditions[].type string yes type of condition in CamelCase or in foo.example.com/CamelCase. Max length: 316. Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$.
observedGeneration integer (int64)