Share via

Microsoft.CostManagement budgets 2023-11-01

Bicep resource definition

The budgets resource type can be deployed with operations that target:

For a list of changed properties in each API version, see change log.

Resource format

To create a Microsoft.CostManagement/budgets resource, add the following Bicep to your template.

resource symbolicname 'Microsoft.CostManagement/budgets@2023-11-01' = {
  scope: resourceSymbolicName or scope
  eTag: 'string'
  name: 'string'
  properties: {
    amount: int
    category: 'string'
    filter: {
      and: [
        {
          dimensions: {
            name: 'string'
            operator: 'string'
            values: [
              'string'
            ]
          }
          tags: {
            name: 'string'
            operator: 'string'
            values: [
              'string'
            ]
          }
        }
      ]
      dimensions: {
        name: 'string'
        operator: 'string'
        values: [
          'string'
        ]
      }
      tags: {
        name: 'string'
        operator: 'string'
        values: [
          'string'
        ]
      }
    }
    notifications: {
      {customized property}: {
        contactEmails: [
          'string'
        ]
        contactGroups: [
          'string'
        ]
        contactRoles: [
          'string'
        ]
        enabled: bool
        frequency: 'string'
        locale: 'string'
        operator: 'string'
        threshold: int
        thresholdType: 'string'
      }
    }
    timeGrain: 'string'
    timePeriod: {
      endDate: 'string'
      startDate: 'string'
    }
  }
}

Property Values

Microsoft.CostManagement/budgets

Name Description Value
eTag eTag of the resource. To handle concurrent update scenario, this field will be used to determine whether the user is updating the latest version or not. string
name The resource name string

Constraints:
Min length = 1
Max length = 63
Pattern = ^[a-zA-Z0-9_-]+$ (required)
properties The properties of the budget. BudgetProperties
scope Use when creating a resource at a scope that is different than the deployment scope. Set this property to the symbolic name of a resource to apply the extension resource.

BudgetComparisonExpression

Name Description Value
name The name of the column to use in comparison. string (required)
operator The operator to use for comparison. 'In' (required)
values Array of values to use for comparison string[] (required)

BudgetFilter

Name Description Value
and The logical "AND" expression. Must have at least 2 items.

Supported for CategoryType(s): Cost.		 BudgetFilterProperties[]
dimensions Has comparison expression for a dimension.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported dimension names for CategoryType: ReservationUtilization
- ReservationId
- ReservedResourceType		 BudgetComparisonExpression
tags Has comparison expression for a tag.

Supported for CategoryType(s): Cost.		 BudgetComparisonExpression

BudgetFilterProperties

Name Description Value
dimensions Has comparison expression for a dimension.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported dimension names for CategoryType: ReservationUtilization
- ReservationId
- ReservedResourceType		 BudgetComparisonExpression
tags Has comparison expression for a tag.

Supported for CategoryType(s): Cost.		 BudgetComparisonExpression

BudgetProperties

Name Description Value
amount The total amount of cost to track with the budget.

Supported for CategoryType(s): Cost.

Required for CategoryType(s): Cost.		 int
category The category of the budget.
- 'Cost' defines a Budget.
- 'ReservationUtilization' defines a Reservation Utilization Alert Rule.		 'Cost'
'ReservationUtilization' (required)
filter May be used to filter budgets by user-specified dimensions and/or tags.

Supported for CategoryType(s): Cost, ReservationUtilization.		 BudgetFilter
notifications Dictionary of notifications associated with the budget.

Supported for CategoryType(s): Cost, ReservationUtilization.

- Constraints for CategoryType: Cost - Budget can have up to 5 notifications with thresholdType: Actual and 5 notifications with thresholdType: Forecasted.
- Constraints for CategoryType: ReservationUtilization - Only one notification allowed. thresholdType is not applicable.		 BudgetPropertiesNotifications
timeGrain The time covered by a budget. Tracking of the amount will be reset based on the time grain.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported timeGrainTypes for CategoryType: Cost

- Monthly
- Quarterly
- Annually
- BillingMonth*
- BillingQuarter*
- BillingAnnual*

*only supported for Web Direct customers.

Supported timeGrainTypes for CategoryType: ReservationUtilization
- Last7Days
- Last30Days

Required for CategoryType(s): Cost, ReservationUtilization.		 'Annually'
'BillingAnnual'
'BillingMonth'
'BillingQuarter'
'Last30Days'
'Last7Days'
'Monthly'
'Quarterly' (required)
timePeriod The time period that defines the active period of the budget. The budget will evaluate data on or after the startDate and will expire on the endDate.

Supported for CategoryType(s): Cost, ReservationUtilization.

Required for CategoryType(s): Cost, ReservationUtilization.		 BudgetTimePeriod (required)

BudgetPropertiesNotifications

Name Description Value

BudgetTimePeriod

Name Description Value
endDate The end date for the budget.

- Constraints for CategoryType: Cost - No constraints. If not provided, we default this to 10 years from the start date.

- Constraints for CategoryType: ReservationUtilization - End date cannot be more than 3 years after the start date.		 string
startDate The start date for the budget.

- Constraints for CategoryType: Cost - Must be first of the month and should be less than the end date. Budget start date must be on or after June 1, 2017. Future start date should not be more than twelve months. Past start date should be selected within the timegrain period.

- Constraints for CategoryType: ReservationUtilization - Must be on or after the current date and less than the end date.		 string (required)

Notification

Name Description Value
contactEmails Email addresses to send the notification to when the threshold is breached. Must have at least one contact email or contact group specified at the Subscription or Resource Group scopes. All other scopes must have at least one contact email specified.

Supported for CategoryType(s): Cost, ReservationUtilization.		 string[] (required)
contactGroups Subscription or Resource Group scopes only. Action groups to send the notification to when the threshold is exceeded. Must be provided as a fully qualified Azure resource id.

Supported for CategoryType(s): Cost.		 string[]
contactRoles Subscription or Resource Group scopes only. Contact roles to send the notification to when the threshold is breached.

Supported for CategoryType(s): Cost.		 string[]
enabled The notification is enabled or not.

Supported for CategoryType(s): Cost, ReservationUtilization.		 bool (required)
frequency Frequency of a notification. Represents how long the notification will be silent after triggering an alert for a threshold breach. If not specified, the frequency will be set by default based on the timeGrain (Weekly when timeGrain: Last7Days, Monthly when timeGrain: Last30Days).

Supported for CategoryType(s): ReservationUtilization.		 'Daily'
'Monthly'
'Weekly'
locale Language in which the recipient will receive the notification,

Supported for CategoryType(s): Cost, ReservationUtilization.		 'cs-cz'
'da-dk'
'de-de'
'en-gb'
'en-us'
'es-es'
'fr-fr'
'hu-hu'
'it-it'
'ja-jp'
'ko-kr'
'nb-no'
'nl-nl'
'pl-pl'
'pt-br'
'pt-pt'
'ru-ru'
'sv-se'
'tr-tr'
'zh-cn'
'zh-tw'
operator The comparison operator.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported operators for CategoryType: Cost
- GreaterThan
- GreaterThanOrEqualTo

Supported operators for CategoryType: ReservationUtilization
- LessThan		 'EqualTo'
'GreaterThan'
'GreaterThanOrEqualTo'
'LessThan' (required)
threshold Threshold value associated with a notification. It is always percent with a maximum of 2 decimal places.

Supported for CategoryType(s): Cost, ReservationUtilization.

CategoryType: Cost - Must be between 0 and 1000. Notification is sent when the cost exceeded the threshold.

CategoryType: ReservationUtilization - Must be between 0 and 100. Notification is sent when a reservation has a utilization percentage below the threshold.		 int (required)
thresholdType The type of threshold.

Supported for CategoryType(s): Cost.		 'Actual'
'Forecasted'

ARM template resource definition

The budgets resource type can be deployed with operations that target:

For a list of changed properties in each API version, see change log.

Resource format

To create a Microsoft.CostManagement/budgets resource, add the following JSON to your template.

{
  "type": "Microsoft.CostManagement/budgets",
  "apiVersion": "2023-11-01",
  "name": "string",
  "eTag": "string",
  "properties": {
    "amount": "int",
    "category": "string",
    "filter": {
      "and": [
        {
          "dimensions": {
            "name": "string",
            "operator": "string",
            "values": [ "string" ]
          },
          "tags": {
            "name": "string",
            "operator": "string",
            "values": [ "string" ]
          }
        }
      ],
      "dimensions": {
        "name": "string",
        "operator": "string",
        "values": [ "string" ]
      },
      "tags": {
        "name": "string",
        "operator": "string",
        "values": [ "string" ]
      }
    },
    "notifications": {
      "{customized property}": {
        "contactEmails": [ "string" ],
        "contactGroups": [ "string" ],
        "contactRoles": [ "string" ],
        "enabled": "bool",
        "frequency": "string",
        "locale": "string",
        "operator": "string",
        "threshold": "int",
        "thresholdType": "string"
      }
    },
    "timeGrain": "string",
    "timePeriod": {
      "endDate": "string",
      "startDate": "string"
    }
  }
}

Property Values

Microsoft.CostManagement/budgets

Name Description Value
apiVersion The api version '2023-11-01'
eTag eTag of the resource. To handle concurrent update scenario, this field will be used to determine whether the user is updating the latest version or not. string
name The resource name string

Constraints:
Min length = 1
Max length = 63
Pattern = ^[a-zA-Z0-9_-]+$ (required)
properties The properties of the budget. BudgetProperties
type The resource type 'Microsoft.CostManagement/budgets'

BudgetComparisonExpression

Name Description Value
name The name of the column to use in comparison. string (required)
operator The operator to use for comparison. 'In' (required)
values Array of values to use for comparison string[] (required)

BudgetFilter

Name Description Value
and The logical "AND" expression. Must have at least 2 items.

Supported for CategoryType(s): Cost.		 BudgetFilterProperties[]
dimensions Has comparison expression for a dimension.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported dimension names for CategoryType: ReservationUtilization
- ReservationId
- ReservedResourceType		 BudgetComparisonExpression
tags Has comparison expression for a tag.

Supported for CategoryType(s): Cost.		 BudgetComparisonExpression

BudgetFilterProperties

Name Description Value
dimensions Has comparison expression for a dimension.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported dimension names for CategoryType: ReservationUtilization
- ReservationId
- ReservedResourceType		 BudgetComparisonExpression
tags Has comparison expression for a tag.

Supported for CategoryType(s): Cost.		 BudgetComparisonExpression

BudgetProperties

Name Description Value
amount The total amount of cost to track with the budget.

Supported for CategoryType(s): Cost.

Required for CategoryType(s): Cost.		 int
category The category of the budget.
- 'Cost' defines a Budget.
- 'ReservationUtilization' defines a Reservation Utilization Alert Rule.		 'Cost'
'ReservationUtilization' (required)
filter May be used to filter budgets by user-specified dimensions and/or tags.

Supported for CategoryType(s): Cost, ReservationUtilization.		 BudgetFilter
notifications Dictionary of notifications associated with the budget.

Supported for CategoryType(s): Cost, ReservationUtilization.

- Constraints for CategoryType: Cost - Budget can have up to 5 notifications with thresholdType: Actual and 5 notifications with thresholdType: Forecasted.
- Constraints for CategoryType: ReservationUtilization - Only one notification allowed. thresholdType is not applicable.		 BudgetPropertiesNotifications
timeGrain The time covered by a budget. Tracking of the amount will be reset based on the time grain.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported timeGrainTypes for CategoryType: Cost

- Monthly
- Quarterly
- Annually
- BillingMonth*
- BillingQuarter*
- BillingAnnual*

*only supported for Web Direct customers.

Supported timeGrainTypes for CategoryType: ReservationUtilization
- Last7Days
- Last30Days

Required for CategoryType(s): Cost, ReservationUtilization.		 'Annually'
'BillingAnnual'
'BillingMonth'
'BillingQuarter'
'Last30Days'
'Last7Days'
'Monthly'
'Quarterly' (required)
timePeriod The time period that defines the active period of the budget. The budget will evaluate data on or after the startDate and will expire on the endDate.

Supported for CategoryType(s): Cost, ReservationUtilization.

Required for CategoryType(s): Cost, ReservationUtilization.		 BudgetTimePeriod (required)

BudgetPropertiesNotifications

Name Description Value

BudgetTimePeriod

Name Description Value
endDate The end date for the budget.

- Constraints for CategoryType: Cost - No constraints. If not provided, we default this to 10 years from the start date.

- Constraints for CategoryType: ReservationUtilization - End date cannot be more than 3 years after the start date.		 string
startDate The start date for the budget.

- Constraints for CategoryType: Cost - Must be first of the month and should be less than the end date. Budget start date must be on or after June 1, 2017. Future start date should not be more than twelve months. Past start date should be selected within the timegrain period.

- Constraints for CategoryType: ReservationUtilization - Must be on or after the current date and less than the end date.		 string (required)

Notification

Name Description Value
contactEmails Email addresses to send the notification to when the threshold is breached. Must have at least one contact email or contact group specified at the Subscription or Resource Group scopes. All other scopes must have at least one contact email specified.

Supported for CategoryType(s): Cost, ReservationUtilization.		 string[] (required)
contactGroups Subscription or Resource Group scopes only. Action groups to send the notification to when the threshold is exceeded. Must be provided as a fully qualified Azure resource id.

Supported for CategoryType(s): Cost.		 string[]
contactRoles Subscription or Resource Group scopes only. Contact roles to send the notification to when the threshold is breached.

Supported for CategoryType(s): Cost.		 string[]
enabled The notification is enabled or not.

Supported for CategoryType(s): Cost, ReservationUtilization.		 bool (required)
frequency Frequency of a notification. Represents how long the notification will be silent after triggering an alert for a threshold breach. If not specified, the frequency will be set by default based on the timeGrain (Weekly when timeGrain: Last7Days, Monthly when timeGrain: Last30Days).

Supported for CategoryType(s): ReservationUtilization.		 'Daily'
'Monthly'
'Weekly'
locale Language in which the recipient will receive the notification,

Supported for CategoryType(s): Cost, ReservationUtilization.		 'cs-cz'
'da-dk'
'de-de'
'en-gb'
'en-us'
'es-es'
'fr-fr'
'hu-hu'
'it-it'
'ja-jp'
'ko-kr'
'nb-no'
'nl-nl'
'pl-pl'
'pt-br'
'pt-pt'
'ru-ru'
'sv-se'
'tr-tr'
'zh-cn'
'zh-tw'
operator The comparison operator.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported operators for CategoryType: Cost
- GreaterThan
- GreaterThanOrEqualTo

Supported operators for CategoryType: ReservationUtilization
- LessThan		 'EqualTo'
'GreaterThan'
'GreaterThanOrEqualTo'
'LessThan' (required)
threshold Threshold value associated with a notification. It is always percent with a maximum of 2 decimal places.

Supported for CategoryType(s): Cost, ReservationUtilization.

CategoryType: Cost - Must be between 0 and 1000. Notification is sent when the cost exceeded the threshold.

CategoryType: ReservationUtilization - Must be between 0 and 100. Notification is sent when a reservation has a utilization percentage below the threshold.		 int (required)
thresholdType The type of threshold.

Supported for CategoryType(s): Cost.		 'Actual'
'Forecasted'

Usage Examples

Terraform (AzAPI provider) resource definition

The budgets resource type can be deployed with operations that target:

For a list of changed properties in each API version, see change log.

Resource format

To create a Microsoft.CostManagement/budgets resource, add the following Terraform to your template.

resource "azapi_resource" "symbolicname" {
  type = "Microsoft.CostManagement/budgets@2023-11-01"
  name = "string"
  parent_id = "string"
  body = {
    eTag = "string"
    properties = {
      amount = int
      category = "string"
      filter = {
        and = [
          {
            dimensions = {
              name = "string"
              operator = "string"
              values = [
                "string"
              ]
            }
            tags = {
              name = "string"
              operator = "string"
              values = [
                "string"
              ]
            }
          }
        ]
        dimensions = {
          name = "string"
          operator = "string"
          values = [
            "string"
          ]
        }
        tags = {
          name = "string"
          operator = "string"
          values = [
            "string"
          ]
        }
      }
      notifications = {
        {customized property} = {
          contactEmails = [
            "string"
          ]
          contactGroups = [
            "string"
          ]
          contactRoles = [
            "string"
          ]
          enabled = bool
          frequency = "string"
          locale = "string"
          operator = "string"
          threshold = int
          thresholdType = "string"
        }
      }
      timeGrain = "string"
      timePeriod = {
        endDate = "string"
        startDate = "string"
      }
    }
  }
}

Property Values

Microsoft.CostManagement/budgets

Name Description Value
eTag eTag of the resource. To handle concurrent update scenario, this field will be used to determine whether the user is updating the latest version or not. string
name The resource name string

Constraints:
Min length = 1
Max length = 63
Pattern = ^[a-zA-Z0-9_-]+$ (required)
parent_id The ID of the resource to apply this extension resource to. string (required)
properties The properties of the budget. BudgetProperties
type The resource type "Microsoft.CostManagement/budgets@2023-11-01"

BudgetComparisonExpression

Name Description Value
name The name of the column to use in comparison. string (required)
operator The operator to use for comparison. 'In' (required)
values Array of values to use for comparison string[] (required)

BudgetFilter

Name Description Value
and The logical "AND" expression. Must have at least 2 items.

Supported for CategoryType(s): Cost.		 BudgetFilterProperties[]
dimensions Has comparison expression for a dimension.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported dimension names for CategoryType: ReservationUtilization
- ReservationId
- ReservedResourceType		 BudgetComparisonExpression
tags Has comparison expression for a tag.

Supported for CategoryType(s): Cost.		 BudgetComparisonExpression

BudgetFilterProperties

Name Description Value
dimensions Has comparison expression for a dimension.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported dimension names for CategoryType: ReservationUtilization
- ReservationId
- ReservedResourceType		 BudgetComparisonExpression
tags Has comparison expression for a tag.

Supported for CategoryType(s): Cost.		 BudgetComparisonExpression

BudgetProperties

Name Description Value
amount The total amount of cost to track with the budget.

Supported for CategoryType(s): Cost.

Required for CategoryType(s): Cost.		 int
category The category of the budget.
- 'Cost' defines a Budget.
- 'ReservationUtilization' defines a Reservation Utilization Alert Rule.		 'Cost'
'ReservationUtilization' (required)
filter May be used to filter budgets by user-specified dimensions and/or tags.

Supported for CategoryType(s): Cost, ReservationUtilization.		 BudgetFilter
notifications Dictionary of notifications associated with the budget.

Supported for CategoryType(s): Cost, ReservationUtilization.

- Constraints for CategoryType: Cost - Budget can have up to 5 notifications with thresholdType: Actual and 5 notifications with thresholdType: Forecasted.
- Constraints for CategoryType: ReservationUtilization - Only one notification allowed. thresholdType is not applicable.		 BudgetPropertiesNotifications
timeGrain The time covered by a budget. Tracking of the amount will be reset based on the time grain.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported timeGrainTypes for CategoryType: Cost

- Monthly
- Quarterly
- Annually
- BillingMonth*
- BillingQuarter*
- BillingAnnual*

*only supported for Web Direct customers.

Supported timeGrainTypes for CategoryType: ReservationUtilization
- Last7Days
- Last30Days

Required for CategoryType(s): Cost, ReservationUtilization.		 'Annually'
'BillingAnnual'
'BillingMonth'
'BillingQuarter'
'Last30Days'
'Last7Days'
'Monthly'
'Quarterly' (required)
timePeriod The time period that defines the active period of the budget. The budget will evaluate data on or after the startDate and will expire on the endDate.

Supported for CategoryType(s): Cost, ReservationUtilization.

Required for CategoryType(s): Cost, ReservationUtilization.		 BudgetTimePeriod (required)

BudgetPropertiesNotifications

Name Description Value

BudgetTimePeriod

Name Description Value
endDate The end date for the budget.

- Constraints for CategoryType: Cost - No constraints. If not provided, we default this to 10 years from the start date.

- Constraints for CategoryType: ReservationUtilization - End date cannot be more than 3 years after the start date.		 string
startDate The start date for the budget.

- Constraints for CategoryType: Cost - Must be first of the month and should be less than the end date. Budget start date must be on or after June 1, 2017. Future start date should not be more than twelve months. Past start date should be selected within the timegrain period.

- Constraints for CategoryType: ReservationUtilization - Must be on or after the current date and less than the end date.		 string (required)

Notification

Name Description Value
contactEmails Email addresses to send the notification to when the threshold is breached. Must have at least one contact email or contact group specified at the Subscription or Resource Group scopes. All other scopes must have at least one contact email specified.

Supported for CategoryType(s): Cost, ReservationUtilization.		 string[] (required)
contactGroups Subscription or Resource Group scopes only. Action groups to send the notification to when the threshold is exceeded. Must be provided as a fully qualified Azure resource id.

Supported for CategoryType(s): Cost.		 string[]
contactRoles Subscription or Resource Group scopes only. Contact roles to send the notification to when the threshold is breached.

Supported for CategoryType(s): Cost.		 string[]
enabled The notification is enabled or not.

Supported for CategoryType(s): Cost, ReservationUtilization.		 bool (required)
frequency Frequency of a notification. Represents how long the notification will be silent after triggering an alert for a threshold breach. If not specified, the frequency will be set by default based on the timeGrain (Weekly when timeGrain: Last7Days, Monthly when timeGrain: Last30Days).

Supported for CategoryType(s): ReservationUtilization.		 'Daily'
'Monthly'
'Weekly'
locale Language in which the recipient will receive the notification,

Supported for CategoryType(s): Cost, ReservationUtilization.		 'cs-cz'
'da-dk'
'de-de'
'en-gb'
'en-us'
'es-es'
'fr-fr'
'hu-hu'
'it-it'
'ja-jp'
'ko-kr'
'nb-no'
'nl-nl'
'pl-pl'
'pt-br'
'pt-pt'
'ru-ru'
'sv-se'
'tr-tr'
'zh-cn'
'zh-tw'
operator The comparison operator.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported operators for CategoryType: Cost
- GreaterThan
- GreaterThanOrEqualTo

Supported operators for CategoryType: ReservationUtilization
- LessThan		 'EqualTo'
'GreaterThan'
'GreaterThanOrEqualTo'
'LessThan' (required)
threshold Threshold value associated with a notification. It is always percent with a maximum of 2 decimal places.

Supported for CategoryType(s): Cost, ReservationUtilization.

CategoryType: Cost - Must be between 0 and 1000. Notification is sent when the cost exceeded the threshold.

CategoryType: ReservationUtilization - Must be between 0 and 100. Notification is sent when a reservation has a utilization percentage below the threshold.		 int (required)
thresholdType The type of threshold.

Supported for CategoryType(s): Cost.		 'Actual'
'Forecasted'