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.

name: # Specify the name of the YAML file you are creating.
entities: # This section defines a list of entities.
- type: # Specify the type of entity you are defining.
  name: # Specify the label used to populate the name property on the custom entity.
  scope: # (Optional) Defines how you scope the name. The `name` and `scope` together uniquely identify
         # an entity in the Asserts entity graph. You can use one or more of the options below.
    namespace: # Specify the label used to populate the namespace property of the custom entity.
               # This is usually the namespace label.
    env:  # Specify the label used to populate the `env` property of the custom entity.
          # This is usually the `asserts_env` label.
    site: # Specify the label used to populate the `site` property of the custom entity.
          # This is usually the `asserts_site` label.
  definedBy: # A list of PromQL `query` that Asserts uses to discover the entity.
    - query: # Specify the PromQL query Asserts uses to query the time series database.
      labelValues: # (Optional) Specify a list of properties that are mapped from the label values in the query result.
      metricValue: # (Optional) Specify which property to put the metric value of the query result
      literals: # (Optional) Specify a list of properties that are populated with the literal text
  enrichedBy: # (Optional) Specify a list of PromQL queries that Asserts uses to add more properties.
              # enrichedBy is similar to definedBy, except that enrichedBy doesn't create an entity.
              # enrichBy only adds properties to an entity if the entity is already discovered by definedBy.
 relations: # This section defines relationships
 - type: # Specify the type of relationship you are defining
   startEntityType: # Specify the entity type of the start/from entity in the relationship
   endEntityType: # Specify the entity type of the end/to entity in the relationship
   definedBy: # Specify how the relationship is defined
     source: # Specify one of the two ways to define a relationship. You can use PROPERTY_MATCH or METRICS
     startEntityProperties: # When source is PROPERTY_MATCH, specify a list of properties on the start entity
     endEntityProperties: # When source is PROPERTY_MATCH, specify a list of properties on the end entity whose values match the values of properties listed in the start entity in startEntityProperties
 - type: # Specify the type of relationship you are defining
   startEntityType: # Specify the entity type of the start/from entity in the relationship
   endEntityType: # Specify the entity type of the end/to entity in the relationship
   definedBy: # Specify how the relationship is defined
     source: # Specify one of the two ways to define a relationship, either by PROPERTY_MATCH and by METRICS
     pattern: # When source is METRICS, specify the PromQL query to run
     startEntityMatchers: # When source is METRICS, specify a list of property-label pair used to match the start entity
     endEntityMatchers: # When source is METRICS, specify a list of property-label pair used to match the end entity