# Grafana 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's CloudWatch datasource plugin. Grants access to CloudWatch Logs
and Metrics APIs so Lambda execution logs and AWS service metrics are
browsable directly in Grafana.

## Features

- **Read-Only IAM User**: Dedicated user for Grafana CloudWatch datasource
- **CloudWatch Logs**: Browse Lambda and AWS service log groups via Logs Insights
- **CloudWatch Metrics**: Browse metrics across all AWS namespaces (Lambda, SQS, SNS, DynamoDB, etc.)
- **Resource Discovery**: `tag:GetResources` and `ec2:DescribeRegions` for Grafana plugin autodiscovery

## Architecture

Single SAM template that creates:

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

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 Grafana pod on MPP via a Kubernetes Secret.

```mermaid
flowchart LR
  subgraph aws [AWS]
    iam["IAM User\n(read-only)"]
    cwLogs["CloudWatch Logs"]
    cwMetrics["CloudWatch Metrics"]
  end
  subgraph mpp [MPP Hub]
    grafana["Grafana\n(CloudWatch datasource)"]
  end
  grafana -->|"Logs Insights API"| cwLogs
  grafana -->|"Metrics API"| cwMetrics
  grafana -.->|"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 |
| -------- | ------- |
| Logs | `DescribeLogGroups`, `DescribeLogStreams`, `GetLogEvents`, `FilterLogEvents`, `StartQuery`, `StopQuery`, `GetQueryResults`, `DescribeQueries` |
| Metrics | `GetMetricData`, `GetMetricStatistics`, `ListMetrics`, `DescribeAlarms`, `DescribeAlarmsForMetric` |
| Discovery | `ec2:DescribeRegions`, `tag:GetResources` |

## 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 grafana-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

- **Grafana deployment**: `kubernetes/grafana/` in the [infrastructure repo][infra-repo]
- **CloudWatch datasource**: `grafana_data/datasource/` 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