Skip to content

Usage Basic

Jump to bottom
Kamil Mrzygłód edited this page Feb 6, 2023 · 12 revisions

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 ./templates:/app thecloudtheory/azure-cost-estimator:latest templates/acr.json <subscription-id> arm-estimator-tests-rg

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

  • authentication to Azure
  • Docker volume which maps a directory with your template to /app directory within container

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>

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 must use the following three required parameters:

Name Default value Example Description
template-file N/A some_path/some_file.json Path to the template file (must be in JSON format)
subscription-id N/A 11c43ee8-b9d3-4e51-b73f-bd9dda66e29c Identifier (GUID) of your subscription
resource-group N/A mygroup-rg Name of the resource group
Clone this wiki locally