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

[fitzgeraldsteele]

Summary

VMSS Lifecycle Hooks (LCH) is a new event-driven control-plane feature (API version 2025-11-01) that lets customers register hooks to be notified before Auto OS Upgrade phases and respond to per-VM events before the platform proceeds.

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: TBD
PM: Jerry Steele (fisteele@microsoft.com / @fisteele)
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 (1 hr default wait, 2 days max)
• UpgradeAutoOSRollingBatchStarting — fires before each rolling-upgrade batch (30 min default, 4 hr max)

Preview note: Clients accept the full schema enums (Approve/Reject, Approved/Rejected). The platform returns a server-side validation error for Reject/Rejected during private preview. No client change is required at GA. --lifecycle-hook-default-action defaults to Approve; customers should normally omit it.

---

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. PT8H). 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). Reject returns a server error during preview. 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.

---

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 event by name (GUID)
az vmss lifecycle-hook-event update	Respond to an event (approve / reject / delay / per-VM subset)
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 (server returns validation error during preview)

Subgroup: az vmss lifecycle-hook

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

az vmss lifecycle-hook (hook config management) is a separate subgroup from az vmss lifecycle-hook-event (responding to events). Reserved for future hook CRUD operations (VM Create/Delete hook types).

---

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 (schema). Rejected returns a server error during preview.
--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	No	Raw targetResources[] escape hatch (mixed states). Mutually exclusive with --instance-ids.
--body	JSON / file	No	Full PATCH request body. Overrides other 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	Target specific VMs only

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 (verified against CRP LchProfileInputProcessor.cs): 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: [] } }. Removal does not require AFEC re-validation.

---

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 PT8H

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

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

# 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 (returns server error during preview)
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: lch-team@microsoft.com

[yonzhan]

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

[microsoft-github-policy-service]

🔔 Routing this issue to @act-observability-squad.