> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-discovery-discovery/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview/deployment-using-cloudformation.md).

# Deployment using CloudFormation

AWS CloudFormation builds infrastructure from a template file, so the same template gives you the same deployment every time. The Harness template deploys the AWS CloudWatch agent into your AWS account as a CloudFormation stack. The stack runs the agent on an EC2 instance or as ECS Fargate tasks, and it runs whichever collectors you turn on: API Gateway, Bedrock, AgentCore, or any mix of the three.

You can deploy the stack from the AWS console or with the AWS CLI. This topic covers both.

## What will you learn in this topic?

By the end of this topic, you will understand:

* The steps to prepare your AWS services and credentials for the agent.
* The steps to deploy the stack from the console and from the AWS CLI.
* The purpose of each CloudFormation parameter that you are likely to set.
* The way to build the `Accounts` value, and to remove the stack.

***

## Before you begin

* Make sure that you know which collectors you want. You must turn on at least one, or CloudFormation rejects the stack and creates nothing.
* Make sure that the AWS CLI is configured with credentials that can create the resources in the target account and region, if you plan to deploy from the CLI. Step 2 covers this.
* Make sure that you have a TPA set up. The agent sends all its data to the TPA, so follow the [TPA installation guide](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-discovery-discovery/installation/platform-agent.md) first, then note the TPA's URL. The URL must be reachable from the place where the agent runs. You enter it as `TraceableAgentEndpoint` in Step 6.
* Make sure that API Gateway logging, Bedrock model-invocation logging, or AgentCore observability is turned on for the services you want to collect. Step 1 covers all three.
* Make sure that you have the ID of the subnet where the agent will run, because the stack creates the agent inside it. For `ecs` mode, you also need the ARN of an existing ECS Fargate cluster.

***

## Understand the deployment modes

The `DeploymentMode` parameter decides where the agent runs. The two modes use different parameters, so pick one before you fill in the template.

The following table describes the two modes, what the stack creates in each, and when to choose one over the other.

| Mode            | What the Stack Creates                                                                  | Use It When                                                                                 |
| --------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `ec2` (default) | An EC2 instance in the subnet you specify, with the agent running on it                 | You want the agent to run on one instance and you do not want to manage a container cluster |
| `ecs`           | Resources that start the agent as an ECS task on a schedule, through Amazon EventBridge | You already run an ECS Fargate cluster and want the agent to run as a task                  |

In `ecs` mode, the template also creates a helper AWS Lambda function named `ECSCustomResource`. It creates the EventBridge schedules for you. You never invoke it yourself, but it shows up in the stack's resource list, and its logs help you when a stack fails.

***

## Step 1: Prepare your AWS services

The agent does not create logs. It reads logs that your AWS services already write to CloudWatch Logs, so each service you want to collect from has to be logging first. The three collectors read different logs, so the preparation differs for each. API Gateway needs access logs in a specific JSON format. Bedrock needs model invocation logging enabled, plus the name of its log group, in your agent configuration. AgentCore needs observability turned on and nothing more.

Do only the parts for the collectors you plan to turn on. If you turn on more than one, do each part.

### API Gateway (REST APIs)

Use this section if the API Gateway collector will read REST APIs. The collector reads each stage's access logs, so every stage you want to collect from must write them in a format the agent can parse.

Complete the following for every stage you want to collect from:

1. Open the API Gateway console and select your API, then select the stage.
2. Go to **Logs/tracing**.
3. In the **CloudWatch Logs** drop-down, select **Error and info logs**.
4. Turn on **Custom Access Logging**.
5. In **Access log destination ARN**, enter the ARN of a CloudWatch log group. This is where API Gateway writes the access logs that the agent reads.
6. In **Log Format**, paste the following JSON:

```json
{
  "requestId": "$context.requestId",
  "ip": "$context.identity.sourceIp",
  "httpMethod": "$context.httpMethod",
  "path": "$context.path",
  "status": "$context.status",
  "responseLength": "$context.responseLength",
  "domainName": "$context.domainName"
}
```

Each field maps to an API Gateway `$context` variable. API Gateway populates the variables for every request, so each log line includes the request ID, the caller's IP address, the HTTP method, the path, the status code, the response size, and the domain name. The agent expects these fields in every log line, so leave none out.

### API Gateway (HTTP APIs)

Use this section if the API Gateway collector will read HTTP APIs. The agent reads them the same way it reads REST APIs, so the log format is the same. Only the place where you turn logging on differs.

Turn on access logging for the stage and use the same JSON format as in the REST APIs section. That way, every log line carries the fields the agent needs.

### Bedrock

Use this section if you turn on the Bedrock collector. The collector reads Bedrock’s model invocation logs from CloudWatch Logs, so you need to complete two tasks: enable logging in Amazon Bedrock and specify the log group to read.

{% hint style="info" %}
**Note**: The Bedrock collector reads model invocation logs, which AWS provides for Amazon Bedrock Runtime. It does not collect data from Bedrock Mantle, because AWS does not support model invocation logging for it.
{% endhint %}

1. Turn on model invocation logging in Amazon Bedrock, and send the logs to a CloudWatch Logs log group. AWS describes the steps in its [model invocation logging documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-invocation-logging.html).
2. Add the name of that log group to the `log_groups` field of the matching object in the `Accounts` value, which Step 5 explains. The Bedrock collector does not discover this log group on its own, so it reads only the log groups you list.

If the API Gateway collector is also on, list the API Gateway log groups in the same `log_groups` field as well.

### AgentCore

Use this section if you turn on the AgentCore collector. It needs the least setup on your side, because the agent finds its own log groups. All it needs is for AgentCore to produce observability data.

Turn on AgentCore observability by following the [AWS documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html#observability-configure-builtin). The agent discovers all AgentCore log groups on its own, so you do not list any.

***

## Step 2: Configure AWS credentials (CLI deployments)

If you deploy from the console, skip to Step 3. The console uses the account and region you are signed into.

For the CLI, the commands below set up the credentials that every `aws` command uses. They also decide the region the stack deploys into.

```
aws configure
```

This prompts for your AWS access key ID, secret access key, default region name, and default output format (use `json`), then stores them for later commands.

If you use named profiles, tell the CLI which one to use:

```
export AWS_PROFILE=<profile-name>
```

This sets the profile for your current shell session. The profile must hold the credentials you use to deploy the Harness resources.

Then check the region:

```
aws configure get region
```

The command prints the default region. It should match the region where you want to install the agent, because a mismatch creates the stack somewhere you did not intend.

If you prefer environment variables, set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` (or `AWS_DEFAULT_REGION`), and `AWS_DEFAULT_OUTPUT` instead.

***

## Step 3: Create a cross-account IAM role (multiple accounts only)

Skip this step if every API gateway you want to monitor lives in the same account as the agent.

To collect from another account, the agent needs permission to read that account's logs. It gets that permission by assuming an IAM role that you create in the monitored account. You create one role per monitored account, with the `cross_account_iam_role` CloudFormation template.

The template takes one parameter, `AccountId`. It is the ID of the AWS account that assumes the role, which is the **host account**, the account where the agent runs.

The template creates:

* A role named `traceable-cross-account-role`. Its trust policy lets the account you named in `AccountId` assume the role.
* A policy named `traceable-cross-account-policy`, attached to the role. It grants `logs:DescribeLogGroups`, `logs:FilterLogEvents`, and `apigateway:GET` on all resources in the account. These are read-only permissions.
* An output named `TraceableRoleArn`, which returns the role's ARN.

Copy the `TraceableRoleArn` value after the stack finishes. You enter it as `cross_account_role_arn` when you build the `Accounts` value in Step 5.

{% hint style="info" %}
**Note**: The trust policy names the whole account (`:root`), so any identity in that account with `sts:AssumeRole` permission can assume this role. If your security team wants a narrower trust, restrict the principal in the template before you deploy it.
{% endhint %}

***

## Step 4: Download the template

The CloudFormation template ships in an archive named `aws-cloudwatch.tar.gz`. Open the Downloads site at the path below, which always holds the current release, and download the archive from there:

```
https://downloads.traceable.ai/#install/aws-cloudwatch/cloudformation/latest/
```

Then extract it:

```
tar xvzf aws-cloudwatch.tar.gz
```

`tar xvzf` unpacks the gzip archive and lists each file as it goes, so you can see the template file you need for Step 6.

***

## Step 5: Build the Accounts value

The `Accounts` parameter tells the agent which accounts and regions to read. It is a comma-separated list of base64-encoded JSON objects, one object per account and region pair. The base64 encoding keeps the JSON intact when CloudFormation passes it around as a plain string.

Start with one JSON object for each account and region:

```json
{
  "region": "us-east-1",
  "api_list": ["<api-id>/<stage-name>"],
  "cross_account_role_arn": "",
  "exclude": false
}
```

The following table describes each key you can set inside the object.

| Key                      | Required | What It Does                                                                                                                                                                                                                            |
| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region`                 | Yes      | The AWS region to collect from.                                                                                                                                                                                                         |
| `api_list`               | Yes      | A list of API IDs. To target one stage, write `<api_id>/<stage_name>`.                                                                                                                                                                  |
| `exclude`                | Yes      | Decides how the agent treats the `api_list` entries. It applies to the API Gateway collector only. Set it to `false` to collect only the listed APIs. Set it to `true` to collect everything except the listed APIs.                    |
| `cross_account_role_arn` | Yes      | The role ARN from Step 3. Use an empty string when the APIs are in the same account as the agent.                                                                                                                                       |
| `log_groups`             | No       | A list of log group names to read directly. For the Bedrock collector, list the model-invocation log group here. If the API Gateway collector is also on and you list log groups for Bedrock, list the API Gateway log groups here too. |
| `access_log_format`      | No       | A map that describes the access log format your API Gateway instances use. It is required when you set `log_groups`.                                                                                                                    |

{% hint style="info" %}
**Note**: The AgentCore collector uses only `region` and `cross_account_role_arn` from each object, and it discovers its own log groups.
{% endhint %}

Then encode each object. On macOS or Linux, run this for each one, with the JSON on a single line:

```
echo -n '<json-object>' | base64 | tr -d '\n'
```

`echo -n` prints the JSON without a trailing newline, so the newline does not end up inside the encoded value. `base64` encodes it, and `tr -d '\n'` removes the line breaks that some versions of `base64` add to long output. Join the results with commas to get the final `Accounts` value.

If you prefer not to encode the objects, use `AccountsStringTyped` instead. It takes the same JSON objects as plain text separated by semicolons. Provide either `Accounts` or `AccountsStringTyped`, not both.

***

## Step 6: Deploy the stack

You can create the stack from the AWS console or with the AWS CLI. Both give the same result, so pick the one that fits how you work. The console walks you through each choice on screen, and the CLI suits repeatable or scripted deployments.

### Option 1: Deploy from the AWS console

Use this option if you prefer to fill in the parameters on screen and watch the stack build in the browser.

1. In the AWS console, search for **CloudFormation** and open it.
2. Click **Create Stack**.
3. Under **Prerequisite - Prepare template**, select **Choose an existing template**.
4. Under **Specify template**, select **Upload a template file**, and upload the template from Step 4.
5. Enter a stack name, and fill in the parameters. Set at least one of `EnableApiGatewayCollector`, `EnableBedrockCollector`, and `EnableAgentCoreCollector` to `true`. The [parameter tables](#parameters-reference) below explain the rest.
6. Add tags and choose your rollback options.
7. Review the settings and create the stack.
8. Wait for the stack to reach a successful state.

The **Prerequisite** and **Specify template** choices tell CloudFormation that you are using a template you already have. Enter your own values on the parameters page, because the defaults are placeholders.

### Option 2: Deploy with the AWS CLI

Use this option if you want to save your settings to a file and repeat the deployment without going through the console. You write the parameters once, then create the stack with a single command.

1. Create a parameters file, for example `parameters.json`. Each entry is a key and a value, and every value is a string:

```json
[
  { "ParameterKey": "DeploymentMode", "ParameterValue": "ecs" },
  { "ParameterKey": "SubnetId", "ParameterValue": "<subnet-id>" },
  { "ParameterKey": "ClusterArn", "ParameterValue": "<ecs-cluster-arn>" },
  { "ParameterKey": "AgentImage", "ParameterValue": "traceableai/awscloudwatch:latest" },
  { "ParameterKey": "TraceableAgentEndpoint", "ParameterValue": "<tpa-endpoint>" },
  { "ParameterKey": "Accounts", "ParameterValue": "<base64-account-objects>" },
  { "ParameterKey": "EnableApiGatewayCollector", "ParameterValue": "true" },
  { "ParameterKey": "EnableBedrockCollector", "ParameterValue": "false" },
  { "ParameterKey": "EnableAgentCoreCollector", "ParameterValue": "false" }
]
```

This example is for `ecs` mode. For `ec2` mode, drop `ClusterArn` and `AgentImage`, set `DeploymentMode` to `ec2`, and add `KeyName` if you want SSH access.

2. Create the stack:

```
aws cloudformation create-stack \
  --stack-name <stack-name> \
  --template-body file://<path/to/template> \
  --parameters file://<path/to/parameters.json> \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM
```

Here is what each option does:

* `--stack-name` names the stack. You use this name again when you delete it.
* `--template-body` points at the template file you downloaded.
* `--parameters` points at the parameters file you wrote a moment ago.
* `--capabilities` acknowledges that the stack creates IAM roles and policies. CloudFormation refuses to create IAM resources until you grant this permission, as a safeguard against unexpected changes.

3. Check progress in the **CloudFormation** console, or run `aws cloudformation describe-stacks --stack-name <stack-name>` and look at `StackStatus`.

***

## Parameters reference

The template has many parameters, but you only set the ones that apply to your deployment. The parameters are grouped by when you need them: the collector switches, the parameters that apply in both modes, and the ones specific to `ecs` or `ec2`, and the ones that send credentials to a hosted TPA. Start with the collector parameters, then use the groups that match your mode.

### Collector parameters

These three parameters decide which collectors run, so you always set at least one of them. The following table lists each parameter with its default.

| Parameter                   | Default | What It Does                        |
| --------------------------- | ------- | ----------------------------------- |
| `EnableApiGatewayCollector` | `false` | Turns on the API Gateway collector. |
| `EnableBedrockCollector`    | `false` | Turns on the Bedrock collector.     |
| `EnableAgentCoreCollector`  | `false` | Turns on the AgentCore collector.   |

### Parameters for both modes

These parameters apply to whichever mode you choose. The following table lists each one, along with its default and the reasons you might change it.

| Parameter                           | Required          | Default                 | What It Does and Why You Might Change It                                                                                   |
| ----------------------------------- | ----------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `DeploymentMode`                    | No                | `ec2`                   | Where the agent runs: `ec2` or `ecs`. Set it to `ecs` to run the agent as ECS tasks.                                       |
| `SubnetId`                          | Yes               | `""`                    | The subnet where the agent runs. Choose one that can reach your TPA endpoint and the AWS APIs.                             |
| `Accounts` or `AccountsStringTyped` | Yes (one of them) | None                    | The accounts and regions to collect from. See Step 5.                                                                      |
| `TraceableAgentEndpoint`            | No                | `http://localhost:5442` | Where the agent sends data. Change it when your TPA runs somewhere else.                                                   |
| `TraceableAgentMaxBatchSize`        | No                | `5`                     | The maximum number of spans in one request to the TPA. Lower it if requests to your TPA time out.                          |
| `TraceableServiceName`              | No                | `aws-cloudwatch`        | The service name Harness shows. It applies to the API Gateway and Bedrock collectors only.                                 |
| `CronIntervalMins`                  | No                | `5`                     | How often the agent runs, in minutes.                                                                                      |
| `AssignPublicIp`                    | No                | `false`                 | Assigns a public IP address to the agent so that it can reach the internet. Turn it on when the subnet has no NAT gateway. |
| `Tags`                              | No                | `{}`                    | Tags to add to the resources the stack creates.                                                                            |

### Parameters for ecs mode

Use these parameters only when `DeploymentMode` is `ecs`. They describe the cluster and the task the agent runs. The following table lists each one.

| Parameter            | Required | Default                            | What It Does and Why You Might Change It                                                                        |
| -------------------- | -------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `ClusterArn`         | Yes      | None                               | The ARN of the ECS Fargate cluster that runs the tasks.                                                         |
| `AgentImage`         | Yes      | `traceableai/awscloudwatch:latest` | The container image that ECS runs for each task. Change it only if you mirror the image into your own registry. |
| `TaskCpu`            | No       | `1024`                             | CPU for each task, in millicores.                                                                               |
| `TaskMemory`         | No       | `2048`                             | Memory for each task, in MB.                                                                                    |
| `EnableLogging`      | No       | `false`                            | Saves the task logs to CloudWatch. Turn it on while you troubleshoot.                                           |
| `AllowImagesFromEcr` | No       | `true`                             | Lets the task's IAM role pull images from Amazon ECR.                                                           |

### Parameters for ec2 mode

Use these parameters only when `DeploymentMode` is `ec2`. They control the instance, its storage, and where the agent installs. The following table lists each one.

| Parameter         | Required | Default                                                                 | What It Does and Why You Might Change It                                                             |
| ----------------- | -------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `KeyName`         | No       | `""`                                                                    | The key pair for the instance. Set it if you need SSH access to troubleshoot.                        |
| `InstanceType`    | No       | `m4.xlarge`                                                             | The EC2 instance type. Pick a larger type if you collect heavy traffic.                              |
| `RootDirectory`   | No       | `/var/traceable/aws-cloudwatch`                                         | Where the agent is installed on the instance.                                                        |
| `LogDirectory`    | No       | `/var/traceable/log/aws-cloudwatch`                                     | Where the agent writes its logs. You look here when you troubleshoot.                                |
| `AmiNameSsm`      | No       | `/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64` | The SSM parameter that holds the AMI ID. The default resolves to the latest Amazon Linux 2023 image. |
| `KmsKeyID`        | No       | `alias/aws/ebs`                                                         | The KMS key that encrypts the EBS volume. Supply the ARN of your own key if policy requires it.      |
| `EBSVolumeSize`   | No       | `50`                                                                    | The EBS volume size, in GB.                                                                          |
| `EBSVolumeType`   | No       | `gp2`                                                                   | The type of EBS volume, for example `gp2`.                                                           |
| `EBSEncryption`   | No       | `true`                                                                  | Turns on encryption for the EBS volume.                                                              |
| `BlockDeviceType` | No       | `/dev/sdb`                                                              | The device name that the EBS volume uses when it attaches to the instance.                           |

### Parameters that send credentials to a hosted TPA

Set these only if your agent sends data to a Harness-hosted (SaaS) TPA. The TPA uses them to identify your environment and authenticate the agent. The following table lists the three parameters and the request header each one becomes.

| Parameter              | Default | What It Does                                                  |
| ---------------------- | ------- | ------------------------------------------------------------- |
| `TraceableEnvironment` | None    | Sent to the TPA as the `traceableai-environment-name` header. |
| `TraceableToken`       | None    | Sent to the TPA as the `traceableai-agent-token` header.      |
| `TraceableGuid`        | None    | Sent to the TPA as the `x-traceable-guid` header.             |

The agent leaves out any header whose value is empty. You need these three only when `TraceableAgentEndpoint` points to a Harness-hosted (SaaS) TPA. For a self-hosted TPA, leave them empty.

***

## Verify the deployment

When the stack reaches a successful state, give the agent one run interval (5 minutes by default), then check Harness for your traffic:

* Go to **Insights** → **Explore Data** to view the traces and spans directly.
* Go to **Discovery** → **Inventory** to view the services and endpoints the agent discovered.

API Gateway and Bedrock traffic appear under the service name you set in `TraceableServiceName`, which is `aws-cloudwatch` by default. AgentCore traffic appears under the name of the AgentCore resource.

If the stack fails, or no data arrives, go through [Troubleshooting the AWS CloudWatch agent](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-discovery-discovery/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview/troubleshooting-the-aws-cloudwatch-agent.md).

***

## Uninstall the stack

Deleting the stack removes all Harness resources it created.

To delete it from the console, open **CloudFormation**, select the stack, and click **Delete**.

To delete it with the AWS CLI, run:

```
aws cloudformation delete-stack --stack-name <name of stack>
```

Replace `<name of stack>` with the name you gave the stack in Step 6. The command asks CloudFormation to remove the stack and all its resources, then returns immediately while the deletion continues in the background.

For more information, see [AWS CloudWatch agent overview](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-discovery-discovery/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview.md) and [Configure the AgentCore collector](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-discovery-discovery/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview/configure-the-agentcore-collector.md).
