Azure Cost

Azure Cost Management Skill

Unified skill for all Azure cost management tasks: querying historical costs, forecasting future spending, and optimizing to reduce waste.

When to Use This Skill

Activate this skill when user wants to:

• Query or analyze Azure costs (how much am I spending, show my bill, cost breakdown)
• Break down costs by service, resource, location, or tag
• Analyze cost trends over time
• Forecast future Azure spending or project end-of-month costs
• Optimize Azure costs, reduce spending, or find savings
• Find orphaned or unused resources
• Rightsize Azure VMs, containers, or services
• Generate cost optimization reports

Quick Reference

MCP Tools

💡 Tip: Prefer MCP tools over direct CLI commands. Use az rest only when MCP tools don't cover the specific operation.

---

Routing

Read the user's request and follow the appropriate workflow below.

Important: When optimizing costs, always present the total bill and cost breakdown alongside optimization recommendations.

---

Scope Reference (Shared Across All Workflows)

💡 Tip: These are scope paths only — not complete URLs. Combine with the API endpoint and version.

---

Part 1: Cost Query Workflow

For the full cost query workflow (scope selection, report types, timeframes, dataset configuration, API calls, pagination, guardrails, examples, and error handling), see:

📄 [Cost Query Workflow](cost-query/workflow.md)

---

Part 2: Cost Optimization Workflow

For the full cost optimization workflow (prerequisites, best practices, Redis/AKS-specific analysis, Azure Quick Review, resource discovery, cost queries, pricing validation, utilization metrics, and report generation), see:

📄 [Cost Optimization Workflow](cost-optimization/workflow.md)

---

Part 3: Cost Forecast Workflow

For the full cost forecast workflow (scope selection, time period rules, dataset configuration, forecast-specific options, API calls, response interpretation, guardrails, and error handling), see:

📄 [Cost Forecast Workflow](cost-forecast/workflow.md)

---

Data Classification

• ACTUAL DATA = Retrieved from Azure Cost Management API
• ACTUAL METRICS = Retrieved from Azure Monitor
• VALIDATED PRICING = Retrieved from official Azure pricing pages
• ESTIMATED SAVINGS = Calculated based on actual data and validated pricing

Best Practices

• Always query actual costs first — never estimate or assume
• Always present the total bill alongside optimization recommendations
• Validate pricing from official sources — account for free tiers
• Use REST API for cost queries (more reliable than az costmanagement query)
• Always include the ClientType: GitHubCopilotForAzure header on all Cost Management API requests (--headers "ClientType=GitHubCopilotForAzure" in az rest)
• Save audit trail — include all queries and responses
• Include Azure Portal links for all resources
• For costs < $10/month, emphasize operational improvements over financial savings
• Never execute destructive operations without explicit approval
• On 429 responses, check all x-ms-ratelimit-microsoft.costmanagement-*-retry-after headers (qpu-retry-after, entity-retry-after, tenant-retry-after), wait for the longest value, and do not retry until that duration has elapsed. The per-scope limit (4 requests/minute) is the most restrictive.

Common Pitfalls

• Assuming costs: Always query actual data from Cost Management API
• Ignoring free tiers: Many services have generous allowances
• Using wrong date ranges: 30 days for costs, 14 days for utilization
• Not showing the bill: Always present cost breakdown alongside optimization recommendations
• Cost query failures: Use az rest with JSON body, not az costmanagement query

Safety Requirements

• Get approval before deleting resources
• Test changes in non-production first
• Provide dry-run commands for validation
• Include rollback procedures

SDK Quick References

• Redis Management: .NET

Forecast API Error Handling

HTTP Status Codes

Validation Error Reference

Forecast-Specific Scenarios

Retry Strategy

⚠️ Warning: Do not retry any errors except 429. All other errors indicate issues that must be fixed before re-attempting the request.

Forecast API Examples

Common forecast patterns with request bodies. Use the SKILL.md workflow to construct and execute the az rest command.

1. Forecast Rest of Current Month (Daily)

{
  "type": "ActualCost",
  "timeframe": "Custom",
  "timePeriod": {
    "from": "<first-of-month>",
    "to": "<last-of-month>"
  },
  "dataset": {
    "granularity": "Daily",
    "aggregation": {
      "totalCost": { "name": "Cost", "function": "Sum" }
    },
    "sorting": [
      { "direction": "Ascending", "name": "UsageDate" }
    ]
  },
  "includeActualCost": true,
  "includeFreshPartialCost": true
}

💡 Tip: Set from to the first of the month — the response contains Actual rows up to today and Forecast rows for remaining days.

---

2. Forecast Next 3 Months (Monthly)

{
  "type": "ActualCost",
  "timeframe": "Custom",
  "timePeriod": {
    "from": "<first-of-month>",
    "to": "<3-months-out>"
  },
  "dataset": {
    "granularity": "Monthly",
    "aggregation": {
      "totalCost": { "name": "Cost", "function": "Sum" }
    },
    "sorting": [
      { "direction": "Ascending", "name": "BillingMonth" }
    ]
  },
  "includeActualCost": true,
  "includeFreshPartialCost": true
}

💡 Tip: Monthly granularity uses the BillingMonth column in the response.

---

3. Forecast for Resource Group Scope

{
  "type": "ActualCost",
  "timeframe": "Custom",
  "timePeriod": {
    "from": "<start-date>",
    "to": "<end-date>"
  },
  "dataset": {
    "granularity": "Daily",
    "aggregation": {
      "totalCost": { "name": "Cost", "function": "Sum" }
    },
    "sorting": [
      { "direction": "Ascending", "name": "UsageDate" }
    ]
  },
  "includeActualCost": true,
  "includeFreshPartialCost": true
}

💡 Tip: Scope is set at the URL level. Use the resource group scope URL to limit the forecast.

---

4. Forecast for Billing Account Scope

{
  "type": "ActualCost",
  "timeframe": "Custom",
  "timePeriod": {
    "from": "<start-date>",
    "to": "<end-date>"
  },
  "dataset": {
    "granularity": "Monthly",
    "aggregation": {
      "totalCost": { "name": "Cost", "function": "Sum" }
    },
    "sorting": [
      { "direction": "Ascending", "name": "BillingMonth" }
    ]
  },
  "includeActualCost": true,
  "includeFreshPartialCost": true
}

💡 Tip: Use URL pattern /providers/Microsoft.Billing/billingAccounts/<id>/.... Monthly granularity recommended for billing account forecasts.

---

Scope URL Reference

💡 Tip: These are path-only patterns — not complete URLs. Append ?api-version=2023-11-01 when constructing the full request URL.

Forecast API Guardrails

Detailed guardrails derived from CCM-LUX getForecastData and CCM-UX-MIDDLEWARE Forecaster.

Time Period Validation

⚠️ Warning: If both from and to are in the past, the API returns CantForecastOnThePast. At least the to date must be in the future.

Training Data Requirements

⚠️ Warning: New subscriptions with fewer than 28 days of cost history cannot generate forecasts. Suggest using the Cost Query workflow (Part 1) to retrieve available historical data instead.

Grouping Restriction

⚠️ Warning: Even when using the Cost Query workflow (Part 1) for grouped historical data, ResourceId grouping is only supported at subscription scope and below. It is not supported at billing account, management group, or higher scopes.

Response Row Limit

💡 Tip: If the user needs a daily forecast for more than 2–3 weeks, consider splitting the request into smaller time windows or switching to monthly granularity.

includeActualCost / includeFreshPartialCost

⚠️ Warning: Setting includeFreshPartialCost=true without includeActualCost=true produces validation error DontContainIncludeActualCostWhileIncludeFreshPartialCost. Always set both fields explicitly.

Forecast Availability

The API returns "Forecast is unavailable for the specified time period" when:

⚠️ Warning: This is not an error — it is a valid response indicating the forecast model cannot generate predictions. Do not retry. Instead, suggest using the Cost Query workflow (Part 1) to retrieve whatever historical data is available.

Rate Limiting

Rate Limit Thresholds

The Forecast API shares the same rate limits as the Cost Query API:

⚠️ Warning: The per-scope limit (4 requests/minute) is the most restrictive. Sequential queries to the same subscription, resource group, or billing account share this limit.

Rate Limit Headers

Handling 429 Responses

On a 429 response, check all retry-after headers present in the response. Multiple headers may be returned simultaneously. Take the maximum value and do NOT retry until that duration has fully elapsed.

⚠️ Warning: Do not retry before the retry-after duration has elapsed. Premature retries will be rejected and may extend the throttling period.

Forecast API Request Body Schema

Complete JSON Schema

{
  "type": "ActualCost",
  "timeframe": "Custom",
  "timePeriod": {
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-03-31T00:00:00Z"
  },
  "dataset": {
    "granularity": "Daily",
    "aggregation": {
      "totalCost": {
        "name": "Cost",
        "function": "Sum"
      }
    },
    "sorting": [
      {
        "direction": "Ascending",
        "name": "UsageDate"
      }
    ],
    "filter": {
      "dimensions": {
        "name": "ResourceGroupName",
        "operator": "In",
        "values": ["my-resource-group"]
      }
    }
  },
  "includeActualCost": true,
  "includeFreshPartialCost": true
}

Field Reference

Forecast-Specific Fields

includeActualCost

• Type: boolean
• Default: true
• When true, the response includes historical actual cost rows from the from date up to today, alongside projected forecast rows from today to the to date.
• When false, only forecast (projected) rows are returned.

includeFreshPartialCost

• Type: boolean
• Default: true
• When true, includes partial (incomplete) cost data for the most recent days where billing data is still arriving.
• ⚠️ Requires `includeActualCost=true`. Setting includeFreshPartialCost=true without includeActualCost=true produces a validation error (DontContainIncludeActualCostWhileIncludeFreshPartialCost).

Response Structure

Response Columns

CostStatus Values

Granularity and Date Column Mapping

Key Differences from Query API Request Body

Cost Forecast Workflow

Use this workflow when the user wants to project future costs.

⚠️ Warning: If the user wants historical cost data, use the Cost Query Workflow. If they want to reduce costs, use the Cost Optimization Workflow.

Key Differences from Query API

Step 1: Determine Scope

Use the same scope patterns from the Scope Reference table in the main SKILL.md.

Step 2: Choose Report Type

ActualCost is most common for forecasting. AmortizedCost for reservation/savings plan projections.

Step 3: Set Time Period

⚠️ Warning: The to date MUST be in the future.

• Set timeframe to Custom and provide timePeriod with from and to dates
• from can be in the past — shows actual costs up to today, then forecast to to
• Minimum 28 days of historical cost data required
• Maximum forecast period: 10 years

Full rules: Forecast Guardrails

Step 4: Configure Dataset

• Granularity: Daily or Monthly recommended
• Aggregation: Typically Sum of Cost
• See Forecast Request Body Schema for full schema

⚠️ Warning: Grouping is NOT supported for forecast. Suggest using the Cost Query Workflow for grouped historical data instead.

Step 5: Set Forecast-Specific Options

Step 6: Construct and Execute

Create `temp/cost-forecast.json`:

{
  "type": "ActualCost",
  "timeframe": "Custom",
  "timePeriod": {
    "from": "<first-of-month>",
    "to": "<last-of-month>"
  },
  "dataset": {
    "granularity": "Daily",
    "aggregation": {
      "totalCost": { "name": "Cost", "function": "Sum" }
    },
    "sorting": [{ "direction": "Ascending", "name": "UsageDate" }]
  },
  "includeActualCost": true,
  "includeFreshPartialCost": true
}

Execute:

New-Item -ItemType Directory -Path "temp" -Force

az rest --method post `
  --url "/subscriptions/<subscription-id>/providers/Microsoft.CostManagement/forecast?api-version=2023-11-01" `
  --headers "ClientType=GitHubCopilotForAzure" `
  --body '@temp/cost-forecast.json'

Step 7: Interpret Response

💡 Tip: "Forecast is unavailable for the specified time period" is not an error — it means the scope has insufficient historical data. Suggest using the Cost Query Workflow for available data.

Key Guardrails

Full details: Forecast Guardrails

Error Handling

Full details: Forecast Error Handling

For more forecast examples, see forecast examples.

Azure Authentication Best Practices

Source: Microsoft — Passwordless connections for Azure services and Azure Identity client libraries.

Golden Rule

Use managed identities and Azure RBAC in production. Reserve DefaultAzureCredential for local development only.

Authentication by Environment

Why Not DefaultAzureCredential in Production?

1. Unpredictable fallback chain — walks through multiple credential types, adding latency and making failures harder to diagnose. 2. Broad surface area — checks environment variables, CLI tokens, and other sources that should not exist in production. 3. Non-deterministic — which credential actually authenticates depends on the environment, making behavior inconsistent across deployments. 4. Performance — each failed credential attempt adds network round-trips before falling back to the next.

Production Patterns

.NET

using Azure.Identity;

var credential = Environment.GetEnvironmentVariable("AZURE_FUNCTIONS_ENVIRONMENT") == "Development"
    ? new DefaultAzureCredential()                          // local dev — uses CLI/VS credentials
    : new ManagedIdentityCredential();                      // production — deterministic, no fallback chain
// For user-assigned identity: new ManagedIdentityCredential("<client-id>")

TypeScript / JavaScript

import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity";

const credential = process.env.NODE_ENV === "development"
  ? new DefaultAzureCredential()                          // local dev — uses CLI/VS credentials
  : new ManagedIdentityCredential();                      // production — deterministic, no fallback chain
// For user-assigned identity: new ManagedIdentityCredential("<client-id>")

Python

import os
from azure.identity import DefaultAzureCredential, ManagedIdentityCredential

credential = (
    DefaultAzureCredential()                              # local dev — uses CLI/VS credentials
    if os.getenv("AZURE_FUNCTIONS_ENVIRONMENT") == "Development"
    else ManagedIdentityCredential()                      # production — deterministic, no fallback chain
)
# For user-assigned identity: ManagedIdentityCredential(client_id="<client-id>")

Java

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.identity.ManagedIdentityCredentialBuilder;

var credential = "Development".equals(System.getenv("AZURE_FUNCTIONS_ENVIRONMENT"))
    ? new DefaultAzureCredentialBuilder().build()          // local dev — uses CLI/VS credentials
    : new ManagedIdentityCredentialBuilder().build();      // production — deterministic, no fallback chain
// For user-assigned identity: new ManagedIdentityCredentialBuilder().clientId("<client-id>").build()

Local Development Setup

DefaultAzureCredential is ideal for local dev because it automatically picks up credentials from developer tools:

1. Azure CLI — az login 2. Azure Developer CLI — azd auth login 3. Azure PowerShell — Connect-AzAccount 4. Visual Studio / VS Code — sign in via Azure extension

import { DefaultAzureCredential } from "@azure/identity";

// Local development only — uses CLI/PowerShell/VS Code credentials
const credential = new DefaultAzureCredential();

Environment-Aware Pattern

Detect the runtime environment and select the appropriate credential. The key principle: use DefaultAzureCredential only when running locally, and a specific credential in production.

Tip: Azure Functions sets AZURE_FUNCTIONS_ENVIRONMENT to "Development" when running locally. For App Service or containers, use any environment variable you control (e.g. NODE_ENV, ASPNETCORE_ENVIRONMENT).

import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity";

function getCredential() {
  if (process.env.NODE_ENV === "development") {
    return new DefaultAzureCredential();          // picks up az login / VS Code creds
  }
  return process.env.AZURE_CLIENT_ID
    ? new ManagedIdentityCredential(process.env.AZURE_CLIENT_ID)  // user-assigned
    : new ManagedIdentityCredential();                            // system-assigned
}

Security Checklist

• [ ] Use managed identity for all Azure-hosted apps
• [ ] Never hardcode credentials, connection strings, or keys
• [ ] Apply least-privilege RBAC roles at the narrowest scope
• [ ] Use ManagedIdentityCredential (not DefaultAzureCredential) in production
• [ ] Store any required secrets in Azure Key Vault
• [ ] Rotate secrets and certificates on a schedule
• [ ] Enable Microsoft Defender for Cloud on production resources

Further Reading

• Passwordless connections overview
• Managed identities overview
• Azure RBAC overview
• .NET authentication guide
• Python identity library
• JavaScript identity library
• Java identity library

AKS Cost Anomaly Investigation

Investigate user-reported cost or utilization spikes by correlating Azure Monitor metrics, scaling events, and Cost Management data.

Step 1 - Confirm Timeframe

Ask the user: "When did you notice the spike? (e.g., 'last Tuesday', 'between 2 AM and 4 AM yesterday')"

Step 2 - Pull Cost Data

az rest --method post \
  --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CostManagement/query?api-version=2023-11-01" \
  --headers "ClientType=GitHubCopilotForAzure" \
  --body '{
    "type": "ActualCost",
    "timeframe": "Custom",
    "timePeriod": { "from": "<start-date>", "to": "<end-date>" },
    "dataset": {
      "granularity": "Daily",
      "aggregation": { "totalCost": { "name": "Cost", "function": "Sum" } },
      "grouping": [{ "type": "Dimension", "name": "ResourceId" }]
    }
  }'

Step 3 - Pull Node Count and Scaling Events

# First, verify available metrics on your AKS resource
az monitor metrics list-definitions \
  --resource "<aks-resource-id>" \
  --output table

# Node count over the anomaly window (use metric name from list-definitions output)
az monitor metrics list \
  --resource "<aks-resource-id>" \
  --metrics "<verified-node-count-metric>" \
  --interval PT5M --aggregation Count \
  --start-time "<start-date>" --end-time "<end-date>"

# HPA scaling events
kubectl get events --all-namespaces \
  --field-selector reason=SuccessfulRescale \
  --sort-by='.lastTimestamp'

Step 4 - Top Consumers

kubectl top nodes
kubectl top pods --all-namespaces --sort-by=cpu

Common Causes

Set Up Budget Alert

az consumption budget create \
  --budget-name "aks-monthly-budget" \
  --amount <budget-amount> \
  --time-grain Monthly \
  --start-date "<YYYY-MM-01>" \
  --end-date "<YYYY-MM-01>" \
  --resource-group "<resource-group>" \
  --threshold 80 \
  --contact-emails "<contact-email>"

AKS Cost Analysis Add-on

Enable namespace-level cost visibility using the built-in AKS cost monitoring add-on.

Check Status

# Check if add-on is enabled
az aks show \
  --name "<cluster-name>" --resource-group "<resource-group>" \
  --query "addonProfiles.costAnalysis" -o json

# Check cluster tier (add-on requires Standard or Premium)
az aks show \
  --name "<cluster-name>" --resource-group "<resource-group>" \
  --query "{tier:sku.tier, name:name}" -o table

Enable Add-on

# Requires Standard or Premium tier
az aks update \
  --name "<cluster-name>" --resource-group "<resource-group>" \
  --enable-cost-analysis

If Cluster is Free Tier

Warn user that upgrading from Free to Standard introduces an ongoing cluster management fee. Use the official AKS pricing page or this skill’s pricing validation step to confirm the current cost with the user and obtain explicit approval before proceeding. After user approval:

az aks update \
  --name "<cluster-name>" --resource-group "<resource-group>" \
  --tier standard

az aks update \
  --name "<cluster-name>" --resource-group "<resource-group>" \
  --enable-cost-analysis

After Enabling

Namespace-level cost data is available in:

• Azure Portal: AKS cluster -> Cost Analysis blade
• Azure Cost Management: filter by cluster resource ID + kubernetes namespace dimension

Risk: Low for enabling the add-on. Upgrading tier (Free -> Standard) has a cost — always confirm with user first.

Azure Quick Review (azqr) for Cost Optimization

Azure Quick Review (azqr) generates compliance and governance reports that identify cost-impacting issues and orphaned resources.

Create Filters Configuration

Create a filters.yaml file to focus the scan on cost optimization:

includeSections:
  - Costs
  - Advisor
  - Inventory
  - Orphaned
excludeSections:
  - Recommendations
  - AzurePolicy
  - DefenderRecommendations

Run the azqr Scan

Execute the scan using Azure MCP or CLI:

# Via Azure MCP (preferred if available)
# Use the extension_azqr tool with subscription and optional resource-group parameters

# Or via direct CLI:
azqr scan --subscription "<SUBSCRIPTION_ID>" --resource-group "<RESOURCE_GROUP>" --filters ./filters.yaml --output json

Save Output

Save all generated files to the output/ folder: 1. Create the folder: mkdir output (if it doesn't exist) 2. Save the azqr report as: output/azqr_report_<YYYYMMDD_HHMMSS>.json 3. After the scan completes, delete the temporary filters.yaml file

Report Output

The scan generates a JSON report with recommendations categorized by impact level (High/Medium/Low), including:

• Orphaned resources (NICs, disks, IPs)
• Azure Advisor cost recommendations
• Resource inventory
• Cost breakdown by resource

Notes

• azqr provides qualitative governance recommendations
• Always validate findings with actual cost data before making changes
• The tool requires Reader role on the subscription or resource group
• Save reports to output/ folder with timestamps for audit trail

Azure Resource Graph Queries for Cost Optimization

Azure Resource Graph (ARG) enables fast, cross-subscription resource querying using KQL via az graph query. Use it to find orphaned resources, unused infrastructure, and optimization targets.

How to Query

Use the extension_cli_generate MCP tool to generate az graph query commands:

azure__extension_cli_generate
  intent: "query Azure Resource Graph to <describe what you want to find>"
  cli-type: "az"

Or construct directly:

az graph query -q "<KQL>" --query "data[].{name:name, type:type}" -o table

⚠️ Prerequisite: az extension add --name resource-graph

Key Tables

Cost Optimization Query Patterns

Find orphaned (unattached) managed disks:

Resources
| where type =~ 'microsoft.compute/disks'
| where isempty(managedBy)
| project name, resourceGroup, location, diskSizeGb=properties.diskSizeGB, sku=sku.name

Find unattached public IP addresses:

Resources
| where type =~ 'microsoft.network/publicipaddresses'
| where isempty(properties.ipConfiguration)
| project name, resourceGroup, location, sku=sku.name

Find orphaned network interfaces:

Resources
| where type =~ 'microsoft.network/networkinterfaces'
| where isempty(properties.virtualMachine)
| project name, resourceGroup, location

Resource count by SKU/tier (spot oversized resources):

Resources
| where isnotempty(sku.name)
| summarize count() by type, tostring(sku.name)
| order by count_ desc

Tag coverage for cost allocation:

Resources
| extend hasCostCenter = isnotnull(tags['CostCenter'])
| summarize total=count(), tagged=countif(hasCostCenter) by type
| extend coverage=round(100.0 * tagged / total, 1)
| order by total desc

Find idle load balancers (no backend pools):

Resources
| where type =~ 'microsoft.network/loadbalancers'
| where array_length(properties.backendAddressPools) == 0
| project name, resourceGroup, location, sku=sku.name

Get Advisor cost recommendations:

AdvisorResources
| where properties.category == 'Cost'
| project name, impact=properties.impact, description=properties.shortDescription.solution

Tips

• Use =~ for case-insensitive type matching (resource types are lowercase)
• Navigate properties with properties.fieldName
• Use --first N to limit result count
• Use --subscriptions to scope to specific subscriptions
• Cross-reference orphaned resources with cost data from Cost Management API

Cost Optimization Report Template

Use create_file with path output/costoptimizereport<YYYYMMDD_HHMMSS>.md and the following structure:

# Azure Cost Optimization Report
**Generated**: <timestamp>

## Executive Summary
- Total Monthly Cost: $X (ACTUAL DATA from Cost Management API)
- Top Cost Drivers: [List top 3 services with costs]
- Potential Savings: $Y/month

## Cost Breakdown by Service
| Service | Cost (USD) | % of Total |
|---------|-----------|------------|
| ... | ... | ... |
| **Total** | **$X** | **100%** |

## Free Tier Analysis
[Resources operating within free tiers]

## Orphaned Resources (Immediate Savings)
[From azqr — resources that can be deleted immediately]

## Optimization Recommendations

### Priority 1: High Impact, Low Risk
- ACTUAL cost: $X/month
- ESTIMATED savings: $Y/month
- Commands to execute

### Priority 2: Medium Impact, Medium Risk
- ACTUAL baseline, ACTUAL metrics, VALIDATED pricing
- ESTIMATED savings with commands

### Priority 3: Long-term Optimization
[Reserved Instances, Storage tiering]

## Total Estimated Savings
- Monthly: $X | Annual: $Y

## Implementation Commands
[Safe commands with approval warnings]

## Validation Appendix
- Cost Query Results: `output/cost-query-result<timestamp>.json`
- Pricing Sources: [Links]

Portal Link Format

Include Azure Portal links for all resources using this format:

https://portal.azure.com/#@<TENANT_ID>/resource/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/<RESOURCE_PROVIDER>/<RESOURCE_TYPE>/<RESOURCE_NAME>/overview

Audit Trail

Save cost query results to output/cost-query-result<YYYYMMDD_HHMMSS>.json for reproducibility.

Cleanup

After generating the report, remove temporary files:

Remove-Item -Path "temp" -Recurse -Force -ErrorAction SilentlyContinue

Redis Management — .NET SDK Quick Reference

Condensed from azure-resource-manager-redis-dotnet. Full patterns

(cache creation, firewall rules, access keys, geo-replication, patching)

in the azure-resource-manager-redis-dotnet plugin skill if installed.

Install

dotnet add package Azure.ResourceManager.Redis dotnet add package Azure.Identity

Quick Start

Auth: DefaultAzureCredential is for local development. See auth-best-practices.md for production patterns.

using Azure.ResourceManager;
using Azure.Identity;
var armClient = new ArmClient(new DefaultAzureCredential());

Best Practices

• Use WaitUntil.Completed for operations that must finish before proceeding
• Use WaitUntil.Started when you want to poll manually or run operations in parallel
• Use DefaultAzureCredential for local development only. In production, use ManagedIdentityCredential — see auth-best-practices.md
• Handle RequestFailedException for ARM API errors
• Use CreateOrUpdateAsync for idempotent operations
• Navigate hierarchy via Get* methods (e.g., cache.GetRedisFirewallRules())
• Use Premium SKU for production workloads requiring geo-replication, clustering, or persistence
• Enable TLS 1.2 minimum — set MinimumTlsVersion = RedisTlsVersion.Tls1_2
• Disable non-SSL port — set EnableNonSslPort = false for security
• Rotate keys regularly — use RegenerateKeyAsync and update connection strings

Azure Redis Cost Optimization

Reference guide for identifying cost savings opportunities in Azure Redis deployments through analysis and targeted scans.

Subscription Input Options

Accept any of these identifiers to identify subscriptions for analysis:

Cost Optimization Rules

When analyzing each cache, apply these prioritized rules:

Report Templates

Subscription-Level Summary

Quick overview of costs and issues per subscription (use for multi-subscription scans). Include: subscription name/ID, total monthly cost, number of caches, cache count by SKU tier, and top issues found.

Detailed Cache Analysis

Individual cache breakdown with specific recommendations. Include: cache name, resource group, SKU tier, current cost, memory usage %, CPU usage %, connection count, and specific rightsizing recommendations.

Tools & Commands

MCP Tool: azure__redis with command redis_list (parameter: subscription)

Azure CLI Equivalents:

• az account list - List subscriptions
• az redis list --subscription <id> - List Redis caches
• az redis show - Get cache details
• az redis delete - Remove cache

Cost Optimization Workflow

Use this workflow when the user wants to reduce their costs — find waste, orphaned resources, rightsizing opportunities.

Important: Always present the total bill and cost breakdown (from the Cost Query Workflow) alongside optimization recommendations.

Step 0: Validate Prerequisites

Required Tools:

• Azure CLI installed and authenticated (az login)
• Azure CLI extensions: costmanagement, resource-graph
• Azure Quick Review (azqr) installed — See Azure Quick Review

Required Permissions:

• Cost Management Reader role
• Monitoring Reader role
• Reader role on subscription/resource group

Verification commands:

az --version
az account show
az extension show --name costmanagement
azqr version

Step 1: Load Best Practices

azure__get_azure_bestpractices({
  intent: "Get cost optimization best practices",
  command: "get_bestpractices",
  parameters: { resource: "cost-optimization", action: "all" }
})

Step 1.5: Redis-Specific Analysis (Conditional)

If the user specifically requests Redis cost optimization, use the specialized Redis reference:

Reference: Azure Redis Cost Optimization

When to use:

• User mentions "Redis", "Azure Cache for Redis", or "Azure Managed Redis"
• Focus is on Redis resource optimization, not general subscription analysis

💡 Note: For general subscription-wide optimization, continue with Step 2. For Redis-only analysis, follow the Redis reference document.

Step 1.6: Choose Analysis Scope (for Redis-specific analysis)

If performing Redis cost optimization, ask the user to select: 1. Specific Subscription ID 2. Subscription Name 3. Subscription Prefix (e.g., "CacheTeam") 4. All My Subscriptions 5. Tenant-wide

Wait for user response before proceeding.

Step 1.7: AKS-Specific Analysis (Conditional)

If the user specifically requests AKS cost optimization, use the specialized AKS reference files:

When to use AKS-specific analysis:

• User mentions "AKS", "Kubernetes", "cluster", "node pool", "pod", or "kubectl"
• User wants to enable the AKS cost analysis add-on or namespace cost visibility
• User reports a cost spike, unusual cluster utilization, or wants budget alerts

Tool Selection:

• Prefer MCP first: Use azure__aks for AKS operations (list clusters, get node pools, inspect configuration) — it provides richer metadata and is consistent with AKS skill conventions in this repo
• Fall back to CLI: Use az aks and kubectl only when the specific operation cannot be performed via the MCP surface

Reference files (load only what is needed for the request):

• Cost Analysis Add-on — enable namespace-level cost visibility
• Anomaly Investigation — cost spikes, scaling events, budget alerts

Note: For general subscription-wide cost optimization (including AKS resource groups), continue with Step 2. For AKS-focused analysis, follow the instructions in the relevant reference file above.

Step 1.8: Choose Analysis Scope (for AKS-specific analysis)

If performing AKS cost optimization, ask the user to select their analysis scope:

Prompt the user with these options: 1. Specific Cluster Name - Analyze a single AKS cluster 2. Resource Group - Analyze all clusters in a resource group 3. Subscription ID - Analyze all clusters in a subscription 4. All My Clusters - Scan all accessible clusters across subscriptions

Wait for user response before proceeding to Step 2.

Step 2: Run Azure Quick Review

Run azqr to find orphaned resources (immediate cost savings):

Reference: Azure Quick Review

azure__extension_azqr
  subscription: "<SUBSCRIPTION_ID>"
  resource-group: "<RESOURCE_GROUP>"  # optional

What to look for:

• Orphaned resources: unattached disks, unused NICs, idle NAT gateways
• Over-provisioned resources: excessive retention periods, oversized SKUs
• Missing cost tags

Step 3: Discover Resources

Use Azure Resource Graph for efficient cross-subscription resource discovery. See Azure Resource Graph Queries for orphaned resource detection patterns.

az account show
az resource list --subscription "<SUBSCRIPTION_ID>" --resource-group "<RESOURCE_GROUP>"

Step 4: Query Actual Costs

Get actual cost data from Azure Cost Management API (last 30 days). Use the Cost Query Workflow with this configuration:

Create `temp/cost-query.json`:

{
  "type": "ActualCost",
  "timeframe": "Custom",
  "timePeriod": {
    "from": "<START_DATE>",
    "to": "<END_DATE>"
  },
  "dataset": {
    "granularity": "None",
    "aggregation": {
      "totalCost": {
        "name": "Cost",
        "function": "Sum"
      }
    },
    "grouping": [
      {
        "type": "Dimension",
        "name": "ResourceId"
      }
    ]
  }
}

Action Required: Calculate <START_DATE> (30 days ago) and <END_DATE> (today) in ISO 8601 format.

Execute and save results to `output/cost-query-result<timestamp>.json`. Always include the --headers "ClientType=GitHubCopilotForAzure" header in all Cost Management API requests.

💡 Tip: Also run a cost-by-service query (grouping by ServiceName) to present the total bill breakdown alongside optimization recommendations. See examples.md.

⚠️ Warning: Sequential queries to the same scope share the per-scope rate limit (4 requests/minute). If a 429 response is received, check all x-ms-ratelimit-microsoft.costmanagement-*-retry-after headers and do not send further requests until the longest retry-after duration has elapsed.

Step 5: Validate Pricing

Fetch current pricing from official Azure pricing pages using fetch_webpage:

Key services to validate:

• Container Apps: https://azure.microsoft.com/pricing/details/container-apps/
• Virtual Machines: https://azure.microsoft.com/pricing/details/virtual-machines/
• App Service: https://azure.microsoft.com/pricing/details/app-service/
• Log Analytics: https://azure.microsoft.com/pricing/details/monitor/

Important: Check for free tier allowances — many Azure services have generous free limits.

Step 6: Collect Utilization Metrics

Query Azure Monitor for utilization data (last 14 days) to support rightsizing recommendations:

$startTime = (Get-Date).AddDays(-14).ToString("yyyy-MM-ddTHH:mm:ssZ")
$endTime = Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ"

# VM CPU utilization
az monitor metrics list `
  --resource "<RESOURCE_ID>" `
  --metric "Percentage CPU" `
  --interval PT1H `
  --aggregation Average `
  --start-time $startTime `
  --end-time $endTime

Step 7: Generate Optimization Report

Generate a report to output/costoptimizereport<YYYYMMDD_HHMMSS>.md that includes an executive summary, cost breakdown by service, free tier analysis, orphaned resources, prioritized optimization recommendations, and implementation commands. Save cost query results to output/cost-query-result<YYYYMMDD_HHMMSS>.json for audit trail, then clean up temporary files.

For the complete report template, see report-template.md.

Dimensions by Scope

Dimension availability matrix for the Cost Management Query API, organized by scope type and agreement type.

Scope URL Patterns

Common Dimensions

The following dimensions are available across most scopes:

⚠️ Warning: ResourceId grouping is only supported at subscription and resource group scopes. At higher scopes (billing account, management group, billing profile, etc.), use ServiceName, SubscriptionName, or another supported dimension instead. See guardrails.md for the full scope restriction table.

Scope-Specific Dimensions

Additional dimensions available only at certain scopes:

Agreement Type Dimension Sets

Available dimensions vary by agreement type. Only dimensions listed for your agreement type are valid in GroupBy and Filter expressions.

EA (Enterprise Agreement)

MCA (Microsoft Customer Agreement)

MOSP (Microsoft Online Services Program / Pay-As-You-Go)

⚠️ ResourceId is available as a dimension but only works in GroupBy at subscription and resource group scopes. At billing account or management group scopes, use ServiceName or SubscriptionName instead.

Comparison Summary

Scope Resolution Priority

When multiple scope identifiers are available in context, use the following priority order (highest first):

💡 Tip: When a user provides both a subscription and a resource group, prefer the Resource Group scope (priority 2) over Subscription (priority 3) for more targeted results.

Required Context Variables

The following context variables are needed to resolve scope and validate dimensions:

Cost Query Error Handling

Detailed error handling reference for the Cost Management Query API.

HTTP Status Codes

Common Error Scenarios

Retry Strategy

⚠️ Warning: Do not retry any errors except 429. All other errors indicate issues that must be fixed before re-attempting the request.

Error Response Structure

All error responses follow a consistent JSON structure:

{
  "error": {
    "code": "<error-code>",
    "message": "<human-readable-error-message>",
    "details": [
      {
        "code": "<detail-code>",
        "message": "<detail-message>"
      }
    ]
  }
}

Cost Management Query Examples

Common query patterns with request bodies. Use the SKILL.md workflow to construct and execute the az rest command.

1. Monthly Cost by Service

{
  "type": "ActualCost",
  "timeframe": "MonthToDate",
  "dataset": {
    "granularity": "None",
    "aggregation": {
      "totalCost": { "name": "Cost", "function": "Sum" }
    },
    "grouping": [
      { "type": "Dimension", "name": "ServiceName" }
    ],
    "sorting": [
      { "direction": "Descending", "name": "Cost" }
    ]
  }
}

---

2. Daily Cost Trend (Last 30 Days)

{
  "type": "ActualCost",
  "timeframe": "Custom",
  "timePeriod": {
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-31T23:59:59Z"
  },
  "dataset": {
    "granularity": "Daily",
    "aggregation": {
      "totalCost": { "name": "Cost", "function": "Sum" }
    }
  }
}

⚠️ Warning: Daily granularity supports a maximum of 31 days.

---

3. Cost by Resource Group with Tag Filter

{
  "type": "ActualCost",
  "timeframe": "MonthToDate",
  "dataset": {
    "granularity": "None",
    "aggregation": {
      "totalCost": { "name": "Cost", "function": "Sum" }
    },
    "grouping": [
      { "type": "Dimension", "name": "ResourceGroupName" }
    ],
    "filter": {
      "tags": {
        "name": "Environment",
        "operator": "In",
        "values": ["production", "staging"]
      }
    },
    "sorting": [
      { "direction": "Descending", "name": "Cost" }
    ]
  }
}

---

4. Amortized Cost for Reservation Analysis

{
  "type": "AmortizedCost",
  "timeframe": "TheLastMonth",
  "dataset": {
    "granularity": "None",
    "aggregation": {
      "totalCost": { "name": "Cost", "function": "Sum" }
    },
    "grouping": [
      { "type": "Dimension", "name": "BenefitName" }
    ],
    "sorting": [
      { "direction": "Descending", "name": "Cost" }
    ]
  }
}

💡 Tip: AmortizedCost spreads reservation purchases across the term for accurate daily/monthly effective cost.

---

5. Top 10 Most Expensive Resources

{
  "type": "ActualCost",
  "timeframe": "MonthToDate",
  "dataset": {
    "granularity": "None",
    "aggregation": {
      "totalCost": { "name": "Cost", "function": "Sum" }
    },
    "grouping": [
      { "type": "Dimension", "name": "ResourceId" }
    ],
    "sorting": [
      { "direction": "Descending", "name": "Cost" }
    ]
  }
}

💡 Tip: Append &$top=10 to the URL to limit results: ...query?api-version=2023-11-01&$top=10

Cost Query Guardrails

Detailed validation rules and guardrails for the Cost Management Query API. The system applies these automatically, but understanding them helps avoid unexpected query modifications or errors.

Time Period Validation

Default Behavior

Future Date Handling

⚠️ Warning: Future date shifting happens silently. The response data will cover the adjusted period, not the originally requested dates.

Granularity-Based Range Limits

⚠️ Warning: The absolute API limit is 37 months. Requests exceeding 37 months return HTTP 400 regardless of granularity.

Minimum Start Date

GroupBy Interaction with Time Period

💡 Tip: When using GroupBy with Daily granularity over a multi-day range, the system may return data only for the last day. For full daily breakdown with grouping, ensure the range is within the 31-day limit.

ResourceId Scope Restriction

⚠️ Warning: Grouping by ResourceId is only supported at subscription scope and below (subscription, resource group). It is NOT supported at higher scopes.

When the user requests a cost breakdown by resource at a billing account or management group scope, use ServiceName, SubscriptionName, or another supported dimension instead. If per-resource detail is needed, narrow the scope to a specific subscription first.

Dataset Validation

GroupBy Constraints

Aggregation Constraints

Filter Constraints

⚠️ Warning: A filter with a single child in and or or will fail validation. Wrap single-condition filters directly without a logical operator, or use not for negation.

Scope & Dimension Compatibility

Dimensions must be valid for the intersection of the agreement type and scope type.

⚠️ Warning: Using an EA-only dimension (e.g., DepartmentName) on a MOSP subscription will return a validation error. Always verify the agreement type before selecting dimensions.

EA + Management Group Special Case

Remediation: When filtering by subscription name at Management Group scope under EA, always include a SubscriptionId filter alongside the SubscriptionName filter.

{
  "and": [
    {
      "dimensions": {
        "name": "SubscriptionId",
        "operator": "In",
        "values": ["<subscription-id>"]
      }
    },
    {
      "dimensions": {
        "name": "SubscriptionName",
        "operator": "In",
        "values": ["My Subscription"]
      }
    }
  ]
}

Rate Limiting

Rate Limit Thresholds

⚠️ Warning: The per-scope limit (4 requests/minute) is the most restrictive. Sequential queries to the same subscription, resource group, or billing account share this limit.

QPU-Based Throttling

Rate Limit Headers

Handling 429 Responses

On a 429 response, check all retry-after headers present in the response. Multiple headers may be returned simultaneously. Take the maximum value and do NOT send any further requests to the same scope until that duration has fully elapsed.

⚠️ Warning: Do not retry before the retry-after duration has elapsed. Premature retries will be rejected and may extend the throttling period.

Pagination

💡 Tip: For large result sets, always check the nextLink field in the response. If present, make additional requests to retrieve all pages.

Cost Management Query API — Request Body Schema

Schema for the Cost Management Query API.

Request Body Structure

{
  "type": "<report-type>",
  "timeframe": "<timeframe>",
  "timePeriod": { "from": "2024-01-01T00:00:00Z", "to": "2024-01-31T23:59:59Z" },
  "dataset": {
    "granularity": "<granularity>",
    "aggregation": { "<alias>": { "name": "<column>", "function": "<function>" } },
    "grouping": [{ "type": "<column-type>", "name": "<column-name>" }],
    "filter": { "<filter-expression>" },
    "sorting": [{ "direction": "<direction>", "name": "<column>" }]
  }
}

Top-Level Fields

Timeframe Values

WeekToDate · MonthToDate · BillingMonthToDate · YearToDate · TheLastWeek · TheLastMonth · TheLastBillingMonth · TheLastYear · TheLast7Days · TheLast3Months · Custom

Dataset Fields

Granularity

Aggregation

"aggregation": { "totalCost": { "name": "Cost", "function": "Sum" } }

Grouping

"grouping": [
  { "type": "Dimension", "name": "ServiceName" },
  { "type": "TagKey", "name": "Environment" }
]

• type: Dimension (built-in) or TagKey (resource tag)
• Maximum 2 GroupBy dimensions per query. No duplicates.

Filter

Filter expressions restrict which cost records are included. Filters support logical operators (and, or, not) and comparison operators on dimensions or tags.

Filter Expression Structure

"filter": {
  "and": [
    {
      "dimensions": {
        "name": "ResourceGroupName",
        "operator": "In",
        "values": ["rg-prod", "rg-staging"]
      }
    },
    {
      "not": {
        "tags": {
          "name": "Environment",
          "operator": "Equal",
          "values": ["dev"]
        }
      }
    }
  ]
}

Logical Operators

⚠️ Warning: and and or must contain at least 2 child expressions. not must contain exactly 1.

Comparison Operators (ComparisonOperator Enum)

Filter Target Types

Sorting

"sorting": [
  { "direction": "Descending", "name": "Cost" }
]

Response Structure

{
  "id": "<query-id>",
  "name": "<query-name>",
  "type": "Microsoft.CostManagement/query",
  "properties": {
    "nextLink": "<url-for-next-page-or-null>",
    "columns": [
      { "name": "Cost", "type": "Number" },
      { "name": "ServiceName", "type": "String" },
      { "name": "UsageDate", "type": "Number" },
      { "name": "Currency", "type": "String" }
    ],
    "rows": [
      [123.45, "Virtual Machines", 20240115, "USD"],
      [67.89, "Storage", 20240115, "USD"]
    ]
  }
}

💡 Tip: UsageDate is returned as a number in YYYYMMDD format (e.g., 20240115) when granularity is Daily or Monthly.

Cost Query Workflow

Use this workflow when the user wants to understand their costs — breakdowns, trends, totals, top spenders.

Step 1: Determine Scope

Identify the Azure scope for the cost query from the Scope Reference table in the main SKILL.md.

Step 2: Choose Report Type

Step 3: Set Timeframe

Use a preset timeframe (e.g., MonthToDate, TheLastMonth, TheLastYear) or Custom with a timePeriod object.

⚠️ Warning: Key time period guardrails:

- Daily granularity: max 31 days

- Monthly/None granularity: max 12 months

- Custom timeframe requires a timePeriod object with from and to dates

- Future dates in historical queries are silently adjusted (see guardrails for details)

>

See guardrails.md for the complete set of validation rules.

Step 4: Configure Dataset

Define granularity, aggregation, grouping, filtering, and sorting in the dataset object.

• Granularity: None, Daily, or Monthly
• Aggregation: Use Sum on Cost or PreTaxCost for total cost
• Grouping: Up to 2 GroupBy dimensions (e.g., ServiceName, ResourceGroupName)
• Filtering: Use dimensions or tags filters with name, operator (In, Equal, Contains), and values fields
• Sorting: Order results by cost or dimension columns

💡 Tip: Not all dimensions are available at every scope. See dimensions-by-scope.md for the availability matrix.

For the full request body schema, see request-body-schema.md.

Step 5: Construct and Execute the API Call

Use az rest to call the Cost Management Query API.

Create cost query file:

Create temp/cost-query.json with:

{
  "type": "ActualCost",
  "timeframe": "MonthToDate",
  "dataset": {
    "granularity": "None",
    "aggregation": {
      "totalCost": {
        "name": "Cost",
        "function": "Sum"
      }
    },
    "grouping": [
      {
        "type": "Dimension",
        "name": "ServiceName"
      }
    ]
  }
}

Execute cost query:

# Create temp folder
New-Item -ItemType Directory -Path "temp" -Force

# Query using REST API (more reliable than az costmanagement query)
az rest --method post `
  --url "<scope>/providers/Microsoft.CostManagement/query?api-version=2023-11-01" `
  --headers "ClientType=GitHubCopilotForAzure" `
  --body '@temp/cost-query.json'

Step 6: Handle Pagination and Errors

• The API returns a maximum of 5,000 rows per page (default: 1,000).
• If nextLink is present in the response, follow it to retrieve additional pages.
• Handle rate limiting (HTTP 429) by checking all x-ms-ratelimit-microsoft.costmanagement-*-retry-after headers in the response. Wait for the longest value before retrying. Do not send further requests to the same scope until the retry-after duration has elapsed.

See error-handling.md for the full error reference.

Key Guardrails

Examples

Cost by service for the current month:

az rest --method post `
  --url "/subscriptions/<subscription-id>/providers/Microsoft.CostManagement/query?api-version=2023-11-01" `
  --headers "ClientType=GitHubCopilotForAzure" `
  --body '{
    "type": "ActualCost",
    "timeframe": "MonthToDate",
    "dataset": {
      "granularity": "None",
      "aggregation": {
        "totalCost": { "name": "Cost", "function": "Sum" }
      },
      "grouping": [
        { "type": "Dimension", "name": "ServiceName" }
      ]
    }
  }'

For more examples including daily trends, tag-based filtering, and multi-dimension queries, see examples.md.

Error Handling

See error-handling.md for detailed error handling including rate limit headers and retry strategies.