Grapes
Warning This project is an experiment in AI-assisted development. The code was generated without human review and should not be trusted for production use. That said, Grapes is read-only and makes no modifications to your AWS resources, so there's no harm in trying it!
A single-pane TUI (Text User Interface) for monitoring AWS ECS cluster health. Built with Python and Textual.
Features
- Cluster Selection: View all accessible ECS clusters and select one to monitor
- Real-time Monitoring: View cluster, service, task, and container status at a glance
- Health Indicators: Visual health status (✓ Healthy, ⚠ Warning, ✗ Unhealthy, ? Unknown)
- Container Metrics: CPU and memory utilization from CloudWatch Container Insights
- Deployment Tracking: See all deployments (PRIMARY, ACTIVE, etc.) with task definition versions
- AWS Console Integration: One-key access to open resources in AWS Console
- Keyboard Navigation: Fast, keyboard-driven interface
- Dark Mode: Easy on the eyes for extended monitoring sessions
Requirements
- Python 3.11+
- AWS credentials configured (via environment, ~/.aws/credentials, or IAM role)
- CloudWatch Container Insights enabled (optional, for CPU/memory metrics)
Installation
Install from PyPI:
pip install grapes-ecs
Or using uv:
uv tool install grapes-ecs
Then run:
grapes
Development Installation
# Clone the repository
git clone <repository-url>
cd grapes
# Install dependencies
uv sync
# Run the application
uv run grapes
Configuration
Create a config.toml file in your current directory or at ~/.config/grapes/config.toml:
[cluster]
name = "my-ecs-cluster" # Optional: ECS cluster name (if omitted, select from list)
region = "us-east-1" # Required: AWS region
profile = "default" # Optional: AWS profile name
[refresh]
interval = 30 # Optional: API poll interval in seconds (default: 30)
task_definition_interval = 300 # Optional: Task def cache TTL in seconds (default: 300)
If you omit the name field, Grapes will show a list of all clusters in the region, and you can select one to view.
Run with a specific config file:
grapes -c /path/to/config.toml
Keyboard Shortcuts
| Key | Action |
|---|---|
| ↓/↑ | Navigate list |
| Enter | Select cluster / View service details |
| Esc | Go back (cluster list / service list) |
| O | Open in AWS Console |
| R | Force refresh data |
| D | Toggle debug console |
| Q | Quit |
Required IAM Permissions
The following IAM permissions are required:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecs:ListClusters",
"ecs:DescribeClusters",
"ecs:ListServices",
"ecs:DescribeServices",
"ecs:ListTasks",
"ecs:DescribeTasks",
"ecs:DescribeTaskDefinition"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"cloudwatch:GetMetricData",
"cloudwatch:GetMetricStatistics"
],
"Resource": "*"
}
]
}
Enabling Container Insights
For CPU and memory metrics, enable Container Insights on your cluster:
aws ecs update-cluster-settings \
--cluster my-cluster \
--settings name=containerInsights,value=enabled \
--region us-east-1
If Container Insights is not enabled, Grapes will display a warning and show - for metrics.
Health Status
Grapes determines health based on ECS container health checks:
- ✓ Healthy: All containers report healthy
- ⚠ Warning: Some containers unhealthy or desired != running count
- ✗ Unhealthy: All containers unhealthy or no running tasks
- ? Unknown: Health checks not configured
No fallback logic is used - only actual container health check results are displayed.
Metrics Display
When Container Insights is enabled:
- CPU: Displayed as
usage% / limit_units(e.g.,12% / 512) - Memory: Displayed as
usedM / limitM(e.g.,256M / 1024M)
Metrics are fetched from CloudWatch and may have 1-2 minutes of lag. Missing or stale metrics are always shown as -.
Development
# Install dev dependencies
uv sync
# Run linting
uv run ruff check .
# Run tests
uv run pytest
License
MIT
Metadata
Release files for grapes-ecs 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| grapes_ecs-0.2.0.tar.gz | 77.0 kB | Without provenance | Details for grapes_ecs-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| grapes_ecs-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for grapes_ecs-0.2.0-py3-none-any.whl |
Total release size: 123.1 kB
Release files / grapes_ecs-0.2.0.tar.gz
| Download URL | grapes_ecs-0.2.0.tar.gz |
|---|---|
| Size | 77.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
690ec71857c667ff68e0b818197950cb0681aacad980db6dcb39ca3cffa9cfe4
|
|
BLAKE2b-256 checksum How to use checksums |
b17b0d738a6c1ed056d767fa9bb28de40426b63da5b937e8d241078828cf1851
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / grapes_ecs-0.2.0-py3-none-any.whl
| Download URL | grapes_ecs-0.2.0-py3-none-any.whl |
|---|---|
| Size | 46.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7227925654ed498dfe4a0769c62fc0e41358abe19b660128fac3d70a1b4f2942
|
|
BLAKE2b-256 checksum How to use checksums |
d39b70f046ad8162879205706870a02b07f9825d88c20014ce221dbb1cf78c75
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Security for grapes-ecs 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.