Monitor VPC, RDS & DynamoDB

Monitor AWS VPC subnets, RDS instances, and DynamoDB tables with a single consolidated integration.

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.

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.

Setting it up

In the app

Navigate to 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) 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":

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 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.

groundcover assumes roleArn using the same identity used by other AWS integrations. Follow the trust policy steps in Ingest CloudWatch Metrics to set up that side - the permissions below just need to be attached to that role.

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.

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).

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.

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

{
  "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.