> 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/migrate-from-the-aws-api-gateway-agent.md).

# Migrate from the AWS API Gateway agent

The AWS CloudWatch agent is the successor to the AWS API Gateway agent. It is built on the same codebase and adds collectors for Amazon Bedrock and Amazon Bedrock AgentCore. You cannot upgrade the old agent to the new one. Instead, you install the AWS CloudWatch agent alongside the old agent, confirm that it receives your traffic, and then remove the old agent.

You do not have to move right away. The AWS API Gateway agent is deprecated and no longer receives new releases, but the versions you already run continue to work. When you want new capabilities or fixes, move to the new agent.

## What will you learn in this topic?

By the end of this topic, you will understand:

* The reasons to move, and the situations where you can wait.
* The differences between the two agents that affect your existing setup.
* The steps to move your configuration to the AWS CloudWatch agent.
* The way to check the new agent and remove the old one.

***

## Decide whether to move now

The following table lists common situations and tells you whether to move to the AWS CloudWatch agent now or wait.

| Your Situation                                                           | What to Do                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| You collect only API Gateway traffic and the current agent works for you | You can stay on the AWS API Gateway agent for now. It keeps working, but it will not get new releases.                                                                                                                                                      |
| You want to collect Amazon Bedrock or Amazon Bedrock AgentCore traffic   | Move to the AWS CloudWatch agent. Only the new agent has those collectors.                                                                                                                                                                                  |
| You need a fix or feature that ships after this change                   | Move to the AWS CloudWatch agent. New releases go to the new agent only.                                                                                                                                                                                    |
| You are setting up AWS collection for the first time                     | Skip this topic, and start with [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). |

```mermaid
flowchart TD
    A["Do you need the new agent?<br/>Bedrock, AgentCore, or new releases"] -- No --> B["Stay on AWS API Gateway agent<br/>Keeps working, no new releases"]
    A -- Yes --> C["Record your current settings"]
    C --> D["Install the AWS CloudWatch agent"]
    D --> E["Verify the new agent"]
    E --> F["Remove the AWS API Gateway agent"]
```

***

## Understand what changes

Most settings carry over, but some names and defaults change, and a single behavior change can prevent an install. Review the changes in this section before you start.

### Enable collectors

In the AWS CloudWatch agent, you configure collection for each service separately. The agent has three collectors, one each for API Gateway, Amazon Bedrock, and Amazon Bedrock AgentCore, and all three are disabled by default. Enable the collectors for the services you want to monitor. You must enable at least one. If none is enabled, the installation fails with the error "at least one collector must be enabled".

To continue collecting API Gateway traffic, as the AWS API Gateway agent did automatically, enable the API Gateway collector. The following table lists the settings for each installation method.

| Installation Method   | Setting                                   |
| --------------------- | ----------------------------------------- |
| Terraform             | `enable_api_gateway_collector = true`     |
| CloudFormation        | `EnableApiGatewayCollector` set to `true` |
| Manual install on EC2 | `--enable-api-gateway true`               |

### Names, paths, and defaults

Every name that included `aws-api-gateway` now includes `aws-cloudwatch`. That covers the module name, the service name, the install paths, the cron file, the container image, the S3 install prefix, the airgapped archive, the CloudFormation log group, and the Terraform default service name.

The following table compares the old and new value of each name, path, and default that changes.

| Item                        | AWS API Gateway Agent                                           | AWS CloudWatch Agent                                                    |
| --------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Default service name        | `aws-api-gateway`                                               | `aws-cloudwatch`                                                        |
| Root directory (EC2)        | `/var/traceable/aws-api-gateway`                                | `/var/traceable/aws-cloudwatch`                                         |
| Log directory (EC2)         | `/var/traceable/log/aws-api-gateway`                            | `/var/traceable/log/aws-cloudwatch`                                     |
| Agent image                 | `traceableai/awsapigw:<TEMPLATE_VERSION>`                       | `traceableai/awscloudwatch:latest`                                      |
| Terraform archive           | `aws-api-gateway-tf`                                            | `aws-cloudwatch-tf.tar.gz`                                              |
| Default AMI parameter (SSM) | `/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2` | `/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64` |
| Installation methods        | Terraform and CloudFormation                                    | Terraform, CloudFormation, and manual install on EC2                    |

{% hint style="info" %}
**Note**: Because the default service name changes, the new agent shows your traffic under `aws-cloudwatch` unless you set a service name yourself. To keep your history on the same service, set the service name to `aws-api-gateway` when you install the new agent. Use `traceable_service_name` in Terraform, `TraceableServiceName` in CloudFormation, or `--service-name` in the manual install.
{% endhint %}

### How the agent connects to a TPA

The old agent could install a TPA on the same VM when you left the endpoint at `http://localhost:5442`. The new agent does not install a TPA by default. To use it, set up a TPA by following the [TPA installation guide](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-discovery-discovery/installation/platform-agent.md), then point the new agent at the TPA's URL. The URL must be reachable from the agent. The same-VM option still exists in the new agent, but it is deprecated and will be removed in a future release.

Plan for this at cutover. Removing the old stack or module also removes the instance it created, and with it any TPA that ran on that instance. Set up your new TPA before you remove the old agent.

If you send data to a Harness-hosted (SaaS) TPA, the new agent also accepts three optional values: the environment, the agent token, and the GUID, and sends them to the TPA as request headers. For more information, see your [TPA installation](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-discovery-discovery/installation/platform-agent.md) topic.

### API Gateway logging setting

The old topics told you to set **CloudWatch Logs** to **Full Request and Response Logs** for REST APIs. The new topics use **Error and info logs**. Follow the "Prepare your AWS services" step in your new installation topic when you set up logging for the new agent.

### The exclude setting

The `exclude` setting in the `accounts` value works the same way as in the old agent and applies only to the API Gateway collector. Your existing values carry over unchanged.

***

## Before you begin

* Make sure that you have a record of your current settings: the accounts and regions, the service name, the TPA endpoint, the instance type or ECS cluster, and the cross-account role ARNs. Step 1 shows where each one goes.
* Make sure that you know your current deployment method, because the new agent supports the same ones.
* Make sure that you can deploy resources in the account that hosts the agent.
* Make sure that you have a TPA set up and that its URL is reachable from the new agent. The [TPA installation guide](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-discovery-discovery/installation/platform-agent.md) covers the setup.
* Make sure that you have read [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).

***

## Step 1: Record your current settings

Open your existing Terraform variables file, CloudFormation parameters, or installer command, and list what you use. Most settings keep their meaning in the new agent. The following table maps each setting you recorded to its name in Terraform and CloudFormation, so you can fill in the new configuration.

| Setting              | Terraform                                    | CloudFormation                               | Notes                                                                                                          |
| -------------------- | -------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Accounts and regions | `accounts`                                   | `Accounts`                                   | The format is the same, and `exclude` behaves as before.                                                       |
| Service name         | `traceable_service_name`                     | `TraceableServiceName`                       | The default changes from `aws-api-gateway` to `aws-cloudwatch`. See the note under Names, paths, and defaults. |
| TPA endpoint         | `traceable_agent_endpoint`                   | `TraceableAgentEndpoint`                     | The default is unchanged: `http://localhost:5442`.                                                             |
| Cross-account role   | `cross_account_role_arn` (inside `accounts`) | `cross_account_role_arn` (inside `Accounts`) | Reuse the role ARNs that you already have.                                                                     |
| Deployment mode      | `deployment_mode`                            | `DeploymentMode`                             | The accepted values are `ec2` and `ecs`, the same as in the old agent.                                         |

For every other setting, look up its name in the parameter reference of your new installation topic.

***

## Step 2: Install the AWS CloudWatch agent

Install the new agent with the method you already use:

* [Deployment using Terraform](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-terraform.md)
* [Deployment using CloudFormation](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)
* [Manual install on EC2](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-discovery-discovery/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview/manual-install-on-ec2.md)

Turn on the API Gateway collector, as described in [Enable collectors](#enable-collectors), and add the Bedrock or AgentCore collector if you want them. If you want to keep your history on the same service, set the service name to `aws-api-gateway` now, as described in [Names, paths, and defaults](#names-paths-and-defaults).

This is a fresh install, and it does not touch your existing agent. You can run the two agents side by side until you cut over. During that overlap, both agents read the same log groups, so you will see duplicate data in Harness. Keep the overlap as short as possible, and verify the new agent in Step 3 as soon as it starts.

***

## Step 3: Verify the new agent

Give the new agent one run interval (5 minutes by default), then check that your traffic appears in Harness under the service name you set:

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

While both agents run, expect to see each request twice.

If your traffic does not appear, 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).

***

## Step 4: Remove the AWS API Gateway agent

When you are satisfied with the new agent, remove the old one with the method you used to install it. Removing it ends the duplicate data from the overlap.

* Terraform: run `terraform destroy` from the directory where you ran `terraform init` for the old agent.
* CloudFormation: delete the old stack in the **CloudFormation** console, or run `aws cloudformation delete-stack --stack-name <name of stack>`.

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