Connect an AWS account#

The Community Edition connects one cloud account, on AWS, Azure or GCP (editions.md). The AWS ingestor is installed by default. An administrator connects the account in the UI, under Integrations, AWS. The screen walks through the services and regions, the billing export and the access, and offers a test before it saves.

Hyvop only reads. It lists and describes resources, reads CloudWatch metrics, and reads the cost reports in one S3 bucket. It makes no change in the account.

1. Services and regions#

Pick the services to collect. EC2, EBS, RDS and S3 are selected by default; Lambda, ELB / ALB / NLB, Elastic IPs, All Snapshots and DynamoDB are off until you pick them.

Pick the regions to scan, or none for all supported commercial regions. A region the account has not enabled is not an error: the ingestion card counts it as "not enabled for this account" and moves on (troubleshooting.md).

2. The billing export (cost report)#

Cost comes from an AWS Cost and Usage Report 2.0 delivered to S3, which Hyvop reads. Without it resources are collected and carry no billed cost. In the AWS console, under Billing, Data Exports, create a Standard data export (CUR 2.0) with the settings the screen gives:

• name hyvop-cur-export;
• Resource IDs on, Split cost allocation data on, time granularity Hourly, compression Parquet;
• destination: your bucket and a prefix (the screen suggests cur-2.0/).

Enter the bucket name and the prefix in the screen; it shows the exact S3 address Hyvop will read. The first delivery arrives within about 24 hours. An export you already have works: enter its bucket and prefix.

Who created a resource. The bill names a creator only when the account has activated cost-allocation tags, among them aws:createdBy (Billing, Cost allocation tags; a tag takes up to 24 hours to appear after it is activated). Otherwise Hyvop uses the tags people wrote on the resource, if any, and says nothing rather than guess.

3. Access: a role (recommended) or access keys#

A role in your account#

Hyvop assumes a read-only role in your account. The role has a trust policy that names the identity Hyvop runs as and an external id made for your organisation; a role without the external id is refused.

1. Give the AWS ingestor an identity of its own, and core as well (core uses it for the connection test). On EKS, annotate their service accounts with the role they run as:

   yamlCopy

   ingestors:
     aws:
       serviceAccount:
         annotations:
           eks.amazonaws.com/role-arn: arn:aws:iam::111122223333:role/hyvop-ingestor
   core:
     serviceAccount:
       annotations:
         eks.amazonaws.com/role-arn: arn:aws:iam::111122223333:role/hyvop-core

2. In the screen, choose "A role in your account". It shows the principal, your external id, the permissions policy for the services you chose, the trust policy, and a CloudFormation template and a Terraform file that create the role as HyvopReaderRole with the policy HyvopReadOnly. Copy them from the screen rather than from this page.

3. Create the role, paste its ARN (arn:aws:iam::<account>:role/HyvopReaderRole) into the screen, and test.

Access keys#

When Hyvop has no AWS identity of its own: create an IAM user, attach the same read-only policy (name it HyvopReadOnly), create an access key and paste the key pair into the screen. Hyvop stores the secret key encrypted under the install's data key and never shows it again (backup-and-restore.md). Rotate it on a schedule.

Permissions#

The policy is generated, one action per call the collectors make, with no wildcard. The inventory actions are list and describe calls allowed on all resources; the two cost-report actions (s3:ListBucket, s3:GetObject) are limited to the one bucket you named. The policy does not allow reading the contents of any other bucket.

4. Test and save#

"Test connection" runs a set of checks and shows each one, with the reason and a hint when it fails. Saving connects the account: it is collected at once, then on schedule, by default inventory every 4 hours, metrics every 2 hours and billing nightly at 02:00. The ingestion card on the Integrations page shows the last and next run of each.

The ingestors need to reach the cloud's APIs on port 443: networkPolicy.egress.ingestors.internet is true by default. Prices are read by the ingestor from the AWS price lists; see "No price list" in troubleshooting.md.

How much history the first collection reads#

The first collection of a newly connected account reads 30 days of metrics, so that the rules that need history can report once it is there. The ingestor setting AWS_METRICS_BACKFILL_DAYS (30 by default) sets it: ingestors.aws.env.AWS_METRICS_BACKFILL_DAYS=14. A shorter history leaves the rules that need more days to wait.

Try it without an AWS account (demo mode)#

Set ingestors.aws.env.AWS_DATA_SOURCE=dummy, then connect the account 000000000000 (twelve zeros) in Hyvop to see sample data. Any connection method works; the keys are not used, so placeholders do. Remove the sample data with the "remove demo data" action (an administrator), and switch back to live for a real account.