Skip to content

README.md

Latest commit

 

History

History
284 lines (233 loc) · 14.7 KB

README.md

File metadata and controls

284 lines (233 loc) · 14.7 KB

groundcover Terraform Provider

Terraform provider for managing groundcover resources.

Usage Examples

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

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.
⚡