docs: May 2024 updates (#635)

docs/faq.md

@@ -9,7 +9,7 @@ Infracost has a [CLI](https://github.com/infracost/infracost) and a [Cloud Prici
 When the CLI runs, it:
 
 1. **Extracts cost-related parameters**<br />
-  The CLI parses Terraform HCL code to extract only [cost-related parameters](/docs/faq#example-request), such as the instance type or disk size.
+  The CLI parses Terraform HCL code to extract only [cost-related parameters](/docs/faq#example-request), such as the instance type or disk size. The CLI automatically discovers all projects or environment in your repo.
 
 2. **Retrieves prices from the Cloud Pricing API**<br />
   The CLI retrieves prices from the Cloud Pricing API. The CLI **does not** send the Terraform plan JSON file, or any cloud credentials or secrets to the Cloud Pricing API. The API [returns the prices](/docs/faq#example-response).
@@ -22,9 +22,7 @@ When the CLI runs, it:
 
 ## Security and Privacy
 
-Security is of paramount importance to us. We are SOC 2 Type II certified. Our <a href="https://www.infracost.io/security/" target="_self" rel="">Security page</a> gives an overview of the processes and systems Infracost has in place to ensure we are continually protecting our users' data.
-
-If you have any questions or concerns, please [contact us](mailto:[email protected]).
+Security is of paramount importance to us. We are SOC 2 Type II certified. Our <a href="https://security.infracost.io" target="_self" rel="">Trust center page</a> enables you to request details and provides an overview of the processes and systems Infracost has in place to ensure we are continually protecting our users' data. If you have any questions or concerns, please [contact us](mailto:[email protected]).
 
 ### What data is sent to the Cloud Pricing API?
 
@@ -109,6 +107,10 @@ Infracost provides static IPs for its Cloud Pricing API and Infracost Cloud serv
 
 ## Features
 
+### Which cloud providers and IaC frameworks are supported?
+
+Currently AWS, Azure and Google are supported with Terraform.
+
 ### What's the difference between Infracost and Terraform Cloud's cost estimation?
 
 There are three key areas of differentiation.
@@ -138,6 +140,10 @@ By default, Infracost parses the code to detect the instance count, thus it has
 
 You can override the instance count manually in the [usage file](/docs/features/usage_based_resources/).
 
+### How do you deal with Reserved Instances and Savings Plans?
+
+See [this doc](/docs/infracost_cloud/custom_price_books/#reserved-instances-and-savings-plans) for details.
+
 ### Can I show costs in a different currency?
 
 Sure! See the [currency](/docs/features/environment_variables/#infracost_currency) docs section.

docs/infracost_cloud/custom_price_books.md

@@ -27,10 +27,18 @@ You can apply these discounts in Infracost Cloud:
 
 ## Custom price books
 
-We can also apply SKU-level custom cloud pricing to your Infracost Cloud organization. Please [contact us](mailto:[email protected]) to set this up. We would need details of the services or SKUs that you'd like to customize.
+We can also apply SKU-level custom cloud pricing to your Infracost Cloud organization. Please [contact us](mailto:[email protected]) to set this up. We would need details of the services or SKUs that you'd like to customize. For example, AWS customers can get this information in the Cost & Usage Reports, and Azure customers can use the [Price Sheet CSV export](https://learn.microsoft.com/en-us/azure/cost-management-billing/manage/ea-pricing?wt.mc_id=searchAPI_azureportal_inproduct_rmskilling&sessionId=e5ed2c1e32b5482c8c7c9a1ecf3b13b2#download-pricing-for-an-enterprise-agreement).
 
 ## Reserved Instances and Savings Plans
 
-For cost estimation purposes, engineers often prefer a simple price point that they can use in their calculations and when making design decisions. Reserved Instances and Savings Plans complicate this due to the dynamic nature of their discounts, which is applied after resources are launched.
+For cost estimation purposes, engineers often prefer a simple price point that they can use in their calculations and when making design decisions. Reserved Instances (RIs) and Savings Plans (SPs) complicate this due to the dynamic nature of their discounts, which is applied after resources are launched. Companies usually manage this by having:
+- Central FinOps teams often change RIs and SPs regularly to match instance usage.
+- Engineers compare like-for-like using on-demand prices; FinOps team ensures maximum savings of RIs/SPs; Engineers ship fast.
+- Engineers use consistent number & make upfront design decisions quickly.
+- Custom price books include main discounts already.
 
-Therefore, to simplify cost estimation for engineers, some companies prefer to use "blended rate" of resources, which combines on-demand and discounted prices into one price point. The blended rate is shown in cloud vendor Cost and Usage Reports (e.g. AWS CUR) and we can import them into your Infracost Cloud organization so they can be used instead of on-demand prices. Please [contact us](mailto:[email protected]) to setup a way for you to provide these to us.
+Showing engineers on-demand prices means that only the FinOps team is changing things, vs engineers also trying to second-guess the RI/SP discount allocation.
+
+However, some companies prefer to use "blended rate" of resources, which combines on-demand and discounted prices into one price point. The blended rate is shown in cloud vendor Cost and Usage Reports (e.g. AWS CUR) and we can import them into your Infracost Cloud organization so they can be used instead of on-demand prices.
+
+Please [contact us](mailto:[email protected]) to discuss what works best for your organization.

docs/infracost_cloud/finops_policies.md

@@ -31,7 +31,7 @@ The Governance > FinOps page shows the status of all policies (screenshot on top
 
 When engineers create a pull request to change infrastructure, Infracost scans the code and checks the FinOps policies against all changed resources. Infracost shows the best practices alongside an explanation of why it's important to consider implementing the change. Infracost also shows the exact file and line numbers that need to be changed if the engineer chooses to implement the change. This shifts-left on FinOps policies and results in the fastest possible feedback loop.
 
-<img src={useBaseUrl("img/infracost-cloud/finops-policies/pr-comment.png")} alt="Create a pull request to test FinOps policies." />
+<img src={useBaseUrl("img/infracost-cloud/pull-request-comment.png")} alt="Create a pull request to test FinOps policies." />
 
 <img src={useBaseUrl("img/infracost-cloud/finops-policies/pr-comment-expanded.png")} alt="The pull request comment shows exactly what file and line number need to be updated to fix the issue." />
 

docs/infracost_cloud/guardrails.md

@@ -7,15 +7,15 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
 
 Guardrails help you control costs by monitoring pull requests (PRs) and triggering actions when your defined thresholds are exceeded. Once you define a cost or percentage-based threshold for the relevant repositories, projects, and branches, you can set up email, Slack, or Microsoft Teams notifications. You can also customize the PR comment (e.g. "This change exceeds the budget, please discuss with your team lead") or even block the PR until it has been reviewed.
 
-<img src={useBaseUrl("img/infracost-cloud/guardrails/cost-saving.png")} alt="Cost savings from guardrails" />
+<img src={useBaseUrl("img/infracost-cloud/guardrails/index.png")} alt="Guardrails" />
 
-## Preventive costs
+## Cost prevention
 
 We figure out how much you've saved on guardrails by looking at the difference between the costliest run that activated the guardrail and the final cost when you made your latest change. So, let's say an engineer opens a pull request with a change that would've increased the cost by $10k, but the guardrail is triggered. Your team then works to reduce the cost, and the changes finally get approved and merged with an increased cost of $2k. In this case, you've saved $8k because of the guardrail.
 
-Guardrails also have an audit trail of the pull requests that triggered them so you can see details of the preventive costs:
+From the Infracost Cloud dashboard, you can see the total cost prevention from guardrails. Clicking on that number will show you an audit trail of the pull requests and their cost prevention numbers.
 
-<img src={useBaseUrl("img/infracost-cloud/guardrails/guardrail-events.png")} alt="Guardrail events" />
+<img src={useBaseUrl("img/infracost-cloud/guardrails/cost-savings.png")} width="70%" alt="Guardrail cost prevention" />
 
 ## Usage
 

docs/infracost_cloud/key_concepts.md

@@ -33,7 +33,7 @@ Infracost Cloud also supports authenticating with [Enterprise SSO providers](/do
 
 ## Organizations
 
-In Infracost Cloud, organizations are used to manage API keys and associated settings. Every Infracost user has a default organization for personal use. We recommend creating a new organization for your company API key as in the future you'll be able to add other users to organizations.
+In Infracost Cloud, organizations are used to group repos, policies and other associated settings.
 
 ### API keys
 
@@ -49,20 +49,16 @@ From the Members page, you can invite your team members to join your organizatio
 
 ## Repos
 
-Repos, short for code repositories, is where your code lives in GitHub, GitLab or any other source control system. Repo is our top-level required grouping concept. If Infracost cannot detect it, you can provide it via [new environment variables](/docs/features/environment_variables/#environment-variables-to-set-metadata), otherwise cost estimates only show in the "All estimates" tab in Infracost Cloud (and not the dashboard, which shows pull request costs).
-
-A repo contains one or more projects. Infracost Cloud lets you track how the costs of repos and projects change over time.
+Repos, short for code repositories, is where your code lives in GitHub, GitLab or any other source control system. A repo contains one or more projects. Infracost Cloud lets you track how the costs and policy issues of repos and projects change over time.
 
 ## Projects
 
 Projects map to repo sub-groups. The majority of Infracost users will have repos that have many projects, these include:
 - code paths for mono repos, each path represents a deployment environment such as dev, stage, prod
-- workspaces, same idea as above but done using Terraform workspaces, e.g. for dev, stage, prod
+- workspaces, same idea as above but done using Terraform var files or workspaces
 - Terraform or Terragrunt modules, which are components of a repo, e.g. core-api or data-stack
 
-If you setup Infracost for a Terraform module repo, you will not need projects as there is no need for a sub-group.
-
-Infracost auto-generates project names based on code paths, workspaces or Terraform/Terragrunt modules. The name appears in the CLI output and pull request comments and Infracost Cloud as shown below.
+Infracost auto-generates project names based on code paths, workspaces or Terraform/Terragrunt modules. The name appears in the CLI output and pull request comments and Infracost Cloud as shown below. If Infracost cannot detect your projects, or if you would like to customize them, we recommend using a [**config file**](/docs/features/config_file/).
 
 <img src={useBaseUrl("img/infracost-cloud/cli-project-name.png")} alt="Auto-generated project name in CLI" />
 
@@ -74,8 +70,3 @@ Infracost auto-generates project names based on code paths, workspaces or Terraf
 
 <img src={useBaseUrl("img/infracost-cloud/infracost-cloud-project-name.png")} alt="Project name in Infracost Cloud" />
 
-### Customize project names
-
-When a long Terraform directory path exists, or paths such as `/tmp/plan.json` are used, the project name might be hard to understand. In such cases we recommend using a [**config file**](/docs/features/config_file/) to set project names to something more understandable.
-
-Alternatively, the `--project-name` flag can also be used; you should set the same project name for both `diff` and `breakdown` commands, failing to use the same name for both breakdown and diff will result in odd diffs.

docs/infracost_cloud/reports.md

@@ -5,16 +5,14 @@ title: Reports
 
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
-All Infracost Cloud users get a weekly email of the most impactful changes across all repos in their organizations. This email shows the most impactful changes across repos, projects, pull requests and users. 
+All Infracost Cloud users get a weekly email summarizing the main changes across all repos in their organization. This email shows the most impactful changes across repos, projects, pull requests and users. 
 
 ### Usage
 
-Log in to [Infracost Cloud](https://dashboard.infracost.io) and go to the Reports page. When creating a report, you can filter on specific pull requests (e.g. only report on certain repositories or merged pull requests) and select the report frequency (daily, weekly, monthly). You can also select which users should get the reports as shown below.
+Log in to [Infracost Cloud](https://dashboard.infracost.io) and go to Reports > Email reports to create reports. When creating a report, you can filter on specific repositories, and select the report frequency (daily, weekly, monthly). You can also select which users should get the reports as shown below. Only merged pull requests are included in reports.
 
 <img src={useBaseUrl("img/infracost-cloud/report-create.png")} alt="Creating a report" />
 
-The pull request status filters (open, merged, closed) fetch pull requests with the selected statuses at the time the report is sent. For example, a daily report with a filter on open pull requests will only include pull requests that are currently open at the time the report is sent every day and have a cost estimate for the report date. So if a pull request was opened and merged quickly it will not be included in that daily report; you can include merged pull requests in the report filter for those. If the pull request doesn't receive any new cost estimates after that, the daily report for the next day will not include it.
-
 ### Example report email
 
 The following screenshot shows an example email report.

docs/integrations/cicd.mdx

@@ -39,7 +39,7 @@ export const CIBox = ({image, link, maxHeight, newWindow, text}) => (
 
 Use one of our many integrations so your engineering team can see cost estimates and FinOps best practices in pull requests **before making changes**. This provides your team with a safety net as people can discuss FinOps as part of the workflow.
 
-<img src={useBaseUrl("img/screenshots/actions-pull-request.png")} alt="Infracost pull request comment" width="85%" />
+<img src={useBaseUrl("img/screenshots/actions-pull-request.png")} alt="Infracost pull request comment" />
 
 If you run into any issues, please join our [community Slack channel](https://www.infracost.io/community-chat), we'll help you very quickly 😄