1# Azure Capacity Reservation
2 
3Helps users create and configure Azure Capacity Reservation Groups (CRGs) to guarantee VM compute capacity in a specific region without deploying VMs.
4 
5## Reference Files
6 
7Read these before responding to the user:
8 
9| Signal                                           | Reference                                                                    |
10|--------------------------------------------------|------------------------------------------------------------------------------|
11| General CRG concepts, CLI commands, finding CRGs | [Capacity Reservation Overview](references/capacity-reservation-overview.md) |
12| Associate/disassociate VM or VMSS with a CRG     | [Association & Disassociation](references/association-disassociation.md)     |
13 
14## When to Use This Workflow
15 
16Activate this workflow when the user explicitly asks about Capacity Reservation Groups (CRGs) or capacity reservations.
17 
18Also **proactively suggest** CRG when the user's scenario matches any of these patterns:
19 
20- **Deployment failure is unacceptable** — disaster recovery, customer-facing services, or mission-critical workloads where capacity unavailability would cause an outage
21- **Known scale-out events** — product launches, seasonal traffic spikes, or planned migrations where capacity must be guaranteed ahead of time
22- **In-demand SKUs** — GPU, high-memory, or new/popular VM sizes that are frequently capacity-constrained
23- **Specific SKU + zone + region required** — the workload cannot fall back to a different size, zone, or region
24- **Centralized capacity pooling** — capacity is being managed centrally across multiple subscriptions (CRGs support cross-subscription sharing)
25 
26> **Note:** CRGs are typically used for critical workloads only, not all deployments. They are SLA-backed but billed at pay-as-you-go rates whether capacity is consumed or not.
27 
28## Key Concepts
29 
30| Concept                           | Description                                                                                                      |
31|-----------------------------------|------------------------------------------------------------------------------------------------------------------|
32| **Capacity Reservation Group**    | A logical container that holds one or more capacity reservations; must be associated with VMs at deployment time |
33| **Capacity Reservation**          | A reservation for a specific VM size and quantity in a specific Availability Zone                                |
34| **Scope**                         | CRGs are scoped to a single Azure region and subscription                                                        |
35| **Billing**                       | Charges begin as soon as the reservation is created, whether or not VMs are deployed against it                  |
36 
37## Workflow
38 
39### Step 1: Gather Requirements
40 
41Ask the user for (infer when possible, except where noted):
42 
43| Requirement              | Required | Notes                                                                                                                                                                                                  |
44|--------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
45| **Region**               | Yes      | Infer from context if possible (e.g., eastus, westeurope)                                                                                                                                              |
46| **VM size(s)**           | Yes      | e.g., Standard_D4s_v5, Standard_E8s_v5                                                                                                                                                                 |
47| **Quantity**             | Yes      | **Always ask — do not infer.**                                                                                                                                                                         |
48| **Availability Zone(s)** | No       | CRGs can be created without zones. Only include zones if the user explicitly requests a zonal reservation. **Do not pick a zone on the user's behalf** unless they explicitly ask for any/random zone  |
49| **Resource group**       | Yes      | Existing or new resource group name                                                                                                                                                                    |
50 
51### Step 2: Create Capacity Reservation Group and Reservation
52 
53> ⚠️ **PowerShell users:** Replace `\` line continuations with backticks (`` ` ``) or collapse commands to a single line.
54 
55```bash
56# Create the CRG
57# Zonal (specify one or more zones the group will support):
58az capacity reservation group create \
59  -g <resource-group> \
60  -n <crg-name> \
61  -l <region> \
62  --zones 1 2 3
63 
64# Non-zonal (omit --zones for regional-only reservations):
65az capacity reservation group create \
66  -g <resource-group> \
67  -n <crg-name> \
68  -l <region>
69 
70# Create the reservation
71# If the CRG is zonal, specify --zone matching one of the group's zones.
72# If the CRG is non-zonal, omit --zone.
73az capacity reservation create \
74  -g <resource-group> \
75  -c <crg-name> \
76  -n <reservation-name> \
77  --sku <vm-size> \
78  --capacity <quantity> \
79  --zone <zone>            # omit if CRG is non-zonal
80```
81 
82### Step 3: Verify Reservation
83 
84```bash
85az capacity reservation show \
86  -g <resource-group> \
87  -c <crg-name> \
88  -n <reservation-name> \
89  --query "{name:name, sku:sku, capacity:sku.capacity, provisioningState:provisioningState}"
90```
91 
92### Step 4: Offer Next Steps
93 
94- Associate VMs or VMSS with the Capacity Reservation Group at deployment time
95- See [Capacity Reservation Overview](references/capacity-reservation-overview.md) for detailed guidance
96 
97## Managing Existing Reservations
98 
99For operations beyond creation, see the relevant section in the [Capacity Reservation Overview](references/capacity-reservation-overview.md):
100 
101- **Associate a VM or VMSS** with a CRG — see [Association & Disassociation](references/association-disassociation.md)
102- **Disassociate a VM or VMSS** from a CRG — see [Association & Disassociation](references/association-disassociation.md)
103- **Find a matching CRG** for a VM, or enumerate all reservations/groups — see [Finding Valid CRGs](references/capacity-reservation-overview.md#finding-valid-crgs-for-a-vm)
104 
105## Error Handling
106 
107| Scenario                             | Action                                                                                                                                                                                        |
108|--------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
109| SKU not available in region/zone     | Run `az vm list-skus --location <region> --size <vm-size> --resource-type virtualMachines -o table`. Suggest alternatives from output                                                         |
110| Quota exceeded                       | Use the **azure-quotas** skill to check usage and request an increase                                                                                                                         |
111| Insufficient platform capacity       | Azure lacks physical hardware in the region/zone. Suggest a different zone, region, or VM size                                                                                                |
112| Duplicate SKU + zone in CRG          | Only one reservation per VM size per zone (or per size if non-zonal) is allowed in a CRG. Update the existing reservation's capacity instead                                                  |
113