Manage entities and relations
After you have set up Asserts to scan your environment, the Asserts graph builder service uses a series of queries to extract entities and properties from your Prometheus metric labels. Every discovered entity is categorized into a type such as Service, Node, or Pod. Asserts associates each entity with a set of properties that describe the attributes of the entity. For example, a Service entity has properties such as version
, container
, run_time
, and more. Asserts populates these properties with data sourced from label values or metric values retrieved from PromQL query results.
Asserts supports a wide range of entity types, including:
- Data sources
- Environments
- Kubernetes clusters
- Namespaces
- Nodes
- Node groups
- Pods
- Services
- Service instances
- Volumes
Additionally, the graph builder service extracts the relationships between these entities, displaying them as arrows on the entity graph within Asserts. Asserts supports relationship types such as HOST
, CONTROL
, and PRODUCES
. Entity and relationship discovery is foundational to Asserts, providing a comprehensive view of your environment’s structure and connections.
While Asserts discovers most, if not all, of the entities and relationships in your environment, there might be cases when you need to define custom entities and relationship.
Example: How Asserts defines entities
The following example shows the definition of an entity type called Job
. The label label_framework_task_name
is the name of the entity which uses the asserts_env
label as the env
property in the scope section. The entity populates the namespace
property from the label_framework_namespace
label.
- type: Job
name: label_framework_task_name
scope:
env: asserts_env
definedBy:
- query: |
group by (asserts_env, label_framework_namespace, label_framework_task_name) (
kube_job_labels{label_app_kubernetes_io_component="task"}
)
labelValues:
namespace: label_framework_namespace
Example: How Asserts defines relationships
Asserts defines relations between entities using the PROPERTY_MATCH
method or the METRICS
method.
In the following PROPERTY_MATCH
example, the Asserts graph builder adds a HOSTS
relationship from a KubeCluster
entity to NodeGroup
entity, as long as the name
, env
, and site
properties on the KubeCluster
entity match the cluster
, env
, and site
properties of the NodeGroup
entity.
- type: HOSTS
startEntityType: KubeCluster
endEntityType: NodeGroup
definedBy:
source: PROPERTY_MATCH
startEntityProperties: [name, env, site]
endEntityProperties: [cluster, env, site]
In the following METRICS
example, the Asserts graph builder runs the query defined in pattern
, and uses the label values of pod
and namespace
to match the start entity, while using the label values of persistentvolumeclaim
and namespace
to match the end entity.
- type: USES
startEntityType: Pod
endEntityType: Volume
definedBy:
source: METRICS
pattern: |-
group by (pod, namespace, persistentvolumeclaim, asserts_env, asserts_site)(
kube_pod_spec_volumes_persistentvolumeclaims_info{asserts_env!=""}
)
startEntityMatchers:
name: pod
namespace: namespace
endEntityMatchers:
name: persistentvolumeclaim
namespace: namespace
Define custom entities and relationships
This section shows you how to define custom entities and relationships.
Before you begin
Before you begin, ensure that:
- You are familiar with the syntax of PromQL and YAML.
- You have sample PromQL query results available. You refer to the query results when you define a custom entity.
Steps
To define custom entities and relationship, complete the following steps:
Sign in to Grafana Cloud and click Asserts > Rules.
Click Entity & Relationship.
Click + New rule file.
Copy and paste the following YAML file contents into the View/Edit YML file field and complete it.
Click Save.