Configure the Knowledge Graph stack using Terraform

The Knowledge Graph stack resource manages the full onboarding flow for your Grafana Cloud stack. It provisions API tokens, configures datasets based on available metrics, and enables the stack.

By default, datasets are auto-configured based on detected metrics. To manually configure datasets, for example when your metrics use non-standard label names, use the dataset block.

Before you begin

Before you begin, ensure you have the following:

• A Grafana Cloud account, as shown in Get started
• Terraform installed on your machine
• The Grafana Terraform provider configured, as shown in Get started with Terraform for Knowledge Graph
• Knowledge Graph enabled on your Grafana Cloud stack
• A Cloud Access Policy with the following scopes: stacks:read, metrics:read, metrics:write

Dataset types

The following dataset types are available:

• kubernetes: Kubernetes metrics. Requires Kubernetes Monitoring to be enabled on your stack.
• otel: Application Observability metrics. Requires Application Observability to be enabled on your stack.
• prometheus: Standard Prometheus metrics.
• aws: Amazon Web Services metrics.

Create the required tokens

Before you configure the Knowledge Graph stack, create the Cloud Access Policy and Grafana Service Account tokens that the resource requires.

Create a file named knowledge-graph-stack.tf and add the following:

# Create a Cloud Access Policy with required scopes
resource "grafana_cloud_access_policy" "knowledge_graph" {
  name         = "knowledge-graph-stack-policy"
  display_name = "Knowledge Graph Stack Policy"

  scopes = [
    "stacks:read",
    "metrics:read",
    "metrics:write",
  ]

  realm {
    type       = "stack"
    identifier = var.stack_id
  }
}

# Create a token from the Cloud Access Policy
resource "grafana_cloud_access_policy_token" "knowledge_graph" {
  name             = "knowledge-graph-stack-token"
  access_policy_id = grafana_cloud_access_policy.knowledge_graph.policy_id
}

# Create a Grafana Service Account for dashboards and Grafana Managed Alerts
resource "grafana_cloud_stack_service_account" "knowledge_graph" {
  stack_slug  = var.stack_slug
  name        = "knowledge-graph-managed-alerts-sa"
  role        = "Admin"
  is_disabled = false
}

resource "grafana_cloud_stack_service_account_token" "knowledge_graph" {
  stack_slug         = var.stack_slug
  service_account_id = grafana_cloud_stack_service_account.knowledge_graph.id
  name               = "knowledge-graph-managed-alerts-token"
}

variable "stack_id" {
  description = "The Grafana Cloud stack ID"
  type        = string
}

variable "stack_slug" {
  description = "The Grafana Cloud stack slug"
  type        = string
}

Replace the following values:

• <STACK_ID> with your Grafana Cloud stack ID
• <STACK_SLUG> with your Grafana Cloud stack slug

Basic stack configuration with auto-detected datasets

The simplest configuration provisions tokens and auto-detects datasets based on available metrics. This is the recommended approach when your metrics use standard label names.

Add the following to knowledge-graph-stack.tf:

resource "grafana_asserts_stack" "main" {
  cloud_access_policy_token = grafana_cloud_access_policy_token.knowledge_graph.token
  grafana_token             = grafana_cloud_stack_service_account_token.knowledge_graph.key
}

When you apply this configuration, the resource:

1. Provisions API tokens for Grafana Cloud, Mimir, and the assertion detector
2. Auto-detects available datasets based on your stack's metrics
3. Enables the stack with the detected datasets

Configure the dataset manually

Use manual configuration when your metrics use non-standard label names, for example a custom environment label. Each dataset block configures one dataset type.

resource "grafana_asserts_stack" "manual" {
  cloud_access_policy_token = grafana_cloud_access_policy_token.knowledge_graph.token
  grafana_token             = grafana_cloud_stack_service_account_token.knowledge_graph.key

  dataset {
    type = "kubernetes"

    filter_group {
      env_label  = "deployment_environment"
      site_label = "cluster"

      env_label_values  = ["production", "staging"]
      site_label_values = ["us-east-1", "eu-west-1"]
    }
  }
}

{{< admonition type="note" >}} When you specify one or more dataset blocks, auto-detection is skipped. You must define all datasets you want to configure. {{< /admonition >}}

Configure multiple datasets with filters

Configure multiple dataset types with custom label mappings and metric filters:

resource "grafana_asserts_stack" "multi_dataset" {
  cloud_access_policy_token = grafana_cloud_access_policy_token.knowledge_graph.token
  grafana_token             = grafana_cloud_stack_service_account_token.knowledge_graph.key

  dataset {
    type = "kubernetes"

    filter_group {
      env_label  = "deployment_environment"
      site_label = "cluster"

      env_label_values  = ["production", "staging"]
      site_label_values = ["us-east-1", "eu-west-1"]
    }
  }

  dataset {
    type = "prometheus"

    filter_group {
      env_label = "environment"
      env_name  = "prod"

      filter {
        name     = "region"
        operator = "=~"
        values   = ["us-.*", "eu-.*"]
      }
    }
  }
}

Resource reference

grafana_asserts_stack

Manage the Knowledge Graph stack configuration through the Grafana API. This resource handles the full onboarding flow including token provisioning, dataset configuration, and stack enablement.

Arguments

Attributes

Dataset block

Each dataset block supports the following:

Filter group block

Each filter_group block supports the following:

Filter block

Each filter block supports the following:

Example

resource "grafana_asserts_stack" "example" {
  cloud_access_policy_token = grafana_cloud_access_policy_token.knowledge_graph.token
  grafana_token             = grafana_cloud_stack_service_account_token.knowledge_graph.key

  dataset {
    type = "kubernetes"

    filter_group {
      env_label         = "deployment_environment"
      site_label        = "cluster"
      env_label_values  = ["production"]
      site_label_values = ["us-east-1"]
    }
  }
}

Best practices

Consider the following best practices when configuring the Knowledge Graph stack with Terraform.

Token management

• Create a dedicated Cloud Access Policy for the Knowledge Graph stack with only the required scopes
• Use separate Service Accounts for different purposes rather than sharing a single admin token
• Rotate tokens regularly and use sensitive variable handling in Terraform to avoid exposing tokens in logs
• Store tokens in a secret management system and reference them through Terraform variables

Dataset configuration

• Start with auto-detected datasets and switch to manual configuration only when needed
• When using manual configuration, define all datasets you want to monitor
• Use specific env_label_values and site_label_values to limit the scope of monitoring
• Test dataset configurations in a non-production stack first

Filter groups

• Use filter groups when your metrics use non-standard label names
• Match your env_label and site_label values to the actual label names in your Prometheus metrics
• Use regular expression operators (=~, !~) in filters for flexible value matching across regions or environments
• Keep filter configurations consistent across datasets for predictable behavior

Validation

After applying the Terraform configuration, verify that:

• The stack status shows as enabled by checking the enabled output attribute
• The status attribute indicates successful onboarding
• Datasets are configured correctly in the Knowledge Graph UI
• Dashboards and alerting rules are installed when grafana_token is provided

You can inspect the stack status using Terraform outputs:

output "stack_enabled" {
  value       = grafana_asserts_stack.main.enabled
  description = "Whether the Knowledge Graph stack is enabled"
}

output "stack_status" {
  value       = grafana_asserts_stack.main.status
  description = "Current onboarding status of the stack"
}

output "stack_version" {
  value       = grafana_asserts_stack.main.version
  description = "Configuration version number"
}

Related documentation

• Knowledge Graph documentation
• Get started with Terraform for Knowledge Graph
• Grafana Terraform Provider documentation
• Cloud Access Policies
• Service accounts