grafana/docs/sources/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/custom-model-rules.md

description, menuTitle, title, weight, keywords, canonical

description	menuTitle	title	weight	keywords	canonical
Define custom entity models for Knowledge Graph using Terraform	Custom model rules	Create custom model rules using Terraform	400	Terraform Knowledge Graph Custom Model Rules Entity Models Prometheus	https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/custom-model-rules/

Create custom model rules using Terraform

Custom model rules in Knowledge Graph allow you to define how entities are discovered and modeled based on Prometheus queries. These rules enable you to create custom entity types, define their relationships, and specify how they should be enriched with additional data.

For information about managing entities and relations in the Knowledge Graph UI, refer to Manage entities and relations.

Basic custom model rules

Create a file named custom-model-rules.tf and add the following:

# Basic custom model rule for services
resource "grafana_asserts_custom_model_rules" "basic_service" {
  provider = grafana.asserts

  name = "basic-service-model"

  rules {
    entity {
      type = "Service"
      name = "service"

      defined_by {
        query = "up{job!=''}"
        label_values = {
          service = "job"
        }
        literals = {
          _source = "up_query"
        }
      }
    }
  }
}

Advanced service model with scope and lookup

Define service entities with environment scoping and relationship mappings:

# Advanced service model with environment scoping
resource "grafana_asserts_custom_model_rules" "advanced_service" {
  provider = grafana.asserts

  name = "advanced-service-model"

  rules {
    entity {
      type = "Service"
      name = "workload | service | job"

      scope = {
        namespace = "namespace"
        env       = "asserts_env"
        site      = "asserts_site"
      }

      lookup = {
        workload  = "workload | deployment | statefulset | daemonset | replicaset"
        service   = "service"
        job       = "job"
        proxy_job = "job"
      }

      defined_by {
        query = "up{job!='', asserts_env!=''}"
        label_values = {
          service     = "service"
          job         = "job"
          workload    = "workload"
          namespace   = "namespace"
        }
        literals = {
          _source = "up_with_workload"
        }
      }

      defined_by {
        query    = "up{job='maintenance'}"
        disabled = true
      }
    }
  }
}

Multi-entity model configuration

Define multiple entity types in a single configuration:

# Multiple entity types in a single model
resource "grafana_asserts_custom_model_rules" "multi_entity" {
  provider = grafana.asserts

  name = "kubernetes-entities"

  rules {
    # Service entity
    entity {
      type = "Service"
      name = "service"

      scope = {
        namespace = "namespace"
        cluster   = "cluster"
      }

      defined_by {
        query = "up{service!=''}"
        label_values = {
          service   = "service"
          namespace = "namespace"
          cluster   = "cluster"
        }
      }
    }

    # Pod entity
    entity {
      type = "Pod"
      name = "Pod"

      scope = {
        namespace = "namespace"
        cluster   = "cluster"
      }

      lookup = {
        service   = "service"
        workload  = "workload"
      }

      defined_by {
        query = "kube_pod_info{pod!=''}"
        label_values = {
          Pod       = "pod"
          namespace = "namespace"
          cluster   = "cluster"
          service   = "service"
        }
        literals = {
          _entity_type = "Pod"
        }
      }
    }

    # Namespace entity
    entity {
      type = "Namespace"
      name = "namespace"

      scope = {
        cluster = "cluster"
      }

      defined_by {
        query = "kube_namespace_status_phase{namespace!=''}"
        label_values = {
          namespace = "namespace"
          cluster   = "cluster"
        }
      }
    }
  }
}

Complex entity with enrichment

Create service entities with multiple data sources and enrichment:

# Service entity with enrichment from multiple sources
resource "grafana_asserts_custom_model_rules" "enriched_service" {
  provider = grafana.asserts

  name = "enriched-service-model"

  rules {
    entity {
      type = "Service"
      name = "service"

      enriched_by = [
        "prometheus_metrics",
        "kubernetes_metadata",
        "application_logs"
      ]

      scope = {
        environment = "asserts_env"
        region      = "asserts_site"
        team        = "team"
      }

      lookup = {
        deployment = "workload"
        Pod        = "pod"
        container  = "container"
      }

      # Primary definition from service up metrics
      defined_by {
        query = "up{service!='', asserts_env!=''}"
        label_values = {
          service     = "service"
          environment = "asserts_env"
          region      = "asserts_site"
          team        = "team"
        }
        literals = {
          _primary_source = "service_up"
        }
      }

      # Secondary definition from application metrics
      defined_by {
        query = "http_requests_total{service!=''}"
        label_values = {
          service     = "service"
          environment = "environment"
          version     = "version"
        }
        literals = {
          _secondary_source = "http_metrics"
        }
      }

      # Disabled definition for testing
      defined_by {
        query    = "test_metric{service!=''}"
        disabled = true
      }
    }
  }
}

Database and infrastructure entities

Define database and infrastructure entity models:

# Database and infrastructure entity models
resource "grafana_asserts_custom_model_rules" "infrastructure" {
  provider = grafana.asserts

  name = "infrastructure-entities"

  rules {
    # Database entity
    entity {
      type = "Database"
      name = "database_instance"

      scope = {
        environment = "env"
        region      = "region"
      }

      lookup = {
        host     = "instance"
        port     = "port"
        db_name  = "database"
      }

      defined_by {
        query = "mysql_up{instance!=''}"
        label_values = {
          database_instance = "instance"
          database         = "database"
          env             = "environment"
          region          = "region"
        }
        literals = {
          _db_type = "mysql"
        }
        metric_value = "1"
      }

      defined_by {
        query = "postgres_up{instance!=''}"
        label_values = {
          database_instance = "instance"
          database         = "datname"
          env             = "environment"
        }
        literals = {
          _db_type = "postgresql"
        }
      }
    }

    # Load balancer entity
    entity {
      type = "LoadBalancer"
      name = "lb_instance"

      scope = {
        environment = "env"
      }

      defined_by {
        query = "haproxy_up{proxy!=''}"
        label_values = {
          lb_instance = "instance"
          proxy      = "proxy"
          env        = "environment"
        }
        literals = {
          _lb_type = "haproxy"
        }
      }
    }
  }
}

Resource reference

grafana_asserts_custom_model_rules

Manage Knowledge Graph custom model rules through the Grafana API. This resource allows you to define custom entity models based on Prometheus queries with advanced mapping and enrichment capabilities.

Arguments

Name	Type	Required	Description
name	string	Yes	The name of the custom model rules. This field is immutable and forces recreation if changed.
rules	list(object)	Yes	The rules configuration containing entity definitions. Refer to rules block for details.

Rules block

Each rules block supports the following:

Name	Type	Required	Description
entity	list(object)	Yes	List of entity definitions. Refer to entity block for details.

Entity block

Each entity block supports the following:

Name	Type	Required	Description
type	string	Yes	The type of the entity (for example, Service, Pod, Namespace).
name	string	Yes	The name pattern for the entity. Can include pipe-separated alternatives.
defined_by	list(object)	Yes	List of queries that define this entity. Refer to defined_by block for details.
disabled	bool	No	Whether this entity is disabled. Defaults to false.
enriched_by	list(string)	No	List of enrichment sources for the entity.
lookup	map(string)	No	Lookup mappings for the entity to relate different label names.
scope	map(string)	No	Scope labels that define the boundaries of this entity type.

defined_by block

Each defined_by block supports the following:

Name	Type	Required	Description
query	string	Yes	The Prometheus query that defines this entity.
disabled	bool	No	Whether this query is disabled. Defaults to false.
label_values	map(string)	No	Label value mappings for extracting entity attributes from query results.
literals	map(string)	No	Literal value mappings for adding static attributes to entities.
metric_value	string	No	Metric value to use from the query result.

{{< admonition type="note" >}} When disabled = true is set for a defined_by query, only the query field is used for matching. All other fields in the block are ignored. {{< /admonition >}}

Best practices

Entity models

• Design your entity models to reflect your actual infrastructure and application architecture
• Use descriptive names for custom model rules that indicate their purpose and scope
• Start with basic entity definitions and gradually add complexity as needed
• Define clear entity scopes using the scope parameter to organize entities by environment, region, or team

Query design and performance

• Write efficient Prometheus queries that don't overload your monitoring system
• Test your Prometheus queries independently before using them in model rules
• Use specific label filters to reduce the scope of your queries where possible
• Consider the cardinality implications of your entity definitions
• Use the disabled flag to temporarily disable problematic queries during debugging

Relationships and enrichment

• Use lookup mappings to establish relationships between different entity types
• Leverage enriched_by to specify additional data sources for entity enrichment
• Map Prometheus labels to entity attributes using clear and descriptive names
• Use meaningful literals to add static metadata that helps with entity identification

Label and attribute management

• Establish consistent labeling conventions across your infrastructure
• Use label_values to extract dynamic attributes from your metrics
• Document the meaning and expected values of custom literals
• Ensure label names match across different entity definitions for proper relationship discovery

Validation

After applying the Terraform configuration, verify that:

• Custom model rules are applied in your Knowledge Graph instance
• Entities are being discovered according to your defined queries
• Entity relationships and enrichment are working as expected
• Entity graphs display the correct entity types and connections
• Queries perform well without causing excessive load

Related documentation

• Manage entities and relations in Knowledge Graph
• Get started with Terraform for Knowledge Graph
• Knowledge graph basics