Runs a config-db query.

catalog.yaml
apiVersion: canaries.flanksource.com/v1
kind: Canary
metadata:
  name: node-catalogs
spec:
  schedule: '@every 30s'
  catalog:
    - name: ingress-catalog-check
      selector:
        - types:
            - Kubernetes::IngressClass
      test:
        expr: "size(results) > 0"
          

Field	Description	Scheme
name*	Name of the check, must be unique within the canary	string
selector*		ResourceSelector
description	Description for the check	string
display	Expression to change the formatting of the display	Expression
icon	Icon for overwriting default icon on the dashboard	Icon
labels	Labels for check	[map[string]string]
markFailOnEmpty	If a transformation or datasource returns empty results, the check should fail	boolean
metrics	Metrics to export from	[]Metrics
test	Evaluate whether a check is healthy	Expression
transform	Transform data from a check into multiple individual checks	Expression

Resource Selector

Resource Selectors are used in multiple places including:

• Attaching components to a topology
• Creating relationships between configs and configs/components
• Finding resources to run health checks or playbooks on

Field	Description	Scheme	Required
id	ID of the component	string	No
name	Name of the component/config	string	No
namespace	Select resources in this namespace only, if empty find resources in all namespaces	string	No
types	Match any of the types specified	[]string	No
statuses	Match any of the statuses specified	[]string	No
labelSelector	Kubernetes Style Label Selector	LabelSelector	No
fieldSelector	Kubernetes Style Field Selector Property fields of the component in kubernetes format (or database columns: owner, topology_id, parent_id)	FieldSelector	No
agent	Select resources created on this agent, Defaults to local	uuid, {name}, local or all	No
cache	Cache settings to use for the results, expensive selectors or selectors that are used often should be cached for longer periods. Defaults to max-age=10m	no-cache, no-store or max-age={duration}	No
search	Search for resources via key value pairs using parsing expression grammar	Search	No

Search

The query syntax is field1=value1 field2>value2 field3=value3* field4=*value4. * is for prefix and suffix matching.

Supported operators:

Operator	Syntax	Types
=	field=value	string int json
!=	field!=value	string int json
*	field=*value or field=value*	string int
> <	field>value or field<value	datetime int

Date Queries

• Absolute dates: 2025-01-15
• Relative dates: now-24h, now-7d, now+1w
• Supported units: s (seconds), m (minutes), h (hours), d (days), w (weeks), y (years)

Supported fields for:

• Catalog/Config:

Field	Type
name	string
source	string
namespace	string
type	string
status	string
labels	json
tags	json
config	json
health	string
agent	string
created_at	datetime
updated_at	datetime
deleted_at	datetime

• Catalog/Config Changes:

Field	Type
id	string
config_id	string
name	string
type	string
created_at	datetime
severity	string
change_type	string
summary	string
count	int
first_observed	datetime
agent_id	string
tags	json
details	json

Example Queries

# Find all Kubernetes namespaces starting with "kube"
type=Kubernetes::Namespace name=kube*

# Find unhealthy AWS EC2 instances
type=AWS::EC2::Instance health=unhealthy

# Find critical severity changes for AWS resources
type=AWS::* severity=critical

# Find configs created in the last 24 hours
created_at>now-24h

# Find nginx pods with prod cluster tag
type=Kubernetes::Pod label.app=nginx tags.cluster=prod

# Complex query with date range
updated_at>2025-01-01 updated_at<2025-01-31 type=Kubernetes::Deployment

Examples

catalog-pod-check.yaml
apiVersion: canaries.flanksource.com/v1
kind: Canary
metadata:
  name: k8s-checks
spec:
  schedule: '@every 30s'
  catalog:
    - name: pod-catalog-check
      selector:
        - labelSelector: 'kubernetes.io/app=notification-listener'
          types:
            - Kubernetes::Pod
      test:
        expr: "size(results) > 0"

    # Only namespace starting with kube should be kube-system, kube-public and kube-node-lease
    - name: namespace-search-check
      selector:
        - search: 'kube-* type=Kubernetes::Namespace'
      test:
        expr: "size(results) == 3"