Deploy Instana Agents on Amazon EC2 and Amazon ECS with Terraform

As organizations continue to scale their cloud environments to meet growing business demand, combining workload provisioning with IBM Instana observability in a single workflow improves operational efficiency. Teams use Terraform to provision Amazon Elastic Compute Cloud (Amazon EC2) instances and Amazon Elastic Container Service (Amazon ECS) resources. They then manually install the IBM Instana agent, configure dashboards and follow that up with alerts in the UI.

With Instana’s Terraform provider, Amazon EC2 module and Amazon ECS module, both resource provisioning and monitoring happen with reduced manual intervention. The same Terraform run that provisions the AWS workload also deploys the Instana agent to configure observability.

IBM Instana publishes a Terraform provider and the agent modules in the public Terraform Registry. The provider turns Instana settings, application perspectives, alerts, access control and service level objectives into declarative resources. So teams can review and merge monitoring just like any other code. The Terraform modules wrap the most common agent deployments for Amazon EC2 and Amazon ECS. You can consume them directly or use them as templates for your own configurations.

In this post we show you how the Instana Terraform building blocks fit together and how a single workflow helps you set up a fully monitored Amazon EC2 or Amazon ECS workload – we call this observability as code.

Solution Overview

The solution combines two Terraform providers in one configuration. The AWS provider provisions the workload, networking, security group, AWS Identity and Access Management (AWS IAM) role and the Amazon EC2 instance or Amazon ECS task. The Instana provider configures the observability layer through the Instana REST API. The agent module sits between them: it installs the Instana agent on the workload. Then the agent reports metrics, traces and events back to the Instana backend.

Because everything is declared as code, monitoring never drifts away from the workload it watches. Every environment is provisioned identically, every change is reviewable in source control and the instance is observable the moment it starts.

Reference Architecture

Figure 1 shows the dual-provider model. A single configuration drives both providers: the AWS provider builds the workload and installs the agent, then the Instana provider creates the observability resources. Oneterraform applycreates both resources and observability.

Terraform configuration drives the AWS provider, which provisions an EC2/ECS workload running the Instana agent, and the Instana provider, which configures observability resources in the Instana backend; a dashed arrow shows the agent reporting telemetry to the backend.

FIgure 1. Dual-provider Terraform configuration for Amazon EC2 and Amazon ECS workloads with Instana Observability.

Implementation

Pre-requisites

Ensure that you have the following to be able to perform the implementation steps in the next section:

An AWS account with permissions to create Amazon Virtual Private Cloud (Amazon VPC) and networking, security groups, AWS IAM roles and Amazon EC2 or Amazon ECS resources, with AWS credentials configured. Refer to the AWS provider in the Terraform documentation.
Basic knowledge of AWS IAM, Amazon VPC, Amazon EC2 and Amazon ECS.
Terraform 5 or later installed.
Working knowledge of Terraform (init, plan, apply).
Terraform AWS provider (>= 5.0) and Terraform Instana provider (>= 7.0).
An active subscription to IBM Instana Observability. You can start with an Instana free trial from AWS Marketplace.
An IBM Instana account with an agent key, the Instana backend endpoint and an API token for the provider. See the Instana documentation.

Cost considerations

If you follow this walkthrough in your own AWS account, you will incur charges for any AWS resources that you create.For detailed pricing information, see Amazon ECS pricing, Amazon EC2 pricing, Amazon VPC pricing, and use the AWS Pricing Calculator to estimate your monthly costs. The cleanup section at the end of this post explains how to remove resources and stop ongoing charges.

The Instana building blocks

Instana’s Terraform assets live under a single namespace calledinstanain the Terraform Registry, the central place to discover and consume them. It contains one provider and two modules. The provider exposes more than 25 resources and 7 data sources, so Instana configuration that you would otherwise set by hand becomes declarative. The two modules are instana-ec2-agent for Amazon EC2 workloads and instana-ecs-agent for Amazon ECS workloads, each shipping with a README and both a basic and a complete example.

Walkthrough

In this walkthrough, you add the Instana agent module and observability modules to a Terraform configuration, then initialize, plan and apply it to provision a fully monitored workload. A real project is modular: the agent module plus a set of observability modules, all version-controlled and repeatable.

Step 1. Add the Instana modules to your Terraform configuration

In the Terraform Registry, open the instana namespace and locate the Instana provider and theinstana-ec2-agentorinstana-ecs-agentmodule, as shown in Figure 2.

Screenshot of Instana console showing the instana namespace in the Terraform Registry, one provider and two modules named instana-ec2-agent and instana-ecs-agent.

Figure 2. The instana namespace in the Terraform Registry, one provider and two modules named instana-ec2-agent and instana-ecs-agent.

In your rootmain.tf, declare the aws and instana providers then add the agent module, as shown in the following example:

provider "aws"     { region = var.region }
provider "instana" {
  api_token = var.instana_api_token
  endpoint  = var.instana_endpoint
}
 
module "instana_agent" {
  source  = "instana/instana-ec2-agent/aws"  # or instana-ecs-agent
  version = "1.0.0"
  region  = var.region
  # vpc_id, subnet_id, agent key, endpoint, security group, tags follow
}

Replace the variable values with your AWS network settings and your Instana agent key, endpoint and API token.

For the full reference setup, including the observability modules, see the Instana Terraform provider repository on GitHub.

Step 2. Initialize the working directory

From the root of your configuration, run the following command:

$ terraform init

Verify that Terraform downloads the AWS provider, the Instana provider and the agent module successfully.

Step 3. Preview the change set

Run the following command:

$ terraform plan

Review the planned changes. In this example, the plan shows fifteen resources spanning AWS infrastructure and Instana configuration.

Step 4. Apply the configuration

Run the following command:

$ terraform apply

When prompted, review the plan and enter yes to confirm. A single run provisions the AWS workload and the Instana observability resources together. Figure 3 traces the flow end to end.

Flowchart of terraform init, plan and apply forking into two branches, the AWS workload (instance plus reporting agent) and the Instana observability resources, then converging on verification and a monitored-from-day-one outcome.

Figure 3. Terraform init, plan, and apply provisions AWS workload resources and Instana observability in parallel, then converges on verification.

Step 5. Verify the deployment in Instana

In your Instana console, open the infrastructure map and confirm that the new host is reporting, as shown in Figure 4.
Confirm the resources created by the observability modules: an application perspective that scopes monitoring to a service, an alerting setup with an email channel and a log-based alert, mobile application monitoring, a role-based access control (RBAC) configuration with roles and a team and an SLO that tracks availability over a rolling window. All of these appear in Instana without a manual step.

Screenshot of Instana console showing the provisioned workload reporting into Instana’s Infrastructure map, the payoff of the apply

Figure 4. The provisioned workload reporting into Instana’s Infrastructure map.

Cleaning up

To remove everything that this walkthrough created, run the following command:

$ terraform destroy

Because the workload and its observability are managed by the same configuration, this single command removes the AWS resources and the Instana configuration created by the run.

Observability as code across the IT ecosystem

A single monitored Amazon EC2 instance is the smallest version of this pattern. The same modules scale to fleets of instances across AWS accounts and Regions, including ephemeral Continuous Integration (CI) environments. You can also add them to AWS Service Catalog so that teams can provision a fully monitored environment from a single module call.

Gartner projected that by 2026, 80% of large software engineering organizations will have platform teams that provide reusable services and tools for application delivery, up from 45% in 2022. A reusable observability module fits this model. Defining observability once and reusing it across environments reduces the need for specialized knowledge on every team.

When you treat observability as code, agent settings, application perspectives, alerts, RBAC and service level objectives (SLOs) become reviewable artifacts. They move through the same pull requests, policy-as-code checks and CI gates as the infrastructure they describe. Drift detection and audit trails extend to the observability layer and alert thresholds become versioned definitions that anyone can inspect.

Today the modules target Amazon EC2 and Amazon ECS. As coverage expands to additional providers, the same declarative workflow produces a consistent observability configuration across heterogeneous environments.

Conclusion

By publishing a Terraform provider along with Amazon EC2 and Amazon ECS agent modules, Instana lets you treat observability the way you treat the rest of your infrastructure: declared in code, reviewed in pull requests and applied in one repeatable run. The workload and the monitoring that watches it are never out of step, because they are provisioned together providing observability from day one, with no additional manual configuration.

Instana Obsevability is actively expanding to additional resources, bringing the same observability-as-code experience across hybrid environments. Try the modules from the Terraform Registry, explore the reference setup on GitHub and adapt them to your own environments.

Additional resources

AWS Marketplace:

Documentation:

Instana on the Terraform Registry: terraform.io/namespaces/instana
Instana EC2 agent module: instana-ec2-agent/aws
Instana ECS agent module: instana-ecs-agent/aws
Instana Terraform provider (GitHub): terraform-provider-instana
IBM Instana Observability: com/products/instana
IBM Instana documentation: com/docs/en/instana-observability
HashiCorp, Terraform AWS provider, 5 billion downloads: com/blog
Gartner, Platform engineering: com/platform-engineering

IBM & Red Hat on AWS