[Feature] Add VMSS Lifecycle Hooks support to az vmss (preview)

[AnshulVermaa]

Summary

VMSS Lifecycle Hooks (LCH) is a new event-driven control-plane feature (API version 2025-11-01) that lets you observe and respond to control plane operations that affect your Virtual Machine Scale Set and its instances (VMSS) before the platform proceeds. When you configure a hook, the platform pauses the operation, emits a lifecycle hook event, and waits for you to approve, reject, or delay it. If you don't respond before the configured wait period expires, the platform applies a default action.

API Spec: Azure/azure-rest-api-specs#39735 (merged, 2025-11-01)
Resource Provider: Microsoft.Compute/virtualMachineScaleSets
Minimum API Version: 2025-11-01
Code-gen path: AAZ CodeGen V2 (preferred) — no Python SDK release needed
Target Date: June 2026
PM: Jerry Steele (fisteele@microsoft.com)
Engineering: Avisha Jain (avjai@microsoft.com)

---

Description

The 2025-11-01 API ships two hook types:

• UpgradeAutoOSScheduling — fires before an Auto OS Upgrade is scheduled (60 minutes default wait, 2 days max)
• UpgradeAutoOSRollingBatchStarting — fires before each rolling-upgrade batch (30 minutes default, 4 hr max)

---

New Parameters for Existing Commands

az vmss create / az vmss update

Parameter	Type	Required	Description
--lifecycle-hook-type	string (repeatable)	No	Hook type: UpgradeAutoOSScheduling or UpgradeAutoOSRollingBatchStarting. Repeat once per hook.
--lifecycle-hook-wait-duration	string (repeatable)	No	ISO 8601 duration (e.g. PT30M). Position-paired with --lifecycle-hook-type.
--lifecycle-hook-default-action	string (repeatable)	No	Platform action if no response. Defaults to Approve. Accepts Approve or Reject (schema). Position-paired with --lifecycle-hook-type when supplied.
--lifecycle-hooks-profile	JSON / @file.json	No	Full profile escape hatch. Mutually exclusive with --lifecycle-hook-*.

Pairing semantics: The i-th occurrence of each repeatable param applies to the i-th hook. --lifecycle-hook-wait-duration count must equal --lifecycle-hook-type count, be 1 (broadcast), or be omitted. --lifecycle-hook-default-action follows the same rule when supplied, but should normally be omitted.

Update semantics: Specifying a type that already exists returns 400 (API enforces one hook per type). To replace: remove --type <X> first, or use --lifecycle-hooks-profile for a full-profile PATCH with updated payload.

---

New Commands

Subgroup: az vmss lifecycle-hook-event

Command	Description
az vmss lifecycle-hook-event list	List all lifecycle hook events for a VMSS
az vmss lifecycle-hook-event show	Get a specific lifecycle hook event by name (GUID)
az vmss lifecycle-hook-event update	Respond to a lifecycle hook event (approve / reject / delay)
az vmss lifecycle-hook-event approve	Convenience: maps to update --action-state Approved
az vmss lifecycle-hook-event reject	Convenience: maps to update --action-state Rejected

Subgroup: az vmss lifecycle-hook

Command	Description
az vmss lifecycle-hook remove	Removes one lifecycle hook (--type) or all lifecycle hooks (--all) from a VMSS

---

Parameter Details

az vmss lifecycle-hook-event update

Parameter	Type	Required	Description
--vmss-name	string	Yes	VMSS name
--resource-group / -g	string	Yes	Resource group
--name / -n	string	Yes	Event name (GUID)
--action-state	string	No	Approved or Rejected.
--wait-until	string	No	ISO 8601 UTC - extend deadline (must be ≤ maxWaitUntil).
--instance-ids	string[]	No	Per-VM targeting. Uniform: decimal IDs (0 1 2); Flex: VM names (myvmss_3ec87a). CLI resolves to full resource IDs. Requires --action-state. Mutually exclusive with --target-resources.
--target-resources	JSON / @file.json	No	Raw targetResources[] escape hatch (mixed states). Mutually exclusive with --instance-ids.
--body	JSON / @file.json	No	Full PATCH request body. Mutually exclusive with other non required params.

az vmss lifecycle-hook-event approve / reject

Same parameters as update, minus --action-state:

Parameter	Type	Required	Description
--vmss-name	string	Yes	VMSS name
--resource-group / -g	string	Yes	Resource group
--name / -n	string	Yes	Event name (GUID)
--instance-ids	string[]	No	Per-VM targeting. Uniform: decimal IDs (0 1 2); Flex: VM names (myvmss_3ec87a). CLI resolves to full resource IDs. Mutually exclusive with --target-resources.
--target-resources	JSON / @file.json	No	Raw targetResources[] escape hatch (mixed states). Mutually exclusive with --instance-ids.

az vmss lifecycle-hook remove

Parameter	Type	Required	Description
--vmss-name	string	Yes	VMSS name
--resource-group / -g	string	Yes	Resource group
--type	string	No*	Hook type to remove. Mutually exclusive with --all.
--all	flag	No*	Remove all lifecycle hooks. Mutually exclusive with --type.

* Exactly one of --type or --all is required.

Implementation note: There is no per-hook DELETE endpoint; API replaces entire lifecycleHooks[] on each PATCH. remove --type is Get → filter → PATCH. remove --all is a single PATCH with { lifecycleHooksProfile: { lifecycleHooks: [] } }.
Should fail when provided --type is not found in the GET payload.

---

Example Usage

# 1) Create VMSS with one hook
az vmss create --name myVmss -g myRg --image Ubuntu2204 \
  --lifecycle-hook-type UpgradeAutoOSScheduling \
  --lifecycle-hook-wait-duration PT4H \
  --lifecycle-hook-wait-duration Approved

# 2) Create with two hooks
az vmss create --name myVmss -g myRg --image Ubuntu2204 \
  --lifecycle-hook-type UpgradeAutoOSScheduling \
  --lifecycle-hook-wait-duration PT4H \
  --lifecycle-hook-wait-duration Approved
  --lifecycle-hook-type UpgradeAutoOSRollingBatchStarting \
  --lifecycle-hook-wait-duration PT30M \
  --lifecycle-hook-wait-duration Approved

# 3) Add a hook to an existing VMSS
az vmss update --name myVmss -g myRg \
  --lifecycle-hook-type UpgradeAutoOSScheduling \
  --lifecycle-hook-wait-duration PT4H \
  --lifecycle-hook-wait-duration Approved

# 4) List events
az vmss lifecycle-hook-event list --vmss-name myVmss -g myRg

# Filter to active events only
az vmss lifecycle-hook-event list --vmss-name myVmss -g myRg \
  --query "[?properties.state=='Active']"

# 5a) Approve all targets (full form)
az vmss lifecycle-hook-event update --vmss-name myVmss -g myRg \
  --name {eventGuid} --action-state Approved

# 5b) Approve all targets (convenience)
az vmss lifecycle-hook-event approve --vmss-name myVmss -g myRg --name {eventGuid}

# 5c) Reject all targets (convenience)
az vmss lifecycle-hook-event reject --vmss-name myVmss -g myRg --name {eventGuid}

# 5d) Approve a subset — Uniform (decimal IDs)
az vmss lifecycle-hook-event update --vmss-name myVmss -g myRg \
  --name {eventGuid} --instance-ids 0 1 2 --action-state Approved

# 5e) Approve a subset — Flex (VM names)
az vmss lifecycle-hook-event update --vmss-name myVmss -g myRg \
  --name {eventGuid} --instance-ids myvmss_3ec87a myvmss_a1b2c3 --action-state Approved

# 5f) Delay the event deadline
az vmss lifecycle-hook-event update --vmss-name myVmss -g myRg \
  --name {eventGuid} --wait-until "2026-05-08T11:00:00Z"

# 6a) Remove one hook type
az vmss lifecycle-hook remove --vmss-name myVmss -g myRg --type UpgradeAutoOSScheduling

# 6b) Remove all hooks
az vmss lifecycle-hook remove --vmss-name myVmss -g myRg --all

---

Long-Running Operations

• VirtualMachineScaleSets_Update (hook config PATCH, removal PATCH) is LRO — standard --no-wait.
• VirtualMachineScaleSetLifeCycleHookEvents_Update (event PATCH) returns 202 Accepted + azure-asyncoperation; AAZ-generated client should poll by default and expose --no-wait.

Code-gen Path

• AAZ CodeGen V2 (preferred) — no Python SDK release needed
• Python SDK + traditional codegen

References

• Swagger PR: Add VMScaleSetLifecycleHookEvent and LifecycleHooksProfile azure-rest-api-specs#39735 (merged, 2025-11-01)
• TypeSpec: specification/compute/Compute.Management/models.tsp, specification/compute/Compute.Management/VirtualMachineScaleSetLifecycleHookEvent.tsp
• Customer documentation: lifecyclehooks-team@microsoft.com

[yonzhan]

Thank you for opening this issue, we will look into it.