> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/integrations/data-sources/aws/monitor-vpc-rds-dynamodb.md).

# Monitor VPC, RDS & DynamoDB

groundcover supports monitoring AWS VPC subnets, RDS instances, and DynamoDB tables through a single consolidated `aws` data integration. Instead of configuring one integration per signal, you configure the AWS account, region(s), role, and scrape interval once, and enable one capability block per signal: `vpc`, `dynamodb`, and `rds`. Every enabled capability inherits the same region/role/interval settings — there's no per-capability override. If you need to cover a different account, region, or role for a given capability, create a second `aws` integration.

## What each capability collects

* **`vpc`** - subnet IPv4 capacity (available and total addresses) via `DescribeSubnets`.
* **`dynamodb`** - per-table item count and size via `DescribeTable`.
* **`rds`** - instance-level gauges via `DescribeDBInstances`, plus OS-level metrics (CPU, memory, swap, tasks) from RDS Enhanced Monitoring, read from the `RDSOSMetrics` CloudWatch Logs group.

{% hint style="warning" %}
Enabling `rds` only surfaces Enhanced Monitoring data for instances that already have it turned on. Enhanced Monitoring involves two separate roles: an **RDS monitoring role**, trusted by `monitoring.rds.amazonaws.com`, that RDS itself assumes to publish OS metrics to the `RDSOSMetrics` CloudWatch Logs group; and groundcover's own `roleArn` above, used only to read that already-published log group. Turn Enhanced Monitoring on via the RDS console (**Modify** → **Additional configuration** → **Enable Enhanced Monitoring**) or the AWS CLI (`--monitoring-interval` set to a non-zero value **and** `--monitoring-role-arn` set to the RDS monitoring role) - groundcover doesn't create or assume that role, it only reads the stream once AWS is already producing it.
{% endhint %}

## Setting it up

### In the app

Navigate to [Data Sources](https://app.groundcover.com/settings/integrations/data-sources) and select **AWS Enhanced**, then follow the wizard:

1. **Configuration** - grant groundcover the required permissions (same IAM role setup as [Ingest CloudWatch Metrics](/integrations/data-sources/aws/ingest-cloudwatch-metrics.md#create-an-iam-role-and-policy)) and provide the Role ARN.
2. **Regions selection** - pick the AWS regions to collect from; enabled services are discovered across every selected region.
3. **Services to monitor** - turn on `VPC`, `DynamoDB`, and/or `Enhanced RDS`, whichever you run. Each service can optionally be narrowed to specific resources (subnet IDs, table names, or DB instance identifiers) - leave the list empty to monitor everything the role can see. At least one service must be enabled.
4. **Ingestion settings** - set the scrape interval and any custom labels.

### Via Terraform or the API

Configure it using the `groundcover_dataintegration` resource with `type = "aws"`:

```hcl
resource "groundcover_dataintegration" "aws_example" {
  type = "aws"
  config = jsonencode({
    version        = 1
    name           = "prod-aws"
    enabled        = true
    regions        = ["us-east-1", "eu-west-1"]
    roleArn        = "arn:aws:iam::123456789012:role/groundcover"
    stsRegion      = "us-east-1"
    scrapeInterval = "5m"

    vpc = {
      enabled   = true
      subnetIds = [] # empty means every subnet in each configured region
    }
    dynamodb = {
      enabled    = true
      tableNames = [] # empty means every table in each configured region
    }
    rds = {
      enabled               = true
      dbInstanceIdentifiers = [] # empty means every instance in each configured region
    }
  })
}
```

For the full configuration reference, validation rules, and emitted metrics/labels, see the [`groundcover_dataintegration` resource docs](https://registry.terraform.io/providers/groundcover-com/groundcover/latest/docs/resources/dataintegration#aws-integration-reference-type-aws) on the Terraform Registry.

## Required IAM permissions

The role referenced by `roleArn` needs the permissions below in addition to the standard cross-account trust relationship.

{% hint style="info" %}
groundcover assumes `roleArn` using the same identity used by other AWS integrations. Follow the trust policy steps in [Ingest CloudWatch Metrics](/integrations/data-sources/aws/ingest-cloudwatch-metrics.md#create-an-iam-role-and-policy) to set up that side - the permissions below just need to be attached to that role.
{% endhint %}

{% hint style="info" %}
If you omit `roleArn` for same-account access, there's no role to assume - the integration calls these APIs using the credentials already available to the collector (for example its instance profile or IRSA role). In that case, attach the permissions below directly to the collector's own AWS execution role instead, and skip the trust policy step above.
{% endhint %}

### Shared / identity permissions

Required regardless of which capabilities are enabled.

| Permission               | Resource / Scope | Purpose                                               |
| ------------------------ | ---------------- | ----------------------------------------------------- |
| `sts:GetCallerIdentity`  | `*`              | Resolve the account ID for labeling (best-effort).    |
| `iam:ListAccountAliases` | `*`              | Resolve the account alias for labeling (best-effort). |

{% hint style="info" %}
`sts:AssumeRole` on the `roleArn` is granted via the role's **trust policy**, not this permissions policy - it belongs on groundcover's own role in the collector account, targeting your role's ARN, not something your role needs to grant itself.
{% endhint %}

### `vpc` capability

| Permission            | Notes                                        |
| --------------------- | -------------------------------------------- |
| `ec2:DescribeSubnets` | Paginated; optionally filtered by subnet ID. |

### `rds` capability

| Permission                | Notes                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------ |
| `rds:DescribeDBInstances` | Paginated; optionally filtered by DB instance ID.                                                |
| `logs:GetLogEvents`       | Scoped to the `RDSOSMetrics` log group - needed for Enhanced Monitoring OS metrics per instance. |

### `dynamodb` capability

| Permission               | Notes                                                                 |
| ------------------------ | --------------------------------------------------------------------- |
| `dynamodb:ListTables`    | Only called when no table names are configured (auto-discovery mode). |
| `dynamodb:DescribeTable` | Called per table - either discovered or explicitly configured.        |

### Suggested minimal IAM policy

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GroundcoverIdentity",
      "Effect": "Allow",
      "Action": [
        "sts:GetCallerIdentity",
        "iam:ListAccountAliases"
      ],
      "Resource": "*"
    },
    {
      "Sid": "GroundcoverVpc",
      "Effect": "Allow",
      "Action": ["ec2:DescribeSubnets"],
      "Resource": "*"
    },
    {
      "Sid": "GroundcoverRds",
      "Effect": "Allow",
      "Action": ["rds:DescribeDBInstances"],
      "Resource": "*"
    },
    {
      "Sid": "GroundcoverRdsEnhancedMonitoring",
      "Effect": "Allow",
      "Action": ["logs:GetLogEvents"],
      "Resource": "arn:aws:logs:*:*:log-group:RDSOSMetrics:*"
    },
    {
      "Sid": "GroundcoverDynamoDb",
      "Effect": "Allow",
      "Action": [
        "dynamodb:ListTables",
        "dynamodb:DescribeTable"
      ],
      "Resource": "*"
    }
  ]
}
```

`rds:DescribeDBInstances` and `ec2:DescribeSubnets` don't support resource-level restriction and must use `Resource: "*"`. `logs:GetLogEvents` can be scoped to the `RDSOSMetrics` log group as shown above. If you'd rather restrict DynamoDB access to specific tables instead of allowing discovery, scope the `dynamodb:*` actions to those tables' ARNs and set `dynamodb.tableNames` in the integration config accordingly - just omit `dynamodb:ListTables` in that case, since discovery won't be used.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.groundcover.com/integrations/data-sources/aws/monitor-vpc-rds-dynamodb.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.