# AWS

> Connect AWS so Ace can read CloudWatch, CloudTrail, X-Ray and your infrastructure during investigations, open incidents from CloudWatch alarms, scan for savings and, if you allow it, make approved changes.

Source: https://tryace.dev/docs/integrations/aws

Ace reads AWS to see what is failing, what changed and how your services connect. A guided setup uses CloudFormation to create a read-only IAM role in your account or organization, and write access comes from a separate, optional role so you can grant it later or never.

| | |
| --- | --- |
| Category | Infrastructure, telemetry and change context |
| Ace reads | CloudWatch metrics, alarms and logs, CloudTrail event history, AWS Config history, AWS Health, X-Ray traces, infrastructure metadata, cost recommendations |
| Ace can change | Nothing with the read role. With the optional actions role, the AWS services you choose, after approval |
| Opens incidents | Yes, from CloudWatch alarms |
| Setup | Guided setup in Ace that creates a role in your AWS account |

## What Ace reads

During an investigation, Ace reads:

- CloudWatch metric data for the incident window, alarm state and history, and error logs through CloudWatch Logs Insights.
- Mutating API calls from your existing 90-day CloudTrail event history. Ace never creates a trail or CloudTrail Lake.
- Auto Scaling activity, AWS Config resource history and AWS Health events. Health events need an AWS Support plan that includes the AWS Health API, and without one Ace skips them.
- The X-Ray service graph and a bounded sample of traces from the incident window.
- RDS Performance Insights load by tokenized SQL and wait events, and Application Signals SLO budgets.
- Infrastructure metadata for the System Map: networking, compute, databases, queues, storage metadata, tags, quotas and declared relationships.

The read role explicitly denies customer data, so it can't read S3 objects, DynamoDB rows, SQS messages, secrets, parameter values, source packages or CloudFormation templates, and it can't decrypt anything or read full SQL text. Ace also strips environment values, inline credentials and secret-bearing command arguments from AWS responses before it stores or shows them.

Once the **Cost & performance** panel shows **Verified**, Ace scans daily for savings in Cost Optimization Hub and Compute Optimizer and reads Cost Explorer anomalies. Because Cost Explorer bills per request, Ace makes only one anomaly request per daily scan.

## What Ace can change

The read role can't create, update or delete any AWS resource. To let Ace make changes, add the separate actions role with at least one of these groups:

| Group | Services |
| --- | --- |
| Compute | ECS, Auto Scaling, EC2, Lambda, EKS |
| Data | RDS, DynamoDB, ElastiCache, SQS, Kinesis |
| Network and edge | Load balancers, Route 53, CloudFront, WAF |
| Deployments | CodeDeploy, CloudFormation, AppConfig |
| Runbooks | SSM documents you allow |
| Alarm muting | Mute a CloudWatch alarm during a fix |

A change has to clear three checks:

1. The role has permissions only for the groups you chose.
2. Ace proposes changes only on the AWS resources you confirm in each workload's settings. It checks that list again before each write.
3. A person approves the exact plan, and Ace reads the resource state again before it writes.

AWS changes need approval unless an admin sets that action to **Automatic** in **Settings** > **Actions** and turns on **Run despite preflight cautions**, which is how Earned autonomy extends to AWS. Some operations always need a person whatever the policy, including stopping an EC2 instance, changing an instance type, RDS instance class or DynamoDB capacity mode, and running an SSM document.

Many operations, such as scaling, rollbacks and alarm muting, have an **Undo**. Others, such as a reboot or a forced ECS deployment, can't be undone.

Alarm muting runs on its own. When an approved fix starts, Ace mutes the incident's firing CloudWatch alarms on the workload's confirmed resources so on-call isn't paged during the rollout. It mutes an alarm only if every one of its actions is an SNS notification, which means an alarm that also triggers Auto Scaling, EC2, Systems Manager or Lambda actions stays as it is. Ace restores each mute after the fix rolls out or the incident resolves, and anyone can undo a mute from the incident.

Review the compute and data groups carefully before you turn them on. Compute lets Ace register task definitions and pass roles, so it can reach as far as the most powerful role in the account that ECS can use, and data can change your data stores. See [Actions and approvals](https://tryace.dev/docs/concepts/actions-and-approvals).

## What opens an incident

Ace polls CloudWatch alarm history with the read role, so you don't need SNS or a webhook.

- An alarm that moves to `ALARM` opens an incident or joins an open one.
- The incident resolves when the alarm returns to `OK`, or moves to `INSUFFICIENT_DATA` after `ALARM`.
- When a composite alarm fires, Ace follows the composite and ignores the alarms it covers.

An alarm opens an incident only for a workload that routes AWS. To route it, open the workload's settings, turn on **Integration alerts** under **Investigation triggers** and select AWS.

**Watch CloudWatch metrics** on the AWS page is a separate setting, off by default because its reads can add CloudWatch charges to your AWS bill. When an admin turns it on, Ace learns each metric's normal range and opens an incident when a deviation lasts. See [Proactive detection](https://tryace.dev/docs/concepts/proactive-detection).

## Before you start

- The **admin** role in Ace. See [Roles and permissions](https://tryace.dev/docs/security/roles-and-permissions).
- Permission in AWS to create CloudFormation stacks and IAM roles.
- To connect an AWS Organization:
  - Organizations must use all features.
  - A management account administrator must activate StackSets trusted access. In CloudFormation, open **StackSets** and choose **Activate trusted access**.
  - To launch from a delegated administrator account, first register it as a delegated administrator for CloudFormation StackSets.
  - Cost scans run from the account you launch from. To cover the whole organization, launch from the management account or the delegated administrator.
- For savings recommendations, enroll in Cost Optimization Hub and Compute Optimizer in the launch account. Cost anomalies, Performance Insights and SLOs work without enrollment.

## Credentials and permissions

Ace never stores AWS access keys. It assumes the roles the stack creates, using an external ID generated for your workspace, and you can review everything the stack adds in Ace and in the AWS console before you launch it.

| Role | Where it lives | What it allows | Why Ace needs it |
| --- | --- | --- | --- |
| Read role | Each connected account | Read-only access to network, compute, data metadata, application integration, observability, identity metadata, and cost and performance. An explicit deny blocks customer data | Investigations, the System Map, CloudWatch alarms and cost scans |
| Organization discovery role | The launch account, in organization mode only | Lists the organization's accounts and organizational units, and assumes the read role in member accounts | Finds member accounts so Ace can read them |
| Actions role | Only if you choose action groups | Permissions for the groups you choose. Keeps the read role's data deny | Approved changes and alarm muting |

The actions role has its own external ID, so adding or removing it never changes read access.

## Set up

### Connect the read role

1. In Ace, go to **Settings** > **Data sources** > **AWS**. Under **Configuration**, choose an **AWS topology**:
   - **AWS Organization (recommended)** covers the accounts you choose with one setup.
   - **Single AWS account** covers one account.
2. Choose a **Primary Region**.
3. For an organization, enter the **Root or OU IDs**. A root ID covers every account, and OU IDs cover only those OUs. Choose the **Launch account**, then confirm that StackSets trusted access is activated.
4. Optional: under **Actions (optional)**, choose the groups Ace may change. Leave them all off for read-only access, since you can add actions later.
5. Choose **Launch stack in AWS**, then review the stack in the AWS console and create it. In organization mode, the stack deploys the read role to every account in the chosen roots or OUs, including accounts added later.
6. When the stack completes, open its **Outputs** tab and copy **PrimaryRoleArn**. Paste it into **Organization discovery role ARN**, or **Member role ARN** for a single account, and choose **Connect**.

Ace validates the role, then discovers your infrastructure for the System Map.

### Add actions later

1. In **Settings** > **Data sources** > **AWS**, find **AWS actions**.
2. Under **Choose what Ace can change**, select the groups. In organization mode, also choose the **Organizational units that receive the role**.
3. Choose **Launch stack** and create it in the AWS console.
4. When the stack completes, choose **Verify and turn on**.
5. Confirm the AWS resources in each workload's settings.

### Turn on cost scans

1. Check the status in the **Cost & performance** panel.
2. If it shows **Not enrolled**, enroll in Cost Optimization Hub and Compute Optimizer. In an organization, enroll from the launch account and include member accounts.
3. Recommendations appear within a day, and then you can choose **Re-check**.

If the panel shows **Update available**, update the stack in the AWS console as Ace shows, then choose **Re-check**.

## Confirm it's working

- The AWS panel shows **Connected** with **AWS Organization · member accounts discovered automatically**, or **Standalone account** and your Regions.
- The role access and CloudTrail access checks pass. If one fails, fix the cause and choose **Re-validate**.
- The System Map fills in after discovery.
- The **Cost & performance** panel shows **Verified**.
- With actions on, **AWS actions** shows **On** with the account, verification time and groups. **Confirmed resources** lists each workload.

## Disconnect

To turn off actions only, choose **Turn off** in **AWS actions**. Ace stops making AWS changes and plans waiting for approval won't run. If you turn actions back on later, you confirm each workload's resources again, and the stack stays in your account until you delete it.

To disconnect AWS, choose **Disconnect** in **Settings** > **Data sources** > **AWS**. Ace stops reading AWS and cancels pending AWS plans, but it doesn't delete anything in AWS. To remove Ace's access, delete the Ace stacks in CloudFormation:

- The actions stack, if you launched one separately.
- The main Ace stack, from the account you launched it from. In organization mode, this also removes the read role from member accounts.

## Next steps

- [Actions and approvals](https://tryace.dev/docs/concepts/actions-and-approvals): approval, automatic policies and undo.
- [Proactive detection](https://tryace.dev/docs/concepts/proactive-detection): CloudWatch watches and early warnings.
- [Security and data](https://tryace.dev/docs/security/security-and-data): what Ace stores and how it is protected.