groundcover Terraform Provider

Terraform provider for managing groundcover resources.

Usage Examples

Basic usage examples can be found in the examples/ directory:

• Policy Resource: examples/resources/groundcover_policy/resource.tf
  • Demonstrates how to define a groundcover_policy resource, including roles and data scope.
• ServiceAccount Resource: examples/resources/groundcover_serviceaccount/resource.tf
  • Shows how to create and manage service accounts with associated policies.
• API Key Resource: examples/resources/groundcover_apikey/resource.tf
  • Illustrates API key creation and management for service accounts.
• Monitor Resource: examples/resources/groundcover_monitor/resource.tf
  • Provides examples of configuring monitoring rules and alerts.
• Ingestion Key Resource: examples/resources/groundcover_ingestionkey/resource.tf
  • Demonstrates how to create and manage ingestion keys for data ingestion.
• Logs Pipeline Resource: examples/resources/groundcover_logspipeline/resource.tf
  • Shows how to configure logs processing pipelines.
• Traces Pipeline Resource: examples/resources/groundcover_tracespipeline/resource.tf
  • Shows how to configure traces processing pipelines.
• Metrics Aggregation Resource: examples/resources/groundcover_metricsaggregation/resource.tf
  • Demonstrates how to configure metrics aggregation rules for reducing cardinality.
• Metrics Pipeline Resource: examples/resources/groundcover_metricspipeline/resource.tf
  • Demonstrates how to configure metrics relabeling rules (keep/drop metrics, add labels, raw VM relabel rules).
• Dashboard Resource: examples/resources/groundcover_dashboard/resource.tf
  • Demonstrates how to create and manage dashboards with customizable widgets and layouts.
• Data Integration Resource: examples/resources/groundcover_dataintegration/resource.tf
  • Demonstrates how to create and manage data integrations.
• Silence Resource: examples/resources/groundcover_silence/resource.tf
  • Demonstrates how to create and manage alert silences with time windows and matchers.
• Connected App Resource: examples/resources/groundcover_connected_app/resource.tf
  • Demonstrates how to create and manage integrations with external services (Slack, PagerDuty, MS Teams).
• Notification Route Resource: examples/resources/groundcover_notification_route/resource.tf
  • Demonstrates how to create and manage notification routes for routing alerts to connected apps.
• Secret Resource: examples/resources/groundcover_secret/resource.tf
  • Demonstrates how to securely store sensitive values and receive reference IDs for use in other resources.
• Synthetic Test Resource: examples/resources/groundcover_synthetic_test/resource.tf
  • Demonstrates how to create and manage synthetic tests for proactive HTTP, SSL/TLS, TCP, and DNS endpoint monitoring with assertions, retries, authentication support, monitor configuration, and notification routing.
• Silence Resource: examples/resources/groundcover_silence/resource.tf
  • Demonstrates how to create and manage alert silences with matcher-based targeting.

Importing Resources

All resources support terraform import. To import an existing resource into your Terraform state:

terraform import groundcover_<resource_type>.<name> <id>

For most resources, the import ID is the resource's UUID. Some exceptions:

• Ingestion Key: Import by name: terraform import groundcover_ingestionkey.example <name>
• Data Integration: Import using composite key: terraform import groundcover_dataintegration.example <type>:<id>
• Logs Pipeline: Singleton resource — use any value: terraform import groundcover_logspipeline.example any
• Traces Pipeline: Singleton resource — use any value: terraform import groundcover_tracespipeline.example any
• Metrics Pipeline: Singleton resource — use any value: terraform import groundcover_metricspipeline.example any See each resource's documentation in docs/resources/ for the exact import syntax.

Local Development and Testing

To use this provider locally before it is published to the Terraform Registry, follow these steps:

1. Build the Provider: Compile the provider binary using the Makefile:

   make build

   This command typically places the compiled terraform-provider-groundcover executable into the ./dist directory within your project.

2. Configure Terraform CLI for Local Override: Terraform needs to know where to find your locally built provider instead of trying to download it from a registry. Create or edit the Terraform CLI configuration file (~/.terraformrc on macOS/Linux, %APPDATA%\terraform.rc on Windows) and add the following provider_installation block:

   # ~/.terraformrc or %APPDATA%\terraform.rc
   
   provider_installation {
     # Replace "groundcover-com/groundcover" if you used a different source 
     # address in main.go. Replace the path with the actual absolute path
     # to the directory containing the built provider binary (step 1).
     dev_overrides {
       "registry.terraform.io/groundcover-com/groundcover" = "/Users/<YOUR_HOME_FOLDER>/projects/terraform-provider-groundcover/dist"
       # Example for Windows:
       # "registry.terraform.io/groundcover-com/groundcover" = "C:/Users/<YourUser>/path/to/terraform-provider-groundcover/dist"
     }
   
     # For all other providers, install them directly from their origin registries.
     direct {}
   }

   • Important: Replace registry.terraform.io/groundcover-com/groundcover if your provider address in main.go is different.
   • Important: Replace /Users/<YOUR_HOME_FOLDER>/projects/terraform-provider-groundcover/dist with the absolute path to the directory containing the terraform-provider-groundcover binary built by make build.

3. Use in a Terraform Project: In a separate directory for your Terraform configuration:

   • Create a .tf file (e.g., main.tf).
   • Declare the provider requirement, ensuring the source matches the one used in dev_overrides:

     # main.tf
     
     terraform {
       required_providers {
         # This 'source' value MUST exactly match:
         # 1. The key used in your ~/.terraformrc dev_overrides block
         # 2. The 'Address' set in your provider's main.go
         groundcover = {
           source = "registry.terraform.io/groundcover-com/groundcover"
           # Version constraint is still good practice, but less critical
           # for local dev as dev_overrides takes precedence.
           # Use ">= 0.1.0" or similar if you haven't tagged releases yet.
           version = ">= 0.0.0"
         }
       }
     }
     
     # Configure the provider instance
     provider "groundcover" {
       # It's STRONGLY recommended to provide the API key via an environment variable
       # export TF_VAR_groundcover_api_key="YOUR_API_KEY_HERE"
       api_key = var.groundcover_api_key # Use this if defining a variable below
     
       # Base URL is optional, defaults to api.groundcover.com in the provider code
       api_url = "https://api.groundcover.com" # optional, defaults to https://api.groundcover.com - required only for on-prem backends
       backend_id = "groundcover"              # Your Backend ID can be found in the groundcover UI under Settings->Access->API Keys
       # org_name = "groundcover"              # deprecated: use backend_id instead
     }
     
     # (Optional but recommended) Define input variables
     variable "groundcover_api_key" {
       type        = string
       description = "groundcover API Key"
       sensitive   = true
     }
     
     # Define a policy resource using your provider
     resource "groundcover_policy" "test_policy" {
       name        = "My Terraform Test Policy"
       description = "Policy managed via local Terraform provider build"
       claim_role  = "tf-test-claim"
       role = {
         admin  = "admin" # key is "read"/"write"/"admin" - value is ignored
       }
     
       # Example data_scope (adjust based on actual API needs)
       data_scope = {
         simple = {
           operator = "and"
           conditions = [
             {
               key    = "cluster"
               origin = "root"
               type   = "string"
               filters = [
                 {
                   op    = "match"
                   value = "my-prod-cluster"
                 }
               ]
             },
             {
               key    = "namespace"
               origin = "root"
               type   = "string"
               filters = [
                 {
                   op    = "not_match"
                   value = "kube-system"
                 }
               ]
             }
           ]
         }
       }
     }
     
     output "policy_id" {
       value = groundcover_policy.test_policy.uuid
     }
     
     output "policy_revision" {
       value = groundcover_policy.test_policy.revision_number
     }

   • Run terraform init. Terraform will detect the dev_overrides and use your local build.

Requirements

• Terraform >= 1.0 (Check required_version if specified in main.tf)
• Go >= 1.25.7 (to build the provider plugin)
• groundcover Account and API Key.

Provider Reference

Configure the groundcover provider in your Terraform configuration:

provider "groundcover" {
  # api_key    = "YOUR_API_KEY" # Required
  # backend_id = "YOUR_BACKEND_ID" # Required - can be found in the groundcover UI under Settings->Access->API Keys
  # api_url    = "https://api.your-instance.groundcover.com" # Optional
}

Arguments

• api_key (String, Required, Sensitive): Your groundcover API key. It is strongly recommended to configure this using the GROUNDCOVER_API_KEY environment variable rather than hardcoding it.
• backend_id (String, Required): Your groundcover Backend ID. Can be found in the groundcover UI under Settings->Access->API Keys. Can also be set via the GROUNDCOVER_BACKEND_ID environment variable.
• api_url (String, Optional): The base URL for the groundcover API. Defaults to https://api.groundcover.com if not specified. Can also be set via the GROUNDCOVER_API_URL environment variable.

Testing

The provider includes comprehensive acceptance tests for all resources. To run the tests, you'll need access to a groundcover environment.

Prerequisites

To run groundcover tests, you'll need at minimum:

• A valid groundcover Backend ID
• The groundcover API URL
• A valid groundcover API Key

Set the required environment variables:

# Required for all tests
export GROUNDCOVER_API_KEY="your-api-key-here"             # Your groundcover API key
export GROUNDCOVER_API_URL="https://api.groundcover.com/"  # groundcover API URL
export GROUNDCOVER_BACKEND_ID="your-backend-id"            # Your groundcover Backend ID

# Required only for Ingestion Key resource tests (requires in-cloud backend)
export GROUNDCOVER_INCLOUD_BACKEND_ID="your-in-cloud-backend-id"  # In-cloud backend ID for ingestion key tests

Note: The GROUNDCOVER_ORG_NAME environment variable is deprecated. Use GROUNDCOVER_BACKEND_ID instead.

Running Tests

# Run all acceptance tests
TF_ACC=1 go test ./internal/provider -v

# Run acceptance tests with coverage reporting
TF_ACC=1 go test ./internal/provider -v -cover

# Run specific resource tests
TF_ACC=1 go test ./internal/provider -v -run TestAccPolicyResource
TF_ACC=1 go test ./internal/provider -v -run TestAccServiceAccountResource
TF_ACC=1 go test ./internal/provider -v -run TestAccMonitorResource
TF_ACC=1 go test ./internal/provider -v -run TestAccApiKeyResource
TF_ACC=1 go test ./internal/provider -v -run TestAccLogsPipelineResource
TF_ACC=1 go test ./internal/provider -v -run TestAccMetricsAggregationResource
TF_ACC=1 go test ./internal/provider -v -run TestAccMetricsPipelineResource
TF_ACC=1 go test ./internal/provider -v -run TestAccIngestionKeyResource
TF_ACC=1 go test ./internal/provider -v -run TestAccDashboardResource
TF_ACC=1 go test ./internal/provider -v -run TestAccDataIntegrationResource
TF_ACC=1 go test ./internal/provider -v -run TestAccSyntheticTestResource
TF_ACC=1 go test ./internal/provider -v -run TestAccTracesPipelineResource
TF_ACC=1 go test ./internal/provider -v -run TestAccSilenceResource

# Run unit tests only (no API calls required)
go test ./internal/provider -v

Test Coverage

The provider includes comprehensive acceptance tests covering:

• Create, Read, Update, Delete (CRUD) operations for all resources
• Import functionality to ensure resources can be imported into Terraform state
• Disappears testing to verify proper handling when resources are deleted outside Terraform
• Complex configurations including resource relationships and advanced features
• Error handling validation for various API error conditions

Test Architecture

The test suite includes:

• Acceptance tests that interact with real groundcover API endpoints
• Unit tests for utility functions (YAML parsing, error handling)
• Retry logic to handle eventual consistency in cloud APIs
• Environment-specific configurations for different backend types (in-cluster and in-cloud)

Resource Reference

See the REFERENCE.md file for detailed documentation of each resource. For detailed examples of how to use each resource, see the examples directory.