Kubecost Allocation API — Model

naftiko: 1.0.0-alpha2
info:
  label: Kubecost Allocation API — Model
  description: 'Kubecost Allocation API — Model. 2 operations. Lead operation: Kubecost Query allocation cost data. Self-contained
    Naftiko capability covering one Kubecost business surface.'
  tags:
  - Kubecost
  - Model
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    KUBECOST_API_KEY: KUBECOST_API_KEY
capability:
  consumes:
  - type: http
    namespace: allocation-model
    baseUri: http://{kubecost-address}
    description: Kubecost Allocation API — Model business capability. Self-contained, no shared references.
    resources:
    - name: model-allocation
      path: /model/allocation
      operations:
      - name: getallocation
        method: GET
        description: Kubecost Query allocation cost data
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: window
          in: query
          type: string
          description: Duration of time over which to query. Accepts units of time (e.g. 3d, 24h, 7d), relative time (e.g.
            yesterday, lastweek, lastmonth), or RFC3339 date pairs.
          required: true
        - name: aggregate
          in: query
          type: string
          description: 'Field by which to aggregate results. Supported values include cluster, namespace, controllerKind,
            controller, service, deployment, statefulset, daemonset, job, '
        - name: step
          in: query
          type: string
          description: Duration of a single allocation set. If unspecified, this defaults to the window, so that you receive
            exactly one set for the entire window.
        - name: accumulate
          in: query
          type: boolean
          description: If true, sum the entire range of sets into a single set.
        - name: idle
          in: query
          type: boolean
          description: Whether to return idle cost. If true, idle allocations are returned.
        - name: external
          in: query
          type: boolean
          description: Whether to include external (out-of-cluster) costs.
        - name: filterClusters
          in: query
          type: string
          description: Filter results by cluster name (comma-separated).
        - name: filterNamespaces
          in: query
          type: string
          description: Filter results by namespace (comma-separated).
        - name: filterControllerKinds
          in: query
          type: string
          description: Filter results by controller kind (comma-separated).
        - name: filterControllers
          in: query
          type: string
          description: Filter results by controller name (comma-separated).
        - name: filterLabels
          in: query
          type: string
          description: Filter results by label in the format label:value (comma-separated).
        - name: filterAnnotations
          in: query
          type: string
          description: Filter results by annotation in the format annotation:value (comma-separated).
        - name: filterServices
          in: query
          type: string
          description: Filter results by service (comma-separated).
        - name: shareIdle
          in: query
          type: boolean
          description: If true, idle cost is allocated proportionally across tenants.
        - name: splitIdle
          in: query
          type: boolean
          description: If true, idle cost is split into separate allocations by cluster and node.
        - name: idleByNode
          in: query
          type: boolean
          description: If true, idle allocations are created on a per-node basis.
        - name: format
          in: query
          type: string
          description: Output format. Supports csv and json.
    - name: model-allocation-totals
      path: /model/allocation/totals
      operations:
      - name: getallocationtotals
        method: GET
        description: Kubecost Query total allocation costs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: window
          in: query
          type: string
          description: Duration of time over which to query.
          required: true
        - name: aggregate
          in: query
          type: string
          description: Field by which to aggregate results.
        - name: filterClusters
          in: query
          type: string
        - name: filterNamespaces
          in: query
          type: string
  exposes:
  - type: rest
    namespace: allocation-model-rest
    port: 8080
    description: REST adapter for Kubecost Allocation API — Model. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/model/allocation
      name: model-allocation
      description: REST surface for model-allocation.
      operations:
      - method: GET
        name: getallocation
        description: Kubecost Query allocation cost data
        call: allocation-model.getallocation
        with:
          window: rest.window
          aggregate: rest.aggregate
          step: rest.step
          accumulate: rest.accumulate
          idle: rest.idle
          external: rest.external
          filterClusters: rest.filterClusters
          filterNamespaces: rest.filterNamespaces
          filterControllerKinds: rest.filterControllerKinds
          filterControllers: rest.filterControllers
          filterLabels: rest.filterLabels
          filterAnnotations: rest.filterAnnotations
          filterServices: rest.filterServices
          shareIdle: rest.shareIdle
          splitIdle: rest.splitIdle
          idleByNode: rest.idleByNode
          format: rest.format
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/model/allocation/totals
      name: model-allocation-totals
      description: REST surface for model-allocation-totals.
      operations:
      - method: GET
        name: getallocationtotals
        description: Kubecost Query total allocation costs
        call: allocation-model.getallocationtotals
        with:
          window: rest.window
          aggregate: rest.aggregate
          filterClusters: rest.filterClusters
          filterNamespaces: rest.filterNamespaces
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: allocation-model-mcp
    port: 9090
    transport: http
    description: MCP adapter for Kubecost Allocation API — Model. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: kubecost-query-allocation-cost-data
      description: Kubecost Query allocation cost data
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: allocation-model.getallocation
      with:
        window: tools.window
        aggregate: tools.aggregate
        step: tools.step
        accumulate: tools.accumulate
        idle: tools.idle
        external: tools.external
        filterClusters: tools.filterClusters
        filterNamespaces: tools.filterNamespaces
        filterControllerKinds: tools.filterControllerKinds
        filterControllers: tools.filterControllers
        filterLabels: tools.filterLabels
        filterAnnotations: tools.filterAnnotations
        filterServices: tools.filterServices
        shareIdle: tools.shareIdle
        splitIdle: tools.splitIdle
        idleByNode: tools.idleByNode
        format: tools.format
      outputParameters:
      - type: object
        mapping: $.
    - name: kubecost-query-total-allocation-costs
      description: Kubecost Query total allocation costs
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: allocation-model.getallocationtotals
      with:
        window: tools.window
        aggregate: tools.aggregate
        filterClusters: tools.filterClusters
        filterNamespaces: tools.filterNamespaces
      outputParameters:
      - type: object
        mapping: $.