Author: Chinmay Samant, Co-author: Phani Pawan Padmanabharao

Observability is no longer optional, it’s a foundational requirement for modern, distributed systems. Today’s applications operate across microservices, cloud platforms, and Kubernetes clusters, generating massive volumes of telemetry data. Managing observability configurations manually through UI interactions is not only inefficient but also prone to human error and difficult to reproduce across environments.

This is where Infrastructure as Code (IaC) and Configuration as Code (CaC) become essential.

Tools like Terraform enable teams to define observability configurations declaratively, making them version-controlled, auditable, and easily replicable. This approach ensures consistency across environments, simplifies large-scale deployments, and allows teams to track changes over time, a critical capability for debugging, compliance, and collaboration.

By leveraging the Instana Terraform provider, organisations can automate the setup and management of their observability configurations, significantly reducing operational overhead. This approach enables teams to scale confidently while maintaining full control over critical Instana components, such as alert configurations, custom events, and other observability settings. Treating observability as configuration as code ensures consistency across environments, simplifies deployment processes, and introduces versioning — allowing teams to track changes, audit configurations, and collaborate more effectively.

In this blog, let’s explore how to set up and use the Instana Terraform provider to configure your observability needs in a repeatable, automated way.

Step-by-Step — Setting up your observability with Instana Terraform provider

Let’s walk through two simple but functional examples to get you started.

1. Install Terraform

Ensure that you have Terraform v1.0 or later installed. To verify the installation, run the following command: .

terraform -version

If not installed, install it from the Terraform website.

2. Configure your Instana provider

Create a file named main.tf and define the following configuration:

terraform {
  required_providers {
    instana = {
      source  = "instana/instana"
      version = "~> 5.0"
    }
  }
}

provider "instana" {
  api_token   = var.instana_api_token
  endpoint    = var.instana_endpoint
}

The Instana provider requires an API token (instana_api_token) and Instana endpoint (instana_endpoint). They can be passed through Terraform variables or environment variables

Example endpoint: https://<your-instana-domain>.instana.io/api

3. Create a sample application perspective (Example 1)

Application perspectives in Instana help group services for targeted monitoring.

To add this resource to your main.tf, use the following configuration:

resource "instana_application" "my_app" {
  name = "SampleApp"
  match_specification {
    type  = "SERVICE"
    key   = "entity.label"
    value = "sample-service"
  }
}

4. Create an alerting configuration (Example 2)

Alerting configurations notifies your team when performance or availability thresholds are breached.

To add this resource to your main.tf, use the following configuration:

resource "instana_alerting_config" "high_latency_alert" {
  name                 = "High Latency Alert"
  description          = "Alert when service latency exceeds threshold"
  severity             = "warning"
  alert_channel_ids    = [var.alert_channel_id] # Pre-created alert channel in Instana
  triggering_conditions {
    metric_name = "latency"
    aggregation = "MEAN"
    threshold   = 500   # milliseconds
    operator    = "GREATER_THAN"
    evaluation_window = 300000 # 5 minutes
  }

Replace `var.alert_channel_id` with your actual Instana alert channel ID or a variable definition

5. Apply your configuration

terraform init
terraform plan
terraform apply

You now have both an Instana application perspective and a latency-based alert configured entirely through IaC.

Migrating from gessnerfl/instana

The terraform-provider-instana project was originally maintained under the gessnerfl GitHub organisation. From version v3.0.0, it is officially maintained by IBM under the Instana GitHub organisation.

If you’re currently using the deprecated gessnerfl/terraform-provider-instana, migrate to the new official instana/terraform-provider-instana. For detailed instructions on the migration, see the Migration Guide.

Real-world applications

Teams use the Instana Terraform provider to perform the following actions:

• Automate onboarding of new microservices with preconfigured alerting and dashboards.
• Version-control observability, ensuring that configurations are peer-reviewed and auditable.
• Rapidly replicate environments, ensuring staging and production have identical Instana setups.
• Enable GitOps, where observability changes are merged through pull requests, ensuring governance.

One SRE team reported reducing manual setup time by 70% for new Kubernetes services by using this provider.

Why and how to contribute

The Instana Terraform provider is not just a tool, it’s a community-driven open source project. Every improvement, bug fix, or documentation enhancement you contribute directly helps SREs, DevOps engineers, and cloud architects deliver more reliable, observable systems.

You can contribute in the following ways:

• Code enhancements: Add new resources, features, or optimizations.
• Bug reports and fixes: Help identify and resolve issues faster.
• Documentation improvements: Provide better examples, migration tips, or tutorials.
• Real-world use cases: Share how your team uses the provider to inspire others.

Fork the repo, experiment, and open a PR. Your contributions can make a lasting impact.

References and further reading

• Instana Terraform Provider GitHub Repo
• Migration Guide
• Terraform Registry: Instana Provider
• Instana Provider Documentation