docs: Nov-2024 updates

docs/infracost_cloud/finops_policies.md

@@ -5,39 +5,49 @@ title: FinOps policies
 
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
-Infracost enables you to pro-actively check FinOps best practices in the engineering workflow, before you deploy infrastructure code. This approach boosts developer productivity by providing quick feedback and encouraging the creation of efficient infrastructure code from the outset, removing the need for post-deployment revisions. Additionally, it spares FinOps teams from the continual effort of urging engineers to adhere to best practices, thereby preventing significant amounts of money being wasted in the cloud.
+The [cloud cost optimization formula](https://www.infracost.io/blog/cloud-cost-optimization-formula/) has a *usage* and a *unit price* that contributes to your cloud bill. The usage component of that formula is fully dependent on engineering teams taking action to change the usage, whereas the unit price can be done in a centralized manner via FinOps tasks such as purchasing reserved instances.
 
-<img src={useBaseUrl("img/infracost-cloud/finops-policies/policies.png")} alt="Infracost includes many AWS, Azure and Google FinOps policies out of the box" />
+Tackling waste requires engineering involvement at every level. FinOps policies gives you a way to prioritize, organize, and fix issues at the source. It's more than just reporting waste; it empowers engineers to take direct action in *their* workflows.
+
+FinOps policies make waste reduction of the usage a team-wide, actionable process. No meetings or Jira tickets, just a streamlined approach to cut unnecessary costs from day one.
 
 ## Usage
 
-This section assumes you have already setup the Infracost source control integration with [GitHub , Azure Repos or GitLab](/docs/integrations/cicd/#source-control-integrations-recommended) (or added Infracost to your CI/CD pipeline).
+### 1. Two steps to cut waste
+
+1. **Seal the leaks.** With cloud resources controlled by infrastructure-as-code, adding waste-reducing policies directly into CI/CD workflows is the best way to stop problems before they start.
+2. **Burndown existing issues.** The best way to do this is to empower engineering teams to action waste within *their* code and workflow, by pinpointing the exact files and lines they need to change.
+
+<img src={useBaseUrl("img/infracost-cloud/finops-policies/chart.png")} alt="FinOps policies provide a streamlined approach to cut unnecessary costs from day one." />
+
+### 2. Use policies to drive action, not meetings & Jira tickets
 
-## 1. See policy failures on repos
+Too often, waste reports lead to long meetings and endless Jira tickets. FinOps policies flips the script with an actionable, streamlined approach. It identifies which of the 70+ AWS, Azure, and Google best practices from the Well-Architected Frameworks aren’t being followed. From there, FinOps teams can decide which policies are most critical to their organization, picking the top 3-5 to focus on each quarter.
 
-Once you've connected a repo to Infracost, it scans your code and checks for over **50 AWS, Azure and Google** FinOps policies out of the box. This gives you immediate analytics on how well you're following the best practices.
+Once priorities are set, Infracost takes care of the rest: FinOps teams simply enable pull request comments for those selected policies, and Infracost automatically checks all pull requests against them. Engineers can then focus on fixing these high-priority issues directly in their code, reducing waste without the need for extra meetings or task-tracking.
 
-Go to the Visibility > Repos page to see which FinOps policies the repo is failing on; for example, the following screenshot shows a repo that is failing 3 policies. The file and line numbers are also shown with a suggested fix so engineers can easily take action.
+<img src={useBaseUrl("img/infracost-cloud/finops-policies/policies.png")} alt="See all FinOps and Tagging policy failures for each repo" />
 
-<img src={useBaseUrl("img/infracost-cloud/finops-policies/repo-page.png")} alt="See all FinOps and Tagging policy failures for each repo" />
+### 3. Track your improvements in real time
 
-## 2. Analytics on policy coverage
+Results matter, and we made sure Infracost makes it easy to track wins. Here’s a snapshot of a customer's progress on their tagging policy:
 
-The Governance > FinOps page shows the status of all policies (screenshot on top of this page), and which policies have the highest number of failing resources. A weekly chart showing the percentage of applicable resources passing FinOps policies is also shown on this page. This shows how well you're progressing on implementing FinOps best practices across all of your repos over time.
+- **Proactive prevention:** Out of 8.1K new issues since July 1, 80% (6.5K) were prevented before the code was merged.
+- **Burning down the backlog:** The team has resolved 41% (39K) of existing tagging issues since July, which translates to 13K fixes per month. At this pace, they’re on track to clear-out all 55K remaining issues in four months!
 
-<img src={useBaseUrl("img/infracost-cloud/finops-policies/coverage-chart.png")} alt="Infracost Cloud shows you the percentage of resources that are passing your FinOps policies." />
+<img src={useBaseUrl("img/infracost-cloud/finops-policies/burndown-chart.png")} alt="Infracost Cloud shows you a burndown chart if how you're doing." />
 
-## 3. Test pull requests
+## Test pull requests
 
 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/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." />
 
-## 4. Update policy settings
+## Update policy settings
 
-From the Governance > FinOps page, you can click on the details of any policy and update its settings. These settings include the option to block requests that fail the policy, and the ability to customize the message shown to engineers in pull requests. This is useful if you need to customize the message to recommend your company's specific policy or a link to internal wiki pages where engineers can learn more.
+From the Governance > FinOps page, you can click on the 3 dots for any policy and  update its settings. These settings include the option to block requests that fail the policy, and the ability to customize the message shown to engineers in pull requests. This is useful if you need to customize the message to recommend your company's specific policy or a link to internal wiki pages where engineers can learn more.
 
 You can also define whether a policy should trigger only when new resources are being added. This is useful when changing an existing resource, such as a database's instance type, requires downtime and thus you prefer engineers to not do that within their existing open pull request.
 
@@ -66,7 +76,7 @@ To set this up, go to Infracost Cloud > Governance > FinOps policies > Inactive
 
 You can override wildcard settings with more specific ones. For example, adding the pair `*:t1.micro` will allow the use of `t1.micro` instances in all regions, but adding the more specific pair `us-west-2:t2.micro` will override this, meaning only `t2.micro` instances can be used in the `us-west-2` region, but `t1.micro` instances can still be used in all other regions.
 
-## 5. Policies for non-production environments
+## Policies for non-production environments
 
 Some FinOps policies are only applicable to non-production environments, for example, consider using single-AZ databases in non-production environments. These policies are often overlooked as engineers tend to use the same infra-as-code logic for production; however, they provide easy and significant cost savings. In Infracost Cloud, go to the Governance > FinOps policies page, and search for "non-production" to see these policies and the resources that are failing the policies.
 

docs/infracost_cloud/tagging_policies.md

@@ -15,60 +15,54 @@ Infracost enables you to define your tagging policies so you can communicate and
 
 You can create multiple tagging policies, for example one policy that applies to all resources, and another one that applies to certain resource types. To create a tagging policy, log in to [Infracost Cloud](https://dashboard.infracost.io) and go to the **Governance** > **Tagging policies** page, and follow the steps below.
 
-### a. Scope of tagging policy
+### a. Define tag keys and values
 
-Give your tagging policy a name, and select the whether the policy should be evaluated against all or specific resource types. Resource-type specific tags are useful in cases you want resources such as EC2 instances to have specific tags such as shutdown schedules.
+You can define what tag keys are mandatory, which tag values are allowed, and make it easy for engineers to take action.
 
-<img src={useBaseUrl("img/infracost-cloud/tagging-policies/name-and-scope.png")} alt="Define tagging policy name and scope." />
+You can also validate tag values using a regular expression (ECMAScript is used). Partial matches are used, so for example `dev` will match `dev`, `development` and `api-development`; but `.*-dev-.*` will not match `development`. In this case, it's helpful to include a brief description of allowed values and examples in the tag key's custom message box.
 
-### b. Define tag keys and values
+<img src={useBaseUrl("img/infracost-cloud/tagging-policies/define-tags.png")} alt="Define tag keys and values." />
 
-You can define what tag keys are mandatory, which tag values are allowed, and make it easy for engineers to take action. You can also validate tag values using a regular expression (ECMAScript is used). Partial matches are used, so for example `dev` will match `dev`, `development` and `api-development`; but `.*-dev-.*` will not match `development`.
+### b. Custom pull request message
 
-<img src={useBaseUrl("img/infracost-cloud/tagging-policies/define-tags.png")} alt="Define tag keys and values." />
+You should also set a custom message to be included in pull request comments to give additional context or instructions. For example, you can describe **why** tagging is important for your organization and link to your internal wiki page.
+
+<img src={useBaseUrl("img/infracost-cloud/tagging-policies/customizations.png")} alt="You can customize the pull request message." />
 
 ### c. Optionally block pull requests
 
-Next you can define whether pull requests that fail this policy should be blocked until the policy failure is fixed. Depending on how your source control system is configured, your admins can usually bypass this for edge cases.
+Next you can define whether pull requests that fail this policy should be blocked until the policy failure is fixed. We recommend giving engineering teams a warning period of 1-3 months before putting policies into enforcement mode. Depending on how your source control system is configured, your admins can usually bypass this for edge cases.
 
 <img src={useBaseUrl("img/infracost-cloud/tagging-policies/actions-to-take.png")} alt="You can optionally block pull requests that fail a policy." />
 
-### d. Custom pull request message 
+### d. Advanced settings
 
 We recommend you leave "Include details in pull requests" as enabled so engineers are shown details of tagging policy failures. However, during testing, you can disable this so you can see the details in Infracost Cloud but not in pull request comments.
 
-You can also set a custom message to be included in pull request comments to give additional context or instructions. For example, you can describe why tagging policies are important or link to your internal wiki page.
-
-<img src={useBaseUrl("img/infracost-cloud/tagging-policies/customizations.png")} alt="You can customize the pull request message." />
-
-### e. Pull requests to monitor
+The "Resource types filter" filter is specially useful for Azure users, as they often only require tags to be set for `azurerm_resource_group` resources, and enable an Azure feature so resources inherit tags from their resource group. 
 
 Usually users monitor all pull requests for tagging policies. However, you can also set filters, e.g. only monitor pull requests in certain repositories so you can do gradual rollouts of your policy. Once you are done, save the tagging policy.
 
 <img src={useBaseUrl("img/infracost-cloud/tagging-policies/filters.png")} alt="Create a tagging policy using pull request filters." />
 
-## 2. See policy failures on repos
-
-Once you have created a tagging policy, Infracost Cloud shows you a central dashboard of any tagging policy failures that are currently happening on your main or master branch across all of your code repos.
-
-This means that you do not need to wait for a pull request to test your policy. Go to one of your repos from Visibility > Repos, and click on the Re-run estimate button. Any tagging policy failures will be shown.
+## 2. See all tagging issues
 
-<img src={useBaseUrl("img/infracost-cloud/tagging-policies/branch-policies.png")} alt="Infracost Cloud shows you any tagging policy failures that are currently happening on your main or master branch too." />
+Once you have created a tagging policy, click on the "Re-run policies" button. This will scan all of your repositories main or master branch and show all tagging issues. This means that you do not need to wait for a pull request to test your policy. 
 
-## 3. Analytics on policy coverage
+Whilst cloud vendor tools such as AWS Cost Explorer show the percentage of untagged costs, Infracost Cloud shows the exact infrastructure-as-code resources that are not using your allowed tag keys and values. You can also filter on specific repos or VCS organizations to zoom-in on a subset of the issues.
 
-From the Governance > Tagging policies page, you can see the percentage of taggable resources that are passing your tagging policies over the last 6 months. Whilst cloud vendor tools such as AWS Cost Explorer show the percentage of untagged costs, Infracost Cloud shows the percentage of infrastructure-as-code resources that are strictly following your tagging policies, which is much clearer for engineers to action and improve. This is an important KPI that FinOps teams track and improve over time to reduce the percentage of costs that cannot be categorized and allocated.
+<img src={useBaseUrl("img/infracost-cloud/tagging-policies/coverage-chart.png")} alt="Infracost Cloud shows all resources that are not using your allowed tag keys or values." />
 
-<img src={useBaseUrl("img/infracost-cloud/tagging-policies/coverage-chart.png")} alt="Infracost Cloud shows you the percentage of resources that are passing your tagging policies." />
+Infracost makes tagging actionable for engineers. Tracking the percentage of resources that are tagged correctly is an important KPI that FinOps teams track and improve over time. This reduces the percentage of costs that cannot be categorized and allocated.
 
-You can also see pull requests that failed policies (shown above). Each of these pull requests would have been deployed with missing or incorrect tags had Infracost not flagged them for engineers to action. Fixing these issues before code is deployed saves significant engineering time as otherwise engineers need to create new pull requests, wait for code reviews, and re-deploy their changes.
-
-## 4. Test pull requests
+## 3. Test pull requests
 
 When engineers create a pull request to change infrastructure, Infracost scans the code and checks the tagging policies against all changed resources. It notifies the engineer immediately of any issues; the pull request comment (shown below) tells them exactly what file and line number they need to change to resolve the issue. This shifts-left on the tagging policy and results in the fastest possible feedback loop.
 
 <img src={useBaseUrl("img/infracost-cloud/tagging-policies/pull-request-tags.png")} alt="Create a pull request to test your tagging policy." />
 
+From the Visibility > Pull requests page, you can also see pull requests that failed policies. Each of these pull requests would have been deployed with missing or incorrect tags had Infracost not flagged them for engineers to action. Fixing these issues before code is deployed saves significant engineering time as otherwise engineers need to create new pull requests, wait for code reviews, and re-deploy their changes.
+
 ## How tagging policies work
 
 Tagging policies check all AWS, Azure and Google Terraform resources that support tagging, including resources that Infracost does not show cost estimates for yet. The following list describes things that are checked by tagging policies:

docs/integrations/azure_repos_app.md

@@ -9,7 +9,7 @@ The Infracost Azure Repos App is an automated integration meaning that Infracost
 
 | 1. Install the Infracost Azure Repos App | 2. Get pull request comments |
 |--------------|-----------|
-<img src={useBaseUrl("img/screenshots/azure-app-install.png")} width="90%" alt="Install the Infracost Azure Repos App into any Azure organization"/> | <img src={useBaseUrl("img/screenshots/azure-app-comment.png")} alt="Infracost automatically leaves a comment on every pull request"/>
+<img src={useBaseUrl("img/screenshots/azure-app-install.png")} width="70%" alt="Install the Infracost Azure Repos App into any Azure organization"/> | <img src={useBaseUrl("img/screenshots/azure-app-comment.png")} alt="Infracost automatically leaves a comment on every pull request"/>
 
 ## Benefits
 
@@ -61,7 +61,7 @@ Each time a pull request is opened or a new commit is pushed to an open pull req
 The Azure Repos App automatically reflects the following changes in Infracost:
 - Repos that are **renamed** are updated in Infracost.
 - When a repo is **moved** from one Azure DevOps project to another, the change is reflected in Infracost as long as the projects belong to the same Azure organization.
-- Repos that are **deleted** or **archived** are marked as archived in Infracost for audit purposes. Their issues will no longer show in the dashboard.
+- Repos that are **deleted** or **disabled** (also known as archived) are marked as archived in Infracost for audit purposes. Their issues will no longer show in the dashboard.
 
 ### Disable pull request comments