Skip to content

README.md

Latest commit

 

History

History
542 lines (364 loc) · 22.3 KB

README.md

File metadata and controls

542 lines (364 loc) · 22.3 KB
Raw

📜 FinOps toolkit scripts

FinOps toolkit scripts are used for local development, testing, and publishing only.

On this page:

🆕 Init-Repo

Init-Repo.ps1 initializes your local dev environment with the following tools, which are required for development and testing:

  • Az PowerShell module
  • Bicep CLI

The following optional apps/modules can be installed with the corresponding parameters or with the ‑All parameter:

  • Visual Studio Code
  • Bicep PowerShell module
  • NodeJS and configured modules (-NPM parameter)
  • Pester PowerShell module

If an app or module is already installed, it will be skipped. To see which apps would be installed, use the -WhatIf parameter.

Examples:

  • Checks to see what apps/modules would be installed:

    ./Init-Repo -All -WhatIf

  • Installs only required apps/modules:

    ./Init-Repo

  • Installs all required and specific apps/modules:

    ./Init-Repo -VSCode -NPM -Pester

  • Installs all required and optional apps/modules:

    ./Init-Repo -All

🌐 Build-OpenData

Build-OpenData.ps1 generates data files, PowerShell commands, and FinOps hubs KQL functions for open data. PowerShell commands are private and not shared externally today – they're meant to be used by other specifically-designed commands, which is outside the scope of Build-OpenData. FinOps hubs KQL functions are available from the hub Ingestion database. File updates must be manually checked in and the script only needs to be run when datasets are added or updated.

Examples:

  • Build all PowerShell functions:

    ./Build-OpenData

  • Build one PowerShell function:

    ./Build-OpenData -Name Regions

  • Build data files only:

    ./Build-OpenData -Data

  • Build FinOps hubs KQL functions only:

    ./Build-OpenData -Hubs

    After running this script, if new open data KQL files are created, you will need to also update dataExplorer.bicep to include them in the Data Explorer deployment.

  • Build data files and PowerShell functions:

    ./Build-OpenData -All

  • Run PowerShell tests after the build completes:

    ./Build-OpenData -Test

📦 Build-Toolkit

Build-Toolkit.ps1 builds toolkit modules and templates for local testing and and to prepare them for publishing.

Examples:

  • Build all toolkit modules and templates:

    ./Build-Toolkit

  • Build all toolkit modules and templates from any directory via NPM:

    npm run build

  • Build all toolkit modules and templates from VS Code:

    Ctrl+Shift+P > Run Build Task > Build Toolkit

Build-Toolkit runs the following scripts internally:


🚀 Deploy-Hub

Deploy-Hub.ps1 is a wrapper around Deploy-Toolkit that simplifies FinOps hub deployments by providing scenario-based flags instead of requiring you to remember all the Bicep parameter names.

By default, deploys with Azure Data Explorer (dev SKU). Use -StorageOnly for storage-only or -Fabric for Fabric-based deployments.

All resources use an {initials}-{name} naming convention where initials are pulled from git config user.name and name defaults to adx. Pass a name as the first positional parameter to use a custom value (e.g., 216 for Feb 16).

Parameter Description
‑Name Optional. First positional parameter. Suffix for {initials}-{name} convention. Default: adx.
‑HubName Optional. Name of the hub instance. Default: hub.
‑ADX Optional. Name of the Azure Data Explorer cluster. Overrides the {initials}-{name} convention.
‑ResourceGroup Optional. Name of the resource group. Overrides the {initials}-{name} convention.
‑Fabric Optional. Deploy with Microsoft Fabric. Provide the eventhouse query URI.
‑StorageOnly Optional. Deploy a storage-only hub (no Azure Data Explorer or Fabric).
‑Remove Optional. Remove test environments. With a name, deletes the target RG. Alone, lists all {initials}-*.
‑PR Optional. PR number for CI deployments. Resources are named pr-{number} or pr-{number}-{name} when -Name is also specified.
‑Scope Optional. Azure scope ID for cost data exports (e.g., /subscriptions/{id}). With -ManagedExports, enables managed exports. Without it, creates exports manually.
‑ManagedExports Optional. Use managed exports instead of manual exports. Requires -Scope. Passes scopesToMonitor to the template and grants the hub identity required roles.
‑Location Optional. Azure location. Default: westus.
‑Build Optional. Build the template before deploying.
‑WhatIf Optional. Validate the deployment without making changes.

Examples:

  • Deploy a hub with ADX (e.g., RG aa-adx, ADX aa-adx):

    ./Deploy-Hub

  • Deploy to a named environment (e.g., RG aa-216, ADX aa-216):

    ./Deploy-Hub 216

  • Deploy a storage-only hub:

    ./Deploy-Hub -StorageOnly

  • Deploy with Microsoft Fabric:

    ./Deploy-Hub -Fabric "https://my-eventhouse.kusto.data.microsoft.com"

  • Build the template first, then deploy:

    ./Deploy-Hub -Build

  • Clean up a specific test environment (e.g., aa-210):

    ./Deploy-Hub -Remove 210

  • List all test environments:

    ./Deploy-Hub -Remove

  • Deploy with PR naming convention (e.g., RG pr-123-adx, ADX pr-123-adx):

    ./Deploy-Hub -PR 123 -Name adx

  • Deploy with managed exports:

    ./Deploy-Hub -PR 123 -Name adx -Scope "/subscriptions/{id}" -ManagedExports -Build

  • Deploy storage-only with manual exports:

    ./Deploy-Hub -StorageOnly -Scope "/subscriptions/{id}" -Build

🚀 Deploy-Toolkit

Deploy-Toolkit.ps1 deploys toolkit templates for local testing purposes.

Parameter Description
‑Template Required. Name of the template or module to deploy. Default = finops-hub.
‑ResourceGroup Optional. Name of the resource group to deploy to. Will be created if it doesn't exist. Default = ftk-<username>-<computername>.
‑Location Optional. Azure location to execute the deployment from. Default = westus.
‑Parameters Optional. Parameters to pass thru to the deployment. Defaults per template/module are configured in the script.
‑Build Optional. Indicates whether the the Build-Toolkit command should be executed first. Default = false.
‑Test Optional. Indicates whether to run the template or module test instead of the template or module itself. Default = false.
‑Debug Optional. Writes script execution troubleshooting details to console. Does not execute deployment.
‑WhatIf Optional. Validates the deployment without executing it or changing resources.

Examples:

  • Basic template deployment validation (requires resource group to exist):

    ./Deploy-Toolkit -WhatIf

  • Deploy a specific template:

    ./Deploy-Toolkit "finops-hub"

  • Build and deploy a Bicep Registry module test:

    ./Deploy-Toolkit "subscription-scheduled-action" -Build -Test

  • Build and deploy a module from any directory via NPM:

    npm run deploy "finops-hub"

  • Build and deploy a module test (main.test.bicep file) from any directory via NPM:

    npm run deploy-test "finops-hub"

🧪 Test-PowerShell

Test-PowerShell.ps1 runs Pester tests.

By default, only unit tests are run. If only one test type is specified, only that test type will be run. If multiple are specified, each of them will be run. Other options will apply to all test types that are selected. Select -AllTests to run all test types.

To investigate the previous test run, use $global:ftk_TestPowerShell_Results.

To view a summary of only the failed tests, use $global:ftk_TestPowerShell_Summary.

To view the configuration used to re-run previously failed tests, use $global:ftk_TestPowerShell_FailedTests.

Parameter Description
‑Cost Optional. Indicates whether to run Cost Management tests.
‑Data Optional. Indicates whether to run open data tests.
‑Exports Optional. Indicates whether to run Cost Management export tests.
‑FOCUS Optional. Indicates whether to run FOCUS tests.
‑Hubs Optional. Indicates whether to run FinOps hubs tests.
‑Toolkit Optional. Indicates whether to run generic toolkit tests.
‑Integration Optional. Indicates whether to run integration tests, which take more time than unit tests by testing external dependencies. Default = false.
‑Lint Optional. Indicates whether to run lint tests, which validate local files are meeting dev standards. Default = false.
‑Unit Optional. Indicates whether to run unit tests. Default = true.
‑AllTests Optional. Indicates whether to run all lint, unit, and integration tests. If set, this overrides Lint, Unit, and Integration options. Default = false.

Examples:

  • Run all unit tests:

    ./Test-PowerShell

  • Run all integration tests:

    ./Test-PowerShell -Integration

  • Run unit and integration tests for a specific area:

    ./Test-PowerShell -Hubs -Integration

  • Run all tests:

    ./Test-PowerShell -AllTests

  • Re-run failed tests:

    ./Test-PowerShell -RunFailed

🏷️ Get-Version

Get-Version.ps1 gets the latest version of the toolkit.

Parameter Description
‑AsDotNetVersion Optional. Indicates that the returned version should be in the format "x.x.x.x". Otherwise, semantic versioning is used. Deafult = false.

Example:

./Get-Version

🏷️ Update-Version

Update-Version.ps1 updates the toolkit version in the following places:

  • NPM (central tracking for the version)
  • PowerShell's private Get-VersionNumber command (used for internal version number usage)
  • All ftkver.txt files in the repo (used for templates and docs)
Parameter Description
‑Major Optional. Increments the major version number (x.0).
‑Minor Optional. Increments the minor version number (0.x).
‑Patch Optional. Increments the patch version number (0.0.x).
‑Prerelease Optional. Increments the prerelease version number (0.0.0-ooo.x).
‑Label Optional. Indicates the label to use for prerelease versions. Allowed: dev, rc, alpha, preview. Default = "dev".
‑Version Optional. Sets the version number to an explicit value.

Examples:

  • Increments the major version number (for example, 1.0 to 2.0).

    ./Update-Version -Major

  • Increments the prerelease version number with an "alpha" preview label (for example, 1.0 to 1.0.1-alpha).

    ./Update-Version -Prerelease -Label "alpha"

🚚 Publish-Toolkit

Publish-Toolkit.ps1 publishes a toolkit template, module, or documentation to its destination repo.

Parameter Description
‑Template Optional. Name of the template or module to publish. Default = * (all templates).
‑QuickstartRepo Optional. Name of the folder where the Azure Quickstart Templates repo is cloned. Default = azure-quickstart-templates.
‑RegistryRepo Optional. Name of the folder where the Bicep Registry repo is cloned. Default = bicep-registry-modules.
‑AppInsightsRepo Optional. Name of the folder where the Application Insights Workbooks repo is cloned. Default = Application-Insights-Workbooks.
‑DocsRepo Optional. Name of the folder where the Partner Center documentation repo is cloned. Default = partner-center-pr.
‑Build Optional. Indicates whether the Build-Toolkit command should be executed first. Default = false.
‑Branch Optional. Indicates whether the changes should be committed to a new branch in the Git repo. Alias: Commit. Default = false.

Examples:

  • Builds and publishes the FinOps hub template to the Azure Quickstart Templates repo, commits changes, and pushes to the fork to prepare for a PR.

    ./Publish-Toolkit "finops-hub" -Build -Commit

  • Builds and publishes the resource group scheduled action module to the Bicep Registry repo locally but does not commit.

    ./Publish-Toolkit "resourcegroup-scheduled-action" -Build

  • Publishes documentation to the Microsoft Learn repo locally but does not commit.

    ./Publish-Toolkit "docs"

📦 Package-Toolkit

Package-Toolkit.ps1 packages all toolkit templates as ZIP files for release.

Parameter Description
‑Template Optional. Name of the template or module to package. Default = * (all).
‑Build Optional. Indicates whether the Build-Toolkit command should be executed first. Default = false.
‑PowerBI Optional. Indicates whether to open Power BI files as part of the packaging process. Default = false.
‑Preview Optional. Indicates that the template(s) should be saved as a preview only. Does not package other files. Default = false.

Examples:

  • Generate ZIP files for each template using an existing build.

    ./Package-Toolkit

  • Builds the latest code and generates ZIP files for each template.

    ./Package-Toolkit -Build

  • Builds the latest version of a specific template and updates the deployment files for the website.

    ./Package-Toolkit finops-workbooks -Build -Preview

©️ Add-CopyrightHeader

Add-CopyrightHeader.ps1 checks all files to ensure they have a copyright header. Generates a summary of the number of files checked, files updated, and file types that are not supported. Run this script whenever adding new code files.

If unsupported file types are found, the script needs to be updated to either specify the comment character(s) or ignore the file type.

To specify the comment character(s), update the $fileTypes variable:

$fileTypes = @{
    "bicep" = "//"
    "ps1"   = "#"
    "psd1"  = "#"
    "psm1"  = "#"
}

To ignore a file type, add it to the Get-ChildItem -Exclude list:

Get-ChildItem `
    -Path ../ `
    -Recurse `
    -Include *.* `
    -Exclude *.abf, *.bim, .buildignore, .gitignore, *.json, *.md, *.pbidataset, *.pbip, *.pbir, *.pbix, *.png, *.svg `
    -File

📁 New-Directory

New-Directory.ps1 creates a new directory without failing if it already exists and without writing data to the console.

Example:

./New-Directory "C:\Temp\NewDirectory"

🌿 New-FeatureBranch

New-FeatureBranch.ps1 creates a new feature branch.

Example:

./New-FeatureBranch "foo"

🔀 Merge-DevBranch

Merge-DevBranch.ps1 merges the dev branch into the specified branch.

Parameter Description
‑Branch Optional. Name of the branch to merge into. Default = "." (current branch).
‑TortoiseGit Optional. Indicates whether to use TortoiseGit to resolve conflicts. Default = false.
‑Silent Optional. Indicates whether to hide informational output. Will abort merge if there are any conflicts. Use $LASTEXITCODE to determine status (0 = successful, 1 = error, 2 = conflicts). Default = false.

Examples:

  • Merge the dev branch into the current branch.

    ./Merge-DevBranch

  • Merge the dev branch into the features/foo branch and uses TortoiseGit to resolve conflicts.

    ./Merge-DevBranch features/foo -TortoiseGit

  • Merge the dev branch into all feature branches. Does not resolve conflicts.

    ./Merge-DevBranch *