Usage Basic

You can use the project with both ARM Templates and with Bicep files. In general, ACE doesn't care if you want to use old-school ARM Template or Bicep, however if you face any issues, you can transform Bicep file to ARM Template with help of Bicep CLI:

bicep build <your-bicep-file>.bicep

Alternatively you can use Azure CLI, which comes with in-built Azure Bicep support:

az bicep build --file <your-bicep-file>.bicep

This will create an ARM Template based on the Bicep file passed as argument.

Native Bicep support is available since 1.0.0-beta2 version. Starting with version 1.0, ACE tries to compile Bicep file using Bicep CLI and falls backs to Azure CLI.

If you want to use Bicep files and pass them directly to ACE, make sure you've installed Bicep CLI / Azure CLI before. This is especially important for build agents, which may have limited capabilities and don't include Bicep by default. In case of any problems, fall back to ARM Templates.

Windows

azure-cost-estimator.exe <template-path>.json|.bicep <subscription-id> <resource-group>

Linux / OSX

./azure-cost-estimator <template-path>.json|.bicep <subscription-id> <resource-group>

Docker

Running ACE as Docker container has following benefits:

• you can run it on any host supporting Docker
• you don't need to manually download executable
• there's no need to install Bicep CLI as it's bundled within running container

However, when running a container with ACE, there're additional things to think about. Here's an example of starting ACE as container:

docker run -e AZURE_CLIENT_ID=$(Client_Id) -e AZURE_TENANT_ID=$(Tenant_Id) -e AZURE_CLIENT_SECRET=$(Client_Secret) -v $(pwd)/templates:/app/templates thecloudtheory/azure-cost-estimator templates/acr.bicep <subscription-id> <resource-group-name>

Using above command, you can run ACE with default values for options. Once container runs, it'll log all estimation information to stdout. However, when Docker container is used, you must configure two elements by yourself:

• authentication to Azure
• mounted directory with your template to /app/<your-directory> directory within container

Additional things to consider:

• If you don't provide an absolute path for host path, Docker will create a named volume, which won't be connect to a host directory. Provide a full path so a bind mount is created instead.
• You need to map local directory to /app/<your-directory> instead of /app as /app is a working directory where ACE run within a container. Hence using /app will overwrite all the binaries and dotnet won't be able to find an executable.
• When using Bicep with private modules, make sure you have bicepconfig.json file configured to allow environment variables as source of credentials.

See this and this issue for more information.

Under the hood, ACE uses Azure.Identity package for handling authentication. As containers run as isolated hosts, by default they don't have access to e.g. Managed Identity configured for you agent. The easiest way is to leverage EnvironmentCredentials as presented above, however if you somehow expose a running container to its host, you may use other ways of authentication.

There're three ways of configuring EnvironmentCredentials within a running container:

• setup variables AZURE_CLIENT_ID, AZURE_TENANT_ID and AZURE_CLIENT_SECRET
• setup variables AZURE_CLIENT_ID, AZURE_TENANT_ID and AZURE_CLIENT_CERTIFICATE_PATH
• setup variables AZURE_USERNAME and AZURE_PASSWORD

Which method is used, is transparent to the estimation process.

Deployment scopes

By default, ACE uses a resource group as deployment target. However, there're additional commands, which can be used for switching target to a higher-level construct like subscription, management group or tenant. You can use any defined option with each command.

Note, that deployment on higher scopes may require additional permissions, which needs to be granted to the principal running ACE.

Subscription

./azure-cost-estimator sub <template-path>.json|.bicep <subscription-id> <location>

Management group

./azure-cost-estimator mg <template-path>.json|.bicep <management-group-id>

Management group

./azure-cost-estimator tenant <template-path>.json|.bicep

GitHub Action Workflows

This repository contains a Reusable Workflow that can easily be integrated into your existing GitHub Actions Workflow.

Simply add this new job to your workflow, using your own URL's.

  CostEstimate:
    uses: TheCloudTheory/arm-estimator/.github/workflows/estimateFromUrl.yml@main
    with:
      rg: 'MyResourceGroup'
      environment: '' #Use empty string for repo level secrets
      templateFileURL: https://github.com/Azure/AKS-Construction/releases/download/0.9.4/main.json
      templateParamFileURL: https://raw.githubusercontent.com/Azure/AKS-Construction/main/.github/workflows_dep/AksDeploy-Private.parameters.json
    secrets:
      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
      AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

The referenced secrets are required to be created in your repository, see this documentation for more information.

Parameters

When using ACE, you can use the following parameters. Their usage depends on the selected deployment scope.

Name	Default value	Example	Description
template-file	N/A	some_path/some_file.json/.bicep	Path to the template file (must be in JSON or Bicep format)
subscription-id	N/A	11c43ee8-b9d3-4e51-b73f-bd9dda66e29c	Identifier (GUID) of your subscription
management-group	N/A	11c43ee8-b9d3-4e51-b73f-bd9dda66e29c	Identifier (GUID) or name of management group
location	N/A	westeurope	Deployment location (applicable to subscription / management group / tenant deployment only)
resource-group	N/A	mygroup-rg	Name of the resource group