Options

Options are non-mandatory parameters, which provide extended functionality for the project. Detailed information how they work can be found below

Name	Default value	Example	Description
--mode	`--mode Incremental`	`Complete`	Deployment mode used for calculation. Supports `Incremenetal` and `Complete` deployments
--threshold	`-1`	`--threshold 3000`	Max acceptable estimated cost. Exceeding threshold causes a non-zero exit code to be reported
--parameters	`null`	`--parameters some_path/params.parameters.json`	Path to the parameters file (must be in JSON format)
--currency	`USD`	`--currency EUR`	Currency code to use for estimations
--generateJsonOutput	`false`	`--generateJsonOutput`	Generates JSON file containing estimation result
--silent	`false`	`--silent`	Silences logs so no information is returned to console
--stdout	`false`	`--stdout`	Redirects generated output to stdout instead of file
--disableDetailedMetrics	`false`	`--disableDetailedMetrics`	Disables detailed metrics of estimated resource cost
--jsonOutputFilename	`null`	`--jsonOutputFilename estimationOutput`	Sets a name of JSON output file created when `--generateJsonOutput` is enabled
--generateHtmlOutput	`false`	`--generateHtmlOutput`	Generates HTML file with estimation result
--inline	`null`	`--inline param1=value1 --inline param2=value2`	Passes parameters inline instead of relying on hardcoded values in parameters file
--htmlOutputFilename	`null`	`--htmlOutputFilename htmlOutputFile`	Sets a name of HTML output file created when `--generateHtmlOutput` is enabled
--outputFormat	`Default`	`--outputFormat Table`	Sets output format
--disable-cache	`false`	`--disable-cache true`	Disables cache
--tf-executable	`null`	`--tf-executable /usr/bin/terraform`	Customizes path of Terraform executable. If omitted, ACE will look for executable in PATH
--conversion-rate	`1.0`	`--conversion-rate 2.0`	Allows you to define USD -> your currency conversion rate, which is used across some calculations
--cache-handler	`Local`	`--cache-handler AzureStorage`	Configures cache handler
--cache-storage-account-name	`null`	`--cache-storage-account-name myaccount`	Configures Azure Storage account name for Azure Storage cache handler
--webhook-url	`null`	`--webhook-url http://localhost:12345`	Configures webhook URL used to send estimates to
--webhook-authorization	`null`	`--webhook-authorization "Bearer ey..."`	Configures value of `Authorization` header used when sending estimation to webhook URL
--configuration-file	`null`	`--configuration-file "my-file.json"`	Defines a path to local file containing ACE configuration
--what-if-file	`null`	`--what-if-file "what-if.json"`	Allows you to pass a user-generated What If file
--markdown-output-filename	`null`	`--mardown-output-filename "file.md"`	Defines the name for the Markdown file generated by ACE
--generate-markdown-output	`null`	`--generate-markdown-output`	Enables generating Markdown file as output

Deployment mode

Available from: 1.0.0-alpha2

When performing resource group level deployment there's an option to select a deployment mode. ACE also supports that option by providing desired value as parameter:

arm-estimator <template-path>.json <subscription-id> <resource-group> --mode Incremental|Complete

When parameter is not passed, Incremental mode is selected. Selecting Complete changes the way estimations work - if there're existing resources in a resource group, they will be considered as up for removal. It'll be noted by ARM Cost Estimator and deducted from the final estimation.

Threshold

Available from: 1.0.0-alpha3

With ACE it's possible to stop your CICD process is projected estimation exceeds your assumptions:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --threshold <int>

By using --threshold option, you can set an upper limit for infrastructure cost and make sure, that you can re-evaluate changes before they reach cloud environment and affect your billing.

If estimation exceeds configured threshold, ARM Cost Estimator exits with status code 1. Make sure you check against returned status code and handle that scenario properly.

Configuring threshold is optional - if you omit it, your CICD process will continue ignoring estimation value.

Parameters

Available from: 1.0.0-alpha4

Very often templates contain parameters, which have different values depending on the selected environment. Sometimes you just need to pass a value, which is generated outside your template. ARM Cost Estimator supports parameters in the same way as you'd normally develop them and pass for deployment:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --parameters <path-to-your-parameters-file>.json

Both ARM Templates and Bicep use parameters defined as JSON files. ACE expects parameters file to be passed without changes, even though Azure What If API expects sending parameters with slightly different schema than parameters file itself.

When using ACE, you parameters file should look like this:

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "dbName": {
      "value": "db"
    },
    "location": {
      "value": "westeurope"
    },
    "sku": {
      "value": "Basic"
    }
  }
}

Do not transform it to the schema expected by What If API (which expects value of the parameters parameter only).

Currency

Available from: 1.0.0-beta1

It's possible to use one of the supported currencies to display estimation result in appropriate format:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --currency EUR

For now, you can use one of the following currency codes:

Code	Name
USD	US dollar
AUD	Australian dollar
BRL	Brazilian real
CAD	Canadian dollar
CHF	Swiss franc
CNY	Chinese yuan
DKK	Danish krone
EUR	Euro
GBP	British pound
INR	Indian rupee
JPY	Japanese yen
KRW	Korean won
NOK	Norwegian krone
NZD	New Zealand dollar
RUB	Russian ruble
SEK	Swedish krona
TWD	Taiwan dollar

Support for a given currency depends on capabilities of underlying Azure Retail API.

JSON output

Available from: 1.0.0-beta1

If you want to use estimation for further automation, it's possible to generate a JSON file containing basic information about estimated resources using --generateJsonOutput option:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --generateJsonOutput

If that option is set to true, once all data is obtained, a JSON file is created:

{
    "TotalCost": 119.3248,
    "Delta": 119.3248,
    "TotalResourceCount": 5,
    "EstimatedResourceCount": 3,
    "SkippedResourceCount": 2,
    "Resources": [
        {
            "Id": "/subscriptions/.../Microsoft.Compute/virtualMachines/ace-vm-01",
            "TotalCost": 29.93,
            "Delta": 29.93
        },
        {
            "Id": "/subscriptions/.../Microsoft.Compute/virtualMachines/ace-vm-02",
            "TotalCost": 63.51,
            "Delta": 63.51
        },
        {
            ...
        }
    ],
    "Currency": "USD"
}

Name of the file contains a UTC timestamp - ace_estimation_yyyyMMddHHssmm.json - but the file is overwritten if the same timestamp would be used twice.

Silent mode

Available from: 1.0.0-beta2

If you don't want any output to be visible in console, you can use --silent option for enabling silent mode:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --silent

Special use case of that option is using it with output redirection:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --generateJsonOutput --stdout --silent

As output redirected to stdout is always considered as non-silent, you can get e.g. estimation JSON without all the noise coming from the tool.

Output redirection

Available from: 1.0.0-beta2

If you don't want an output file to be generated, you can use --stdout option to redirect generated output to stdout:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --generateJsonOutput --stdout

This is especially useful when using estimation output as input for another command or process.

Disabling detailed metrics

Available from: 1.0.0-beta3

By default, ACE reports all aggregated metrics, so you can understand in details how cost was calculated. In scenarios, when you're interested in estimated price only, you can disable detailed metrics for smaller output using --disableDetailedMetrics option:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --disableDetailedMetrics

When this option is enabled, the following output:

[Create] acestg28271
   \--- Type: Microsoft.Storage/storageAccounts
   \--- Location: EU West
   \--- Total cost: 0.25 USD
   \--- Delta: +0.25 USD

Aggregated metrics:

-> Standard LRS | Tables | LRS Data Stored | 0.045 for 1 GB/Month
-> Standard LRS | Queues v2 | LRS Data Stored | 0.045 for 1 GB/Month
-> Standard LRS | General Block Blob | LRS Data Stored | 0.024 for 1 GB/Month
...
-> Standard LRS | General Block Blob | LRS List and Create Container Operations | 0.00036 for 10K
-> Standard LRS | General Block Blob | Read Operations - Free | 0 for 10K
-> Standard LRS | General Block Blob | LRS Write Operations - Free | 0 for 10K

Will be replaced with:

[Create] acestg28271
   \--- Type: Microsoft.Storage/storageAccounts
   \--- Location: EU West
   \--- Total cost: 0.25 USD
   \--- Delta: +0.25 USD

JSON output filename

Available from: 1.0.0-beta4

If you want, you can change the default name of JSON output file created when --generateJsonOutput option is enabled:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --generateJsonOutput --jsonOutputFilename my_estimation_file

When --jsonOutputFilename is set, ACE will use provided custom name as the filename of JSON output file. Custom file is automatically saved as JSON, however timestamp is not automatically appended to its name.

HTML output

Available from: 1.0.0-beta4

While JSON output may be useful in scenarios when you want to process estimation result, sometimes you just need a prettier version of estimated result for attachment or report. To generate pretty HTML output with estimated cost, you may use --generateHtmlOutput option:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --generateHtmlOutput

Once estimation is completed, ACE will generate an HTML file with result data available in the working directory.

ACE comes with HTML template available for further customization. If you don't like how the result file looks like, you can modify Html/GeneratorTemplate.html file in any way you want. Remember not to remove ### [] ### placeholders!

Inline parameters

Available from: 1.0.0-beta5

In many scenarios, you want to pass parameters inline instead of providing them via parameters file. Main use case is use of secureString type as including secrets in your codebase is considered a bad practice. ACE supports inline parameters by passing them with --inline option:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --inline param1=value1 --inline param2=value2 --inline param3=value3

Each inline parameter must be provided as parameterName=parameterValue in order to be parsed correctly. Parameters must be named exactly as they're named in your ARM Template / Bicep file, for instance:

param location string = resourceGroup().location
param singleLineObject object
param exampleArray array

@secure()
param adminPassword string
param adminLogin string
param minCapacity int

resource dbserver 'Microsoft.Sql/servers@2021-11-01-preview' = {
  name: 'sqlserver'
  location: location
  properties: {
    administratorLogin: adminLogin
    administratorLoginPassword: adminPassword
  }
}

resource dbbasic 'Microsoft.Sql/servers/databases@2021-11-01-preview' = {
  parent: dbserver
  name: 'ace-db'
  location: location
  sku: {
    name: 'Basic'
  }
  properties: {
    minCapacity: minCapacity
  }
}

Will be estimated with the following command:

azure-cost-estimator <template-path>.bicep <subscription-id> <resource-group> \
--inline adminPassword=verysecretpassword123 \
--inline adminLogin=adminace \
--inline minCapacity=3 \
--inline singleLineObject={"name": "test name", "id": "123-abc", "isCurrent": true, "tier": 1} \
--inline exampleArray=["1", "2", "3"]

Avoid passing objects / array as strings as they need to be parsed correctly as JSON.

Dry run

Available from: 1.0

If you want to perform only template validation / check for changes, use --dry-run parameter, which skips estimation part:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --dry-run

When dry run is enabled, ACE performs only What If check and returns its result. No further actions are performed (including JSON / HTML output generation).

HTML output filename

Available from: 1.2-beta1

If you want, you can change the default name of HTML output file created when --generateHtmlOutput option is enabled:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --generateHtmlOutput --htmlOutputFilename my_output_file

When --htmlOutputFilename is set, ACE will use provided custom name as the filename of HTML output file. Custom file is automatically saved as HTML, however timestamp is not automatically appended to its name.

Output format

Available from: 1.2-beta1

It's possible to change the default output format to other formatting if you find it difficult to read. To use Table formatting, pass --outputFormat option like below:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --outputFormat Table

Available values for --outputFormat may differ depending on the ACE version you're using. For now, there're two types available:

Default
Table

Note, that output formatting may not affect the whole output. The actual behavior heavily rely on implementation of the given formatter. Example output when using a Table formatter will look like so:

                                  Estimations                                   
┌────────┬─────────────────────┬────────────────────────────┬─────┬──────┬─────┐
│ Change │ Resource name       │ Resource type              │ Lo… │ Tot… │ De… │
│ type   │                     │                            │     │ cost │     │
├────────┼─────────────────────┼────────────────────────────┼─────┼──────┼─────┤
│ Create │ sqldbt6381189164663 │ Microsoft.Sql/servers/data │ EU  │ 4.83 │ +4. │
│        │ 33974               │ bases                      │ Wes │ USD  │ 83  │
│        │                     │                            │ t   │      │ USD │
└────────┴─────────────────────┴────────────────────────────┴─────┴──────┴─────┘
                                 Free Resources                                 
┌─────────────────┬───────────────────────────────┬────────────────────────────┐
│ Change type     │ Resource name                 │ Resource type              │
├─────────────────┼───────────────────────────────┼────────────────────────────┤
│ Create          │ svrt638118916466333963        │ Microsoft.Sql/servers      │
└─────────────────┴───────────────────────────────┴────────────────────────────┘

Disable cache

Available from: 1.2-beta2

By default, ACE caches What If responses to speed up a little bit process of estimating cost of your infrastructure. You can opt-out that behavior by using --disabled-cache option:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --disable-cache true

This option can be also use to invalidate cache if there were changes outside of your template.

Cache works only with What If responses meaning when using ACE with Terraform, cache functionality doesn't have any impact on calculation times .

Terraform executable path

Available from: 1.3

By default, ACE looks for Terraform executable in PATH. You can change that behavior by using the following option:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --tf-executable /usr/bin/terraform

Remember, that path to Terraform executable changes depending on the installation method and OS used.

Conversion rate

Available from: 1.3

Some calculations (like Hybrid Benefit) use a fixed price to determine cost of a resource. That cost is represented as USD price of a feature or service meaning it'll introduce noise to cost estimation when non-USD currency is used. To avoid that, provide a currency rate:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --currency-rate 1.2

Once available, ACE will use that currency rate to adjust calculation.

Cache handler

Available from: 1.3

Depending on the desired cache solution, you can define used handler using following option:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --cache-handler "AzureStorage"

Read about details of each cache handler here.

Configuration file

Available from: 1.4

Allows you to pass configuration file instead of inline parameters. This is helpful if you're using rich configuration and find inline parameters difficult to read. Example:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --configuration-file "dir/config.json"

Note some remarks:

Configuration file must be a JSON file containing specific schema
You cannot pass both inline parameters and use configuration file. However, this is true to some extent - ACE expects, that template parameters passed via --inline option and --webhook-authorization will be still passed as inline parameters. See example below.

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --configuration-file "dir/config.json" \
  --inline "password=foo" \
  --webhook-authorization "Bearer eyJs7s..."

The schema for the file:

{
    "Mode": 0,
    "Threshold": null,
    "Parameters": null,
    "Currency": 0,
    "GenerateJsonOutput": false,
    "Silent": false,
    "Stdout": false,
    "DisableDetailedMetrics": false,
    "JsonOutputFilename": null,
    "GenerateHtmlOutput": false,
    "DryRun": false,
    "HtmlOutputFilename": null,
    "OutputFormat": 0,
    "DisableCache": false,
    "TfExecutable": null,
    "ConversionRate": 0,
    "CacheHandler": 0,
    "CacheStorageAccountName": null,
    "WebhookUrl": null,
    "LogFile": null
}

User-generated What If file

Available from: 1.5

By default ACE automatically obtains responses from What If API to perform estimations. As you don't control that process, you may find it undesired, especially, if What If responses are somehow already generated in your CICD pipelines. To disable automated What If API requests, you may pass --what-if-file option:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --what-if-file "mocked-responses/what-if/automation-account.json"

As result, ACE will report, that What If data is loaded from the provided file:

What If status:

-> Cache miss for What If data.
-> What If data loaded from provided file mocked-responses/what-if/automation-account.json.
-> Detected 1 resources.

Note, that your file MUST be in certain schema (Azure CLI and PowerShell already generate correct output) and be a JSON file. For instance, you could generate valid output by running the following command:

az deployment group what-if --template-file automation-parameters.bicep --exclude-change-types Ignore NoChange -g arm-estimator-tests-rg --no-pretty-print

The result JSON output can be safely saved as a file and provided as an input for ACE.

Markdown output

Available from: 1.5

Allows you to generate Markdown output for the estimation generated by ACE:

azure-cost-estimator <template-path>.json <subscription-id> <resource-group> --generate-markdown-output --markdown-output-filename "some_file.md"

If you don't provide a custom name for the output file, ACE will generate a random one.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Options

Deployment mode

Threshold

Parameters

Currency

JSON output

Silent mode

Output redirection

Disabling detailed metrics

JSON output filename

HTML output

Inline parameters

Dry run

HTML output filename

Output format

Disable cache

Terraform executable path

Conversion rate

Cache handler

Configuration file

User-generated What If file

Markdown output

Clone this wiki locally