This document outlines the filtering language added to the Allocation API in
v1.96 of Kubecost, superseding the original filtering parameters (e.g.
filterNamespaces=). One of the primary goals of the new filter language was
to introduce support for “not equals” (e.g.
namespace != kubecost) queries
while maintaining extensibility.
V1 filters will continue to be supported in all relevant APIs. APIs will first check for the
filter=parameter. If it is present, V2 filters will be used. If it is not present, APIs will attempt to use V1 filters.
How to use V2 filters
V2 filters exist under the
filter= parameter in supported APIs (initially,
just the Allocation APIs). Here are some example filters to give a feel for the
namespace:"kubecost"+container:"cost-model"Return only results that are in the
kubecostnamespace and are for the
cluster:"cluster-one"+label[app]="cost-analyzer"Return only results in cluster
cluster-onethat are labeled with
cluster!:"cluster-one"Ignore results from cluster
namespace:"kubecost","kube-system"Return only results from namespaces
namespace!:"kubecost","kube-system"Return results for all namespaces except
For example, in an Allocation query:
V2 filter overview
The format is essentially:
<filter field> <filter op> <filter value>
The supported filter fields in v1.96 are:
annotation(same syntax as label, see examples)
The supported filter ops in v1.96 are:
:(equality, or “contains” if an array type)
!:(inequality, or “not contains” if an array type)
Filter values are strings surrounded by
". Multiple values can be separated by commas
,, representing logical OR.
Each individual filter is separated by a
+, representing logical AND.
Formal Grammar and Implementation
To see the filter language’s formal grammar and lexer/parser implementation, check out