# Alloy CloudWatch

LLMS index: [llms.txt](/llms.txt) | Full content: [llms-full.txt](/llms-full.txt)

---

An AWS CloudFormation/SAM stack that provisions a read-only IAM user for
Grafana Alloy's `prometheus.exporter.cloudwatch` component. Grants access
to CloudWatch Metrics APIs so selected AWS service metrics (Lambda, SQS,
SNS, DynamoDB) can be ingested into Mimir for alerting.

## Features

- **Read-Only IAM User**: Dedicated user for Alloy CloudWatch metrics exporter
- **CloudWatch Metrics**: `GetMetricData`, `GetMetricStatistics`, `ListMetrics`
- **Resource Discovery**: `tag:GetResources` for filtering by `app-code=RPRM-001`
- **Account Discovery**: `sts:GetCallerIdentity` and `ec2:DescribeRegions` for YACE auto-discovery

## Architecture

Single SAM template that creates:

1. **IAM User** - Read-only service account (`${ResourcePrefix}-user`)
2. **IAM Policy** - CloudWatch Metrics read, tag and region discovery, STS caller identity

The user's access keys are created manually after deployment and stored
in Vault. The companion [infrastructure repo][infra-repo] injects the
credentials into the Alloy Hub pod on MPP via a Kubernetes Secret.

```mermaid
flowchart LR
  subgraph aws [AWS]
    iam["IAM User\n(read-only)"]
    cwMetrics["CloudWatch Metrics"]
  end
  subgraph mpp [MPP Hub]
    alloy["Alloy Hub"]
    mimir["Mimir"]
  end
  alloy -->|"GetMetricData"| cwMetrics
  alloy -->|"remote_write"| mimir
  alloy -.->|"credentials from Vault"| iam
```

## IAM Permissions

All permissions are read-only with `Resource: "*"` (CloudWatch does not
support resource-level restrictions for most read operations).

| Category | Actions |
| -------- | ------- |
| Metrics | `GetMetricData`, `GetMetricStatistics`, `ListMetrics` |
| Discovery | `ec2:DescribeRegions`, `tag:GetResources`, `sts:GetCallerIdentity` |

## Prerequisites

- AWS CLI configured with appropriate credentials (IAM permissions for
  CloudFormation)
- Podman or Docker (for containerized SAM build/deploy)

## Deployment

Build and deploy using containerized AWS SAM CLI:

```bash
cd alloy-cloudwatch
sam deploy --guided   # First deployment
sam deploy            # Subsequent deployments
```

After deployment, create an access key for the IAM user and store it in
Vault using `cki_tools.credentials.manager`.

## Related

- **Alloy Hub deployment**: `kubernetes/alloy-hub/` in the [infrastructure repo][infra-repo]
- **Monitoring documentation**: `documentation/monitoring.md` in the [infrastructure repo][infra-repo]

## License

This project is licensed under the GNU General Public License v3.0 or later -
see the [LICENSE][license] file for details.

[infra-repo]: https://gitlab.com/redhat/hummingbird/infrastructure
[license]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/LICENSE