From c8480863b7a64805c089a9039c17f3874cc2b0c3 Mon Sep 17 00:00:00 2001 From: Michael Flanakin Date: Fri, 12 Jul 2024 01:45:30 -0700 Subject: [PATCH] 0.4 doc updates and fixes (#816) --- .../capabilities/manage/assessment.md | 2 +- .../manage/invoicing-chargeback.md | 2 +- .../capabilities/manage/onboarding.md | 2 +- .../capabilities/manage/operations.md | 2 +- .../framework/capabilities/manage/policy.md | 2 +- .../capabilities/manage/tools-and-services.md | 2 +- .../capabilities/optimize/architecting.md | 2 +- .../capabilities/optimize/licensing.md | 3 +- .../capabilities/optimize/workloads.md | 2 +- .../framework/capabilities/quantify/README.md | 2 +- .../capabilities/quantify/benchmarking.md | 2 +- .../capabilities/quantify/planning.md | 3 +- docs/_reporting/hubs/README.md | 16 +++----- docs/_reporting/hubs/upgrade.md | 41 +++++++++++++++---- docs/_reporting/power-bi/README.md | 2 +- src/optimization-engine/ftkver.txt | 2 +- .../Private/Save-FinOpsHubTemplate.ps1 | 4 +- .../Unit/Save-FinOpsHubTemplate.Tests.ps1 | 18 ++++---- .../en-US/FinOpsToolkit.strings.psd1 | 2 +- 19 files changed, 66 insertions(+), 45 deletions(-) diff --git a/docs/_docs/framework/capabilities/manage/assessment.md b/docs/_docs/framework/capabilities/manage/assessment.md index 0b419be9f..fdf9916f5 100644 --- a/docs/_docs/framework/capabilities/manage/assessment.md +++ b/docs/_docs/framework/capabilities/manage/assessment.md @@ -4,7 +4,7 @@ grand_parent: FinOps Framework parent: Manage title: Assessment permalink: /framework/capabilities/manage/assessment -nav_order: 1 +nav_order: 6 description: This article helps you understand the FinOps assessment capability within the FinOps Framework and how to implement that in the Microsoft Cloud. author: bandersmsft ms.author: banders diff --git a/docs/_docs/framework/capabilities/manage/invoicing-chargeback.md b/docs/_docs/framework/capabilities/manage/invoicing-chargeback.md index f89fe31a0..ee6888ce3 100644 --- a/docs/_docs/framework/capabilities/manage/invoicing-chargeback.md +++ b/docs/_docs/framework/capabilities/manage/invoicing-chargeback.md @@ -4,7 +4,7 @@ grand_parent: FinOps Framework parent: Manage title: Chargeback permalink: /framework/capabilities/manage/invoicing-chargeback -nav_order: 6 +nav_order: 5 description: This article helps you understand the invoicing and chargeback capability within the FinOps Framework and how to implement that in the Microsoft Cloud. author: bandersmsft ms.author: banders diff --git a/docs/_docs/framework/capabilities/manage/onboarding.md b/docs/_docs/framework/capabilities/manage/onboarding.md index 79a318ead..9a058c826 100644 --- a/docs/_docs/framework/capabilities/manage/onboarding.md +++ b/docs/_docs/framework/capabilities/manage/onboarding.md @@ -4,7 +4,7 @@ grand_parent: FinOps Framework parent: Manage title: Onboarding permalink: /framework/capabilities/manage/onboarding -nav_order: 4 +nav_order: 3 description: This article helps you understand the onboarding workloads capability within the FinOps Framework and how to implement that in the Microsoft Cloud. author: bandersmsft ms.author: banders diff --git a/docs/_docs/framework/capabilities/manage/operations.md b/docs/_docs/framework/capabilities/manage/operations.md index 77038a066..80c6c5f86 100644 --- a/docs/_docs/framework/capabilities/manage/operations.md +++ b/docs/_docs/framework/capabilities/manage/operations.md @@ -4,7 +4,7 @@ grand_parent: FinOps Framework parent: Manage title: FinOps practice operations permalink: /framework/capabilities/manage/operations -nav_order: 1 +nav_order: 2 description: This article helps you understand the FinOps practice operations capability within the FinOps Framework and how to implement that in the Microsoft Cloud. --- diff --git a/docs/_docs/framework/capabilities/manage/policy.md b/docs/_docs/framework/capabilities/manage/policy.md index d2b40a034..fb10738c5 100644 --- a/docs/_docs/framework/capabilities/manage/policy.md +++ b/docs/_docs/framework/capabilities/manage/policy.md @@ -4,7 +4,7 @@ grand_parent: FinOps Framework parent: Manage title: Policy + governance permalink: /framework/capabilities/manage/policy -nav_order: 5 +nav_order: 4 description: This article helps you understand the cloud policy and governance capability within the FinOps Framework and how to implement that in the Microsoft Cloud. author: bandersmsft ms.author: banders diff --git a/docs/_docs/framework/capabilities/manage/tools-and-services.md b/docs/_docs/framework/capabilities/manage/tools-and-services.md index 9478101d8..4a37eb5db 100644 --- a/docs/_docs/framework/capabilities/manage/tools-and-services.md +++ b/docs/_docs/framework/capabilities/manage/tools-and-services.md @@ -4,7 +4,7 @@ grand_parent: FinOps Framework parent: Manage title: FinOps tools and services permalink: /framework/capabilities/manage/tools -nav_order: 6 +nav_order: 7 description: This article helps you understand the FinOps tools and services capability within the FinOps Framework and how to implement that in the Microsoft Cloud. --- diff --git a/docs/_docs/framework/capabilities/optimize/architecting.md b/docs/_docs/framework/capabilities/optimize/architecting.md index 441ee59ba..607216301 100644 --- a/docs/_docs/framework/capabilities/optimize/architecting.md +++ b/docs/_docs/framework/capabilities/optimize/architecting.md @@ -4,7 +4,7 @@ grand_parent: FinOps Framework parent: Optimize title: Architecting for cloud permalink: /framework/capabilities/optimize/architecting -nav_order: 3 +nav_order: 1 description: This article helps you understand the architecting for cloud capability within the FinOps Framework and how to implement that in the Microsoft Cloud. author: bandersmsft ms.author: banders diff --git a/docs/_docs/framework/capabilities/optimize/licensing.md b/docs/_docs/framework/capabilities/optimize/licensing.md index 88ddcf243..cd244e35d 100644 --- a/docs/_docs/framework/capabilities/optimize/licensing.md +++ b/docs/_docs/framework/capabilities/optimize/licensing.md @@ -4,8 +4,7 @@ grand_parent: FinOps Framework parent: Optimize title: Licensing and SaaS permalink: /framework/capabilities/optimize/licensing - -nav_order: 3 +nav_order: 4 description: This article helps you understand the licensing and SaaS capability within the FinOps Framework and how to implement that in the Microsoft Cloud. author: bandersmsft ms.author: banders diff --git a/docs/_docs/framework/capabilities/optimize/workloads.md b/docs/_docs/framework/capabilities/optimize/workloads.md index 6d3f26a47..05cff1e1f 100644 --- a/docs/_docs/framework/capabilities/optimize/workloads.md +++ b/docs/_docs/framework/capabilities/optimize/workloads.md @@ -4,7 +4,7 @@ grand_parent: FinOps Framework parent: Optimize title: Workloads permalink: /framework/capabilities/optimize/workloads -nav_order: 1 +nav_order: 2 description: This article helps you understand the Workload optimization capability within the FinOps Framework and how to implement that in the Microsoft Cloud. author: bandersmsft ms.author: banders diff --git a/docs/_docs/framework/capabilities/quantify/README.md b/docs/_docs/framework/capabilities/quantify/README.md index 1beddaa5f..b508825d5 100644 --- a/docs/_docs/framework/capabilities/quantify/README.md +++ b/docs/_docs/framework/capabilities/quantify/README.md @@ -15,7 +15,7 @@ Measure product and cloud performance and map to organizational KPIs to facilita
On this page -- [� Capabilities](#-capabilities) +- [📝 Capabilities](#-capabilities) - [⏩ Next steps](#-next-steps) - [🧰 Related tools](#-related-tools) diff --git a/docs/_docs/framework/capabilities/quantify/benchmarking.md b/docs/_docs/framework/capabilities/quantify/benchmarking.md index c8bbeab79..261194a1d 100644 --- a/docs/_docs/framework/capabilities/quantify/benchmarking.md +++ b/docs/_docs/framework/capabilities/quantify/benchmarking.md @@ -4,7 +4,7 @@ grand_parent: FinOps Framework parent: Quantify title: Benchmarking permalink: /framework/capabilities/quantify/benchmarking -nav_order: 3 +nav_order: 4 description: This article helps you understand the benchmarking capability within the FinOps Framework and how to implement that in the Microsoft Cloud. author: ripadrao ms.author: banders diff --git a/docs/_docs/framework/capabilities/quantify/planning.md b/docs/_docs/framework/capabilities/quantify/planning.md index 8879c7642..afc6ba698 100644 --- a/docs/_docs/framework/capabilities/quantify/planning.md +++ b/docs/_docs/framework/capabilities/quantify/planning.md @@ -4,7 +4,7 @@ grand_parent: FinOps Framework parent: Quantify title: Planning and estimating permalink: /framework/capabilities/quantify/planning -nav_order: 3 +nav_order: 1 description: This article helps you understand the planning and estimating capability within the FinOps Framework and how to implement that in the Microsoft Cloud. author: bandersmsft ms.author: banders @@ -22,6 +22,7 @@ This article helps you understand the planning and estimating capability within
On this page +- [✋ Before you begin](#-before-you-begin) - [▶️ Getting started](#️-getting-started) - [🏗️ Building on the basics](#️-building-on-the-basics) - [🍎 Learn more at the FinOps Foundation](#-learn-more-at-the-finops-foundation) diff --git a/docs/_reporting/hubs/README.md b/docs/_reporting/hubs/README.md index 6bbd8b51a..04cc73b9c 100644 --- a/docs/_reporting/hubs/README.md +++ b/docs/_reporting/hubs/README.md @@ -101,28 +101,22 @@ Once deployed, you can report on the data in Power BI or by connecting to the st ## ➕ Create a new hub
- _FinOps hubs 0.2 is a breaking change. To upgrade an existing hub instance, please refer to the [Upgrade guide](./upgrade.md)._ + _FinOps hubs 0.4 introduces support for FOCUS 1.0. This is **not** a breaking change and is completely backwards compatible with v0.3. To learn more, please refer to the [Upgrade guide](./upgrade.md)._
-1. **Register resource providers.** - - FinOps hubs use Event Grid and Cost Management behind the scenes. Before you deploy your template, register the `Microsoft.EventGrid` and `Microsoft.CostManagementExports` resource providers. - - [Learn more](https://docs.microsoft.com/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) - -2. **Deploy your FinOps hub.** +1. **Deploy your FinOps hub.** {% include deploy.html template="finops-hub" public="1" gov="0" china="0" %} [Learn more](../../_resources/deploy.md) -3. **Configure scopes to monitor.** +2. **Configure scopes to monitor.** FinOps hubs use Cost Management exports to load the data you want to monitor. You can configure exports manually or grant access to your hub to manage exports for you. [Learn more](./configure-scopes.md) -4. **Connect to your data.** +3. **Connect to your data.** You can connect to your data from any system that supports Azure storage. For ideas, see [get started with hubs](#-get-started-with-hubs) below. We recommend using pre-built Power BI starter templates to get started quickly. @@ -188,7 +182,7 @@ Required permissions for deploying or updating hub instances are covered in the You will need one or more of the following to export your cost data: -| Scope | Permission | +| Scope | Permission | | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Subscriptions and resource groups (all account types) | [Cost Management Contributor](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#cost-management-contributor). | | EA billing scopes | Enterprise Reader, Department Reader, or Account Owner (aka enrollment account). | diff --git a/docs/_reporting/hubs/upgrade.md b/docs/_reporting/hubs/upgrade.md index cb4f0b52c..5ebcb35c6 100644 --- a/docs/_reporting/hubs/upgrade.md +++ b/docs/_reporting/hubs/upgrade.md @@ -20,6 +20,8 @@ Upgrade an existing FinOps hub instance to the latest version to leverage new ca - [Before you begin](#before-you-begin) - [Upgrading 0.0.1](#upgrading-001) - [Upgrading 0.1.x](#upgrading-01x) +- [Upgrading 0.2](#upgrading-02) +- [Upgrading 0.3](#upgrading-03) - [⏭️ Next steps](#️-next-steps)
@@ -28,10 +30,6 @@ Upgrade an existing FinOps hub instance to the latest version to leverage new ca Upgrading a FinOps hub instance is usually the same as the initial setup but depending on what version you're moving from or to, you may have specific steps that are needed. Use the following sections to move from one version to another. If you have any questions, please [start a discussion](https://github.com/microsoft/finops-toolkit/discussions). -
- _The most common issue people face when upgrading to `0.2` is trying to use **new** Power BI reports with an **old** hub or using **old** Power BI reports with an **upgraded** hub. FinOps hubs and reports from the `0.0.1` and `0.1.x` releases are compatible, but they are not compatible with `0.2`._ -
-
## Before you begin @@ -65,6 +63,7 @@ Microsoft Online Services Agreement (MOSA, aka PAYG) and Microsoft internal subs If you have an EA or MCA account, please upgrade to `0.2` which uses the new [FOCUS](../../_docs/focus/README.md) cost data format and covers both billed (actual) and amortized costs with 30% less data size (and storage costs). This will be the baseline for all future updates. [See 0.2 upgrade instructions](#ea-and-mca-accounts-for-01x){: .btn .mb-4 .mb-md-0 .mr-4 } +[View changes](../../_resources/changelog.md#-v01){: .btn .mb-4 .mb-md-0 .mr-4 }
@@ -98,17 +97,45 @@ Before you upgrade, consider the following: - If you modified the reports, you will need to re-apply your changes to the new reports. Refer to [How to update existing reports to FOCUS](../../_docs/focus/README.md#how-to-update-existing-reports-to-focus) for details. - If you need your customized reports to continue to run while you upgrade, deploy a second instance of FinOps hubs using a different storage account to avoid data processing errors. -Based on the above, use the following steps to upgrade your hub instance from `0.1.x` to `0.2.x`: +Based on the above, use the following steps to upgrade your hub instance from `0.1.x` to `0.3`: 1. Delete any amortized cost exports pointing to your hub instance. 2. If desired, delete the historical amortized cost data to keep storage costs down. -3. Deploy FinOps hubs `0.2.1` and create new FOCUS exports using the [Create a new hub](./README.md#-create-a-new-hub) instructions. +3. Deploy FinOps hubs `0.3` and create new FOCUS exports using the [Create a new hub](./README.md#-create-a-new-hub) instructions.
_You can skip step 1 since resource providers have already been registered._
4. Backfill historical data using the FOCUS export. -[Download](https://github.com/microsoft/finops-toolkit/releases/tag/v0.2.1){: .btn .mb-4 .mb-md-0 .mr-4 } +[Download 0.3](https://github.com/microsoft/finops-toolkit/releases/tag/v0.3){: .btn .mb-4 .mb-md-0 .mr-4 } +[View changes](../../_resources/changelog.md#-v02){: .btn .mb-4 .mb-md-0 .mr-4 } + +
+ +## Upgrading 0.2 + +Upgrading FinOps hubs 0.2 to 0.4 is as simple as re-deploying the template and optionally update to the v0.3 Power BI reports. There are no breaking changes, so Power BI reports from v0.2 should work with v0.3 and vice-versa. + +[Download 0.3](https://github.com/microsoft/finops-toolkit/releases/tag/v0.3){: .btn .mb-4 .mb-md-0 .mr-4 } +[View changes](../../_resources/changelog.md#-v03){: .btn .mb-4 .mb-md-0 .mr-4 } + +
+ +## Upgrading 0.3 + +Upgrading FinOps hubs 0.3 to 0.4 is as simple as re-deploying the template and optionally update to the v0.4 Power BI reports. There are no breaking changes, so Power BI reports from v0.3 should work with v0.4 and vice-versa. + +FinOps hubs 0.4 aligns with FOCUS 1.0, so you will notice changes to the following columns: + +- ChargeCategory is "Purchase" for refunds instead of "Adjustment". +- ChargeClass (new) is "Correction" for refunds. +- CommitmentDiscountStatus (new) replaces ChargeSubcategory for commitment discount usage. +- Region is replaced by RegionId and RegionName. + +Reports work with both FOCUS 1.0 and FOCUS 1.0 preview exports, so there's no need to change exports in order to use the new reports. The reports themselves update the schema to meet FOCUS 1.0 requirements. + +[Download 0.4](https://github.com/microsoft/finops-toolkit/releases/tag/v0.4){: .btn .mb-4 .mb-md-0 .mr-4 } +[View changes](../../_resources/changelog.md#-v04){: .btn .mb-4 .mb-md-0 .mr-4 }
diff --git a/docs/_reporting/power-bi/README.md b/docs/_reporting/power-bi/README.md index 8ee253d5f..bd8ab0ff0 100644 --- a/docs/_reporting/power-bi/README.md +++ b/docs/_reporting/power-bi/README.md @@ -30,7 +30,7 @@ Accelerate your analytics efforts with simple, targeted reports. Summarize and b {% include_relative _intro.md %}
- _As of FinOps toolkit 0.2, all reports have been updated to use the FinOps Open Cost and Usage Specification (FOCUS). To learn more, see [About FOCUS](../../_docs/focus/README.md)._ + _As of FinOps toolkit 0.4, all reports have been updated to use the FinOps Open Cost and Usage Specification (FOCUS) 1.0. To use FOCUS 1.0 preview, please leverage the 0.3 toolkit release. To learn more, see [About FOCUS](../../_docs/focus/README.md)._

diff --git a/src/optimization-engine/ftkver.txt b/src/optimization-engine/ftkver.txt index 70e8e888c..e6adf3fc7 100644 --- a/src/optimization-engine/ftkver.txt +++ b/src/optimization-engine/ftkver.txt @@ -1 +1 @@ -0.2.1-rc.2 \ No newline at end of file +0.4 \ No newline at end of file diff --git a/src/powershell/Private/Save-FinOpsHubTemplate.ps1 b/src/powershell/Private/Save-FinOpsHubTemplate.ps1 index c64d3e468..76cb918a4 100644 --- a/src/powershell/Private/Save-FinOpsHubTemplate.ps1 +++ b/src/powershell/Private/Save-FinOpsHubTemplate.ps1 @@ -66,11 +66,11 @@ function Save-FinOpsHubTemplate $releases = Get-FinOpsToolkitVersion -Latest:$($Version -eq 'Latest') -Preview:$Preview ` | Where-Object { $_.Version -ne '0.2' -and ($azEnv -eq 'AzureCloud' -or $_.Version.StartsWith('0.0') -or $_.Version.StartsWith('0.1')) } # 0.2 not supported in Azure Gov/China (as of Feb 2024) - # Redirect 0.2 to 0.2.1 due to bug + # Redirect 0.2 to 0.3 due to bug if ($Version -eq '0.2') { Write-Information $LocalizedData.Hub_Deploy_02to021 - $Version = '0.2.1' + $Version = '0.3' } # TODO: Remove 0.2+ redirect for Azure Gov/China when FOCUS exports are supported diff --git a/src/powershell/Tests/Unit/Save-FinOpsHubTemplate.Tests.ps1 b/src/powershell/Tests/Unit/Save-FinOpsHubTemplate.Tests.ps1 index 367ce68c3..c3f5abaec 100644 --- a/src/powershell/Tests/Unit/Save-FinOpsHubTemplate.Tests.ps1 +++ b/src/powershell/Tests/Unit/Save-FinOpsHubTemplate.Tests.ps1 @@ -93,25 +93,25 @@ InModuleScope FinOpsToolkit { } Context 'Version redirection' { - It 'Should redirect 0.2 to 0.2.1' { + It 'Should redirect 0.2 to 0.3' { # Arrange Mock -CommandName 'Get-AzContext' { @{ Environment = @{ Name = 'AzureCloud' } } } - Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.2.1', '0.2', '0.1.1' } + Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.3', '0.2', '0.1.1' } # Act Save-FinOpsHubTemplate -Version '0.2' # Assert - Assert-MockCalled -CommandName 'Test-Path' -Times 1 -ParameterFilter { $Path.EndsWith('0.2.1.zip') } + Assert-MockCalled -CommandName 'Test-Path' -Times 1 -ParameterFilter { $Path.EndsWith('0.3.zip') } } It 'Should redirect 0.2 to 0.1.1 for Azure Gov' { # Arrange Mock -CommandName 'Get-AzContext' { @{ Environment = @{ Name = 'AzureGov' } } } - Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.2.1', '0.2', '0.1.1' } + Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.3', '0.2', '0.1.1' } # Act - Save-FinOpsHubTemplate -Version '0.2.1' + Save-FinOpsHubTemplate -Version '0.3' # Assert Assert-MockCalled -CommandName 'Test-Path' -Times 1 -ParameterFilter { $Path.EndsWith('0.1.1.zip') } @@ -120,10 +120,10 @@ InModuleScope FinOpsToolkit { It 'Should redirect 0.2 to 0.1.1 for Azure China' { # Arrange Mock -CommandName 'Get-AzContext' { @{ Environment = @{ Name = 'AzureChina' } } } - Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.2.1', '0.2', '0.1.1' } + Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.3', '0.2', '0.1.1' } # Act - Save-FinOpsHubTemplate -Version '0.2.1' + Save-FinOpsHubTemplate -Version '0.3' # Assert Assert-MockCalled -CommandName 'Test-Path' -Times 1 -ParameterFilter { $Path.EndsWith('0.1.1.zip') } @@ -132,7 +132,7 @@ InModuleScope FinOpsToolkit { It 'Should support 0.1.1 for Azure Gov' { # Arrange Mock -CommandName 'Get-AzContext' { @{ Environment = @{ Name = 'AzureGov' } } } - Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.2.1', '0.2', '0.1.1' } + Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.3', '0.2', '0.1.1' } # Act Save-FinOpsHubTemplate -Version '0.1.1' @@ -144,7 +144,7 @@ InModuleScope FinOpsToolkit { It 'Should support 0.1.1 for Azure China' { # Arrange Mock -CommandName 'Get-AzContext' { @{ Environment = @{ Name = 'AzureChina' } } } - Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.2.1', '0.2', '0.1.1' } + Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.3', '0.2', '0.1.1' } # Act Save-FinOpsHubTemplate -Version '0.1.1' diff --git a/src/powershell/en-US/FinOpsToolkit.strings.psd1 b/src/powershell/en-US/FinOpsToolkit.strings.psd1 index f8acc9801..d3d760475 100644 --- a/src/powershell/en-US/FinOpsToolkit.strings.psd1 +++ b/src/powershell/en-US/FinOpsToolkit.strings.psd1 @@ -12,7 +12,7 @@ ConvertFrom-StringData -StringData @' Hub_Deploy_Deploy = Deploying FinOps hub '{0}' to resource group '{1}'. Hub_Deploy_TemplateNotFound = Could not find template 'main.bicep' at path '{0}'. Hub_Deploy_02to011 = Version 0.2 is not supported for Azure Gov and Azure China due to FOCUS exports not being available in Cost Management yet. Using version 0.1.1 instead. - Hub_Deploy_02to021 = Version 0.2 is not supported due to a bug in the deployment template. Using version 0.2.1 instead. + Hub_Deploy_02to021 = Version 0.2 is not supported due to a bug in the deployment template. Using version 0.3 instead. Hub_Remove_Failed = FinOps hub could not be deleted. {0}. Hub_Remove_NotFound = FinOps hub '{0}' not found.