4648: Add Asserts provider support for custom models configurations

[matt-metivier]

🎯 Overview

Extends Terraform provider support for managing Asserts configurations through Grafana Cloud by adding a resource for Custom Model Rules. This implementation uses the existing integration with the Grafana Asserts App Plugin, leveraging Grafana Service Account authentication and stack-scoped API calls.

🚀 Features Added

Resources Implemented

• grafana_asserts_custom_model_rules - Manages custom model rule configurations.

Authentication & Architecture

• ✅ Grafana Service Account Token authentication (no separate Asserts tokens needed)
• ✅ Stack-scoped API calls using X-Scope-OrgID headers
• ✅ Grafana Asserts App Plugin integration via plugin API gateway
• ✅ Updated generated API client from grafana-asserts-public-clients/go/gcom

🏗️ Architecture

API Flow:

Terraform Provider → Grafana Service Account Token → Grafana Asserts App Plugin → Asserts Backend

Plugin API Gateway Endpoint:

/api/plugins/grafana-asserts-app/resources/asserts/api-server/v1/config/model-rules

Key Implementation Details:

• Uses generated client from github.com/grafana/grafana-asserts-public-clients/go/gcom
• API calls are routed through the Grafana plugin system, not directly to the Asserts backend.
• The plugin handles authentication and forwards requests to the Asserts service.

Headers Used:

• Authorization: Bearer {token}
• X-Scope-OrgID: {stackID}
• Content-Type: application/json

💻 Example Usage

// Custom Model Rules
resource "grafana_asserts_custom_model_rules" "test" {
  name = "test-anything"
  rules = <<-EOT
    entities:
    - type: Whatever
      name: Nothing
      definedBy:
      - query: "up{job=\\"nothing\\"}"
  EOT
}

📁 Files Added/Modified

New Files

• internal/resources/asserts/resource_custom_model_rules.go - Custom Model Rules resource
• internal/resources/asserts/resource_custom_model_rules_test.go - Custom Model Rules tests
• examples/resources/grafana_asserts_custom_model_rules/resource.tf - Example for Custom Model Rules
• docs/resources/asserts_custom_model_rules.md - Generated documentation

Modified Files

• internal/resources/asserts/resources.go - Registered the new resource
• internal/resources/asserts/catalog-resource.yaml - Added Backstage catalog entry for the new resource
• go.mod / go.sum - Updated grafana-asserts-public-clients dependency

Test Categories

• ✅ Resource schema validation
• ✅ CRUD operations (Create, Read, Update, Delete)
• ✅ Import functionality
• ✅ Error handling and diagnostics
• ✅ Stack ID validation from provider configuration
• ✅ Example configurations

Running Tests

# Run Asserts-specific tests
go test -v ./internal/resources/asserts/... -timeout=30m

# Run all tests including examples
TF_ACC_ASSERTS=true go test -v ./internal/resources/examples_test.go -timeout=30m

🔧 Implementation Notes

Client Configuration

The Asserts client is configured to:

1. Use the standard Grafana URL as its base.
2. Override the server configuration to point to the plugin API gateway.
3. Set the base URL to /api/plugins/grafana-asserts-app/resources/asserts/api-server.
4. Add the proper authorization and stack scoping headers.

Plugin Integration

• Leverages the existing Grafana Asserts App Plugin for API access.
• No direct backend integration is required.
• The plugin handles service routing and authentication.
• Follows established Grafana plugin architecture patterns.

Resource Configuration

• Stack ID from Provider: Uses stack_id from the provider configuration (no per-resource stack ID needed).
• Name-based Resource IDs: Resource IDs are the configuration names.
• Lister Support: The resource supports listing operations for import/discovery.

Error Handling

• Proper error diagnostics for missing client configuration.
• Stack ID validation through provider configuration.
• Graceful handling of API errors with context.

📚 Dependencies

• github.com/grafana/grafana-asserts-public-clients/go/gcom - Generated API client
• Grafana Asserts App Plugin must be installed and enabled on the target stack.
• Requires a Grafana Service Account with appropriate permissions.

🔐 Security & Permissions

• Uses Grafana Service Account authentication.
• Stack-scoped access via X-Scope-OrgID headers.
• No additional Asserts-specific tokens are required.
• Inherits Grafana's existing security model.

[github-actions]

In order to lower resource usage and have a faster runtime, PRs will not run Cloud tests automatically.
To do so, a Grafana Labs employee must trigger the cloud acceptance tests workflow manually.