Connecting Teevity to your Amazon Web Services environment
Last updated - 2022/09/08
If you use AWS, here are all the details (and some AWS CLI based scripts, with download link in this page) regarding 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
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 your external ID you will find on the AWS account setup page :
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
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.
Connection with a dedicated IAM user and AccessKey / SecretAccessKey
In this scenario, you create an IAM user and provide Teevity with the AK/SK of this user. This IAM user can live:
On the account that owns the billing bucket
On another account (exclusively dedicated to IAM users for instance). In this case, you must provide the name of an IAM Role that lives on the AWS account that owns the billing bucket. Teevity will try to assume this Role on the account whose number is provided in the "Master account number".