Ingest CloudWatch Metrics

groundcover supports ingesting CloudWatch metrics directly into our platform, allowing you to visualize them using dashboards and create alerts.

How does it work

CloudWatch integration is done by deploying a service called integrations-agent which is responsible for pulling metrics from CloudWatch using periodic polling of these APIs:

The integration is setup using the following steps:

Create a role with permissions to access the metrics on the target AWS account
Provide the needed permissions to allow the integrations-agent service account to assume the new role
Select the AWS namespaces you wish to collect metrics from
Deploy the integrations-agent service and start collecting metrics

The actual steps differ for inCloud Managed and inCloud deployments. Follow the instructions below depending on your deployment type.

Things to know

Ingestion interval

The integration pulls data from CloudWatch every five minutes.

Data storage

Data fetched is stored in the Victoria Metrics database, meaning metrics are queried via the CloudWatch API only one time per data point.

Metric Statistics

Each metric has a label called stat which denotes the AWS statistic used during querying. Some metrics have multiple stats which are useful for different cases.

Supported AWS services

Click to Open

AWS/AOSS
AWS/ApiGateway
AWS/AppRunner
AWS/AppStream
AWS/AppSync
AWS/ApplicationELB
AWS/Athena
AWS/AutoScaling
AWS/Backup
AWS/Bedrock
AWS/Cassandra
AWS/CertificateManager
AWS/CloudFront
AWS/Cognito
AWS/DDoSProtection
AWS/DMS
AWS/DX
AWS/DocDB
AWS/DynamoDB
AWS/EBS
AWS/EC2
AWS/EC2Spot
AWS/ECR
AWS/ECS
AWS/EFS
AWS/ELB
AWS/ES
AWS/ElastiCache
AWS/ElasticBeanstalk
AWS/ElasticMapReduce
AWS/FSx
AWS/Firehose
AWS/GameLift
AWS/GlobalAccelerator
AWS/Glue
AWS/IoT
AWS/KMS
AWS/Kafka
AWS/Kinesis
AWS/KinesisAnalytics
AWS/Lambda
AWS/MWAA
AWS/MediaConnect
AWS/MediaConvert
AWS/MediaLive
AWS/MediaPackage
AWS/MediaTailor
AWS/MemoryDB
AWS/NATGateway
AWS/Neptune
AWS/Network Manager
AWS/NetworkELB
AWS/NetworkFirewall
AWS/PrivateLinkEndpoints
AWS/PrivateLinkServices
AWS/RDS
AWS/Redshift
AWS/Route53
AWS/S3
AWS/SES
AWS/SNS
AWS/SQS
AWS/SageMaker
AWS/Sagemaker/ModelBuildingPipeline
AWS/Sagemaker/Endpoints
AWS/Sagemaker/ProcessingJobs
AWS/Sagemaker/TrainingJobs
AWS/Sagemaker/TransformJobs
AWS/States
AWS/StorageGateway
AWS/TransitGateway
AWS/TrustedAdvisor
AWS/VPN
AWS/WorkSpaces
ECS/ContainerInsights

Setting up the integration

The integration is supported for both inCloud Managed and inCloud deployments, by following slightly different steps. Make sure to select the deployment relevant for you.

Not sure? Contact us on slack!

inCloud Managed

In this setup, the integrations-agent is deployed inside the managed backend. A service account is automatically provisioned inside the managed account, so the installation mainly requires creating a role in the target AWS account with the correct trust relationship.

Create an IAM role and policy

The following part requires two parameters:

YOUR_GROUNDCOVER_ACCOUNT_ID - the AWS account id hosting the groundcover backend, created during onboarding
YOUR_GROUNDCOVER_SITE_ID - your unique groundcover endpoint ID:
- Fetch your inCloud Site from these docs It will look like <SITE_ID>.platform.grcv.io
- The ID is the first part marked above as <SITE_ID>

Go to Amazon IAM
Click on Roles in the side bar

Click on Create Role

Select Custom trust policy

Paste the following policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<YOUR_GROUNDCOVER_ACCOUNT_ID>:role/groundcover-integrations-agent-<YOUR_GROUNDCOVER_SITE_ID>-sa"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Click on Next twice (we'll attach permissions later)
Provide a name for the role
Click on Create Role

Go to your newly created role

In the Permissions section, click on Add permissions and then Create inline policy

Click on JSON and paste the following:

{
    "Version": "2012-10-17",
    "Id": "groundcover-integrations-agent",
    "Statement": [
        {
            "Action": [
                "tag:GetResources",
                "storagegateway:ListTagsForResource",
                "storagegateway:ListGateways",
                "shield:ListProtections",
                "iam:ListAccountAliases",
                "ec2:DescribeTransitGatewayAttachments",
                "ec2:DescribeSpotFleetRequests",
                "dms:DescribeReplicationTasks",
                "dms:DescribeReplicationInstances",
                "cloudwatch:ListMetrics",
                "cloudwatch:GetMetricStatistics",
                "cloudwatch:GetMetricData",
                "autoscaling:DescribeAutoScalingGroups",
                "aps:ListWorkspaces",
                "apigateway:GET"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

Click on Next
Give the policy a name
Click on Create Policy

Choosing namespaces to ingest

Select the AWS namespaces you wish to ingest metrics from. The list of supported services is here.

Share the following details with the groundcover team to complete the integration:

The ARN of the role created above
The list of namespaces you wish to ingest
The region of the account you wish to ingest metrics from

inCloud

In this setup, the integrations-agent is deployed inside your cluster. The deployment comes with a built-in service account, and permissions will be provided to it using IRSA. Afterwards you will need to create a role + trust policy to allow the integrations-agent service account to assume the role and query the metrics.

Create an identity provider (OIDC) for your EKS cluster

If you already have an identity provider set up in the account where the EKS cluster is set up, skip this stage

The recommended way to give the integrations-agent the ability to interact with AWS resources inside an EKS cluster is using IRSA . The deployment comes in with a built-in service account, which can be used alongside OIDC to provide it with AWS permissions.

Create an OIDC provider for the EKS cluster where groundcover resides in. Once created, the details you will need in the next steps are:

Provider Name
Provider ARN
Namespace - the namespace where groundcover is installed (default: groundcover)

Create an IAM role and policy

Go to Amazon IAM
Click on Roles in the side bar

Click on Create Role

Select Custom trust policy

Paste the following policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "{Provider ARN}"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringLike": {
                    "{Provider Name}:sub": "system:serviceaccount:{Namespace}:integrations-agent"
                }
            }
        }
    ]
}

Click on Next twice (we'll attach permissions later)
Provide a name for the role
Click on Create Role

Go to your newly created role

In the Permissions section, click on Add permissions and then Create inline policy

Click on JSON and paste the following:

{
    "Version": "2012-10-17",
    "Id": "groundcover-integrations-agent",
    "Statement": [
        {
            "Action": [
                "tag:GetResources",
                "storagegateway:ListTagsForResource",
                "storagegateway:ListGateways",
                "shield:ListProtections",
                "iam:ListAccountAliases",
                "ec2:DescribeTransitGatewayAttachments",
                "ec2:DescribeSpotFleetRequests",
                "dms:DescribeReplicationTasks",
                "dms:DescribeReplicationInstances",
                "cloudwatch:ListMetrics",
                "cloudwatch:GetMetricStatistics",
                "cloudwatch:GetMetricData",
                "autoscaling:DescribeAutoScalingGroups",
                "aps:ListWorkspaces",
                "apigateway:GET"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

Click on Next
Give the policy a name
Click on Create Policy

Choosing namespaces to ingest

Select the AWS namespaces you wish to ingest metrics from. The list of supported services is here. These will be provided as a list in the next stage.

Deploy the changes

Add the following overrides to your groundcover installation. You will need the following:

Region - The region of the account you wish to ingest metrics from
NamespaceA, NamespaceB... - the AWS namespaces you chose
RoleARN - the ARN of the role created above

Note: the roleArn section in the configuration below is optional, and only required when using cross-account scraping. If you are scraping metrics inside the same account as the EKS cluster where groundcover is deployed, do not add the roleArn part.

In that scenario, you will need to define a role in each account with the permissions above, and enable cross-account access to assume the role from the RoleARN created above. The cross-account role appears below as otherAccountRole

global:
  integrations:
    agent:
      enabled: true
      
integrationsAgent:
  serviceAccount:
      annotations:
        eks.amazonaws.com/role-arn: {RoleARN}
  targets:
    cloudwatch:
    - stsRegion: "{Region}"
      regions:
        - "{Region}"
      namespaces:
        - "{NamespaceA}"
        - "{NamespaceB}"
      # optional - only for cross-account scraping, see note above
      roleArn: "{otherAccountRole}"

For example:

global:
  integrations:
    agent:
      enabled: true
      
integrationsAgent:
  serviceAccount:
      annotations:
        eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/groundcover-cw-metrics
  targets:
    cloudwatch:
    - stsRegion: "us-east-1"
      regions:
        - "us-east-1"
      namespaces:
        - "AWS/Lambda"
        - "AWS/ApiGateway"

Last updated 1 month ago

How does it work

Things to know

Ingestion interval

Data storage

Metric Statistics

Supported AWS services

Setting up the integration

Create an IAM role and policy

Choosing namespaces to ingest

Share details with groundcover

Create an identity provider (OIDC) for your EKS cluster

Create an IAM role and policy

Choosing namespaces to ingest

Deploy the changes