Last updated - 2024/08/05

If you use AWS, here are all the details (and some AWS CLI based scripts, with download link in this page) explaining how you can connect Teevity to your AWS billing environment using:

• • An IAM cross account relationship between your AWS environment and Teevity

  • AWS Cost And Usage reports (aka CUR reports) which contain an hourly, zipped or gzipped export of your AWS spend 

Once this connection is established, and if you want Teevity to provide its full range of services, you also need to allow Teevity to connect to the individual AWS accounts of your company (or a subset of these AWS accounts) in order to poll:

• • AWS CloudWatch metrics (for the Resource Usage Optimization service)

AWS Cost and Usage Reports (aka CUR reports)

You can find everything about AWS CUR reports in the AWS Documentation, starting from this page Creating an AWS CUR Report.
IMPORTANT: Remember that Teevity expects  hourly, zipped or gzipped CUR reports.

Connecting your AWS environment and Teevity

Connecting AWS Billing Account(s)

Connection using an IAM cross account relationship

The recommended method for connecting third-party tools to you AWS environment is to establish a "trust relationship" between an IAM Role living in your AWS environment (which we recommend to call this role TeevityCrossAccountTrustRole) and the Teevity service (defined by its own IAM Role, under our management).

You will find detailed information about this:

• in the AWS documentation here https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html

• below, in the next sections of this page (including in the well commented/documented AWS CLI based scripts linked below)

REMARK: The TeevityCrossAccountTrustRole role will most likely be created on the AWS account that holds your AWS Billing bucket. But you can also chose to have this IAM Role live on a separate AWS account, and ask Teevity to assume another role, the BillingBucketReadOnlyRole role, to access the billing bucket (cf screenshot below on where to specify this role).

ADVANCED:  If your company has a strict naming conventions on IAM Roles, you may need to use a specific IAM Role name (instead of TeevityCrossAccountTrustRole). If this is the case, please get in touch with support@teevity.com.

Creation of the "Cross account trust IAM Role" in your environment

To Connection of your AWS environment with Teevity:

• • Step 0 - Create an IAM role called TeevityCrossAccountTrustRole of type "cross account trust" on the Master Billing account. The trust relationship is used to enable the "Teevity AWS IAM role" (arn:aws:iam::795686180151:user/teevity.prod.customerbillingaccess.crossaccount) to assume the TeevityCrossAccountTrustRole role you have created.

To perform this step, you can use the STEP0 script (cf the "AWS CLI based scripts" section below).
Before executing this script, you will need adjust some values inside it: 

• replace ##S3_PROGRAMMATIC_BILLING_BUCKET_NAME##" by the name of the S3 bucket where the CUR reports are exported (see more information here)

• replace ##TEEVITY_TRUST_RELATIONSHIP_EXTERNALID## by the external ID generated specifically for your Teevity Account, which you will find on the Teevity AWS account setup page (cf  the green arrow in the screenshot inside the "Declaration of Billing Accounts using the Teevity UI" section below)

Declaration of Billing Accounts using the Teevity CLI

Usage of the Teevity CLI for an AWS BillingAccount declaration

#
# Declare an AWS CUR environment on your Teevity account
#
#   TEEVITY_API_KEY=e9543083-xxxx-xxxx-xxxx-23c8573e4d4b
#
#   AWS_BILLINGACCOUNT_ID=857xxxxx9404
#
#   AWS_CUR_BUCKETNAME=teevity-hr
#   AWS_CUR_BUCKETPREFIX=
#   AWS_CUR_REPORTNAME=teevity-cur-hourly
#
#   REMARKS:
#      aws-cur-only-usage-date is an optional parameter and defines at which date, when there are both DBRWRT and CUR reports, only CUR reports should be considered (1609459200000 is 2021-01 in "Epoch time millis")
#      aws-cur-billing-bucket-region is the version where the S3 bucket is, without dashes (useast1, apsouth1, ...) 
#

teevity cloudservices declare-account-aws \
      --key "${TEEVITY_APIKEY}" \
      --aws-consolidatedbillingaccount-id "${AWS_BILLINGACCOUNT_ID}" \
      --aws-billing-access-credentials-mode "CROSSACCOUNT" \
      --force-awscostexplorer-api "true" \
      --aws-cur-billing-bucket-region "apsouth1" \
      --aws-cur-billing-bucket-name   "${AWS_CUR_BUCKETNAME}" \
      --aws-cur-billing-bucket-prefix "${AWS_CUR_BUCKETPREFIX}" \
      --aws-cur-report-name           "${AWS_CUR_REPORTNAME}" \
      --aws-cur-only-usage-date       "1609459200000" \
      --do-not-launch-data-fetching

Connection of individual AWS accounts (for CloudWatch metrics collection)

Once the connection with Teeevity is established, and if you want Teevity to provide its full range of services, you also need to connect it to the individual AWS accounts of your company (or a subset of these AWS accounts). 

The connection of the individual AWS accounts lets Teevity poll:

• • AWS CloudWatch metrics (for the Resource Usage Optimization service)
    
    

In order to set this up, you need to create IAM Roles on the AWS child accounts.

Creation of IAM roles on the child accounts (to allow Teevity to poll CloudWatch metrics on these accounts ) and of a cross-account-access relationship between the child accounts and the role on the master account (or the IAM user if you followed the method 1):

• • • Step 1 - Create an IAM role of type "cross account trust" on each sub accounts (and all accounts with resources or owning RIs). This role can be called something like TeevityPollerRole (see this script) where

      • ##TEEVITY_IAM_USERNAME##  is the IAM user if you used the method 1 (see above) or role/TeevityCrossAccountTrustRole if you used the method 2 (see above)

    • Step 2 - Authorize the TeevityCrossAccountTrustRole role or the IAM user to assume that role (see this script) where

      • ##TEEVITY_IAM_USERNAME## is the IAM user if you choose the method 1 (see above). 

      • ##AWS_CHILDACCOUNT_NUMBER_00X## are the children accounts ids where the role of the step1 has been declared

AWS CLI based scripts

Scripts referenced on this page (each script is packaged in a zip file which contains only one .sh file (but it's just CLI commands which would work as-is on Windows) and the dependant file(s) for the IAM policies) :

• step0-Teevity-IAM-crossAccountTrustConfiguration-onMainAccount.zip

• step1-Teevity-IAM-crossAccountConfiguration-forChildAccounts.zip

• step2-Teevity-IAM-crossAccountConfiguration-forMainAccount.zip

TIPS: The documentation in this page has sections called "Step 0", "Step 1" and "Step 2". The names of the file above match these sections to make your life easier.

Deprecated connection methods

WARNING - The connection methods listed here are still allowed by Teevity but are deprecated. The are listed here for a complete documentation but it is not recommended to use them anymore.