Skip to content

Commit 65efff1

Browse files
author
User
committed
docs: add spec for removing SQL VM LightWeight mode
Remove LightWeight as an accepted value for --sql-mgmt-type, default to Full mode on az sql vm create. Retain --sql-mgmt-type for NoAgent (EOS SQL 2008/R2) only. Classified as a breaking change.
1 parent eb0633e commit 65efff1

File tree

4 files changed

+299
-0
lines changed

4 files changed

+299
-0
lines changed

‎.gitmodules‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
[submodule ".speckit"]
2+
path = .speckit
3+
url = https://msdata.visualstudio.com/Database%20Systems/_git/SpecKit
4+
branch = main

‎.speckit‎

Submodule .speckit added at 8e68cab

‎specs/dev/user/remove-sqlvm-lightweight/checklists/requirements.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Specification Quality Checklist: Remove SQL VM Lightweight Mode
2+
3+
**Purpose**: Validate specification completeness and quality before proceeding to planning
4+
**Created**: 2026-02-08
5+
**Feature**: [spec.md](../spec.md)
6+
7+
## Content Quality
8+
9+
- [x] No implementation details (languages, frameworks, APIs)
10+
- [x] Focused on user value and business needs
11+
- [x] Written for non-technical stakeholders
12+
- [x] All mandatory sections completed
13+
14+
## Requirement Completeness
15+
16+
- [x] No [NEEDS CLARIFICATION] markers remain
17+
- [x] Requirements are testable and unambiguous
18+
- [x] Success criteria are measurable
19+
- [x] Success criteria are technology-agnostic (no implementation details)
20+
- [x] All acceptance scenarios are defined
21+
- [x] Edge cases are identified
22+
- [x] Scope is clearly bounded
23+
- [x] Dependencies and assumptions identified
24+
25+
## Feature Readiness
26+
27+
- [x] All functional requirements have clear acceptance criteria
28+
- [x] User scenarios cover primary flows
29+
- [x] Feature meets measurable outcomes defined in Success Criteria
30+
- [x] No implementation details leak into specification
31+
32+
## Notes
33+
34+
- All items pass validation. The specification is ready for `/speckit.clarify` or `/speckit.plan`.
35+
- FR-005 (NoAgent mode preservation) is an important constraint that must carry through to planning.
36+
- The spec references specific CLI parameter names (`--sql-mgmt-type`) and command names (`az sql vm create`) which are part of the problem domain, not implementation details.

‎specs/dev/user/remove-sqlvm-lightweight/spec.md‎

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
# Feature Specification: Remove SQL VM Lightweight Mode
2+
3+
**Feature Branch**: `dev/user/remove-sqlvm-lightweight`
4+
**Created**: 2026-02-08
5+
**Status**: Draft
6+
**Input**: User description: "Remove lightweight mode option from Azure SQL VM extension, defaulting to full mode"
7+
8+
## User Scenarios & Testing *(mandatory)*
9+
10+
### User Story 1 - Create SQL VM defaults to Full mode (Priority: P1)
11+
12+
As a customer creating an Azure SQL VM via the CLI, I want the SQL IaaS Extension
13+
to deploy in Full mode by default, so that I have access to all management
14+
features (automated backup, patching, connectivity configuration, SQL assessment)
15+
without needing to specify any additional flags.
16+
17+
**Why this priority**: This is the core behavioral change. Full mode is the
18+
recommended extension mode going forward and should be the default experience
19+
for all new SQL VM registrations.
20+
21+
**Independent Test**: Create a SQL VM with `az sql vm create` without specifying
22+
`--sql-mgmt-type`. Verify the resulting SQL VM resource has
23+
`sqlManagement` set to `Full`.
24+
25+
**Acceptance Scenarios**:
26+
27+
1. **Given** a user runs `az sql vm create` without `--sql-mgmt-type`,
28+
**When** the SQL VM is created,
29+
**Then** the `sqlManagement` property on the created resource MUST be `Full`.
30+
31+
2. **Given** a user runs `az sql vm create` with `--sql-mgmt-type Full` (while
32+
the parameter still exists during deprecation),
33+
**When** the SQL VM is created,
34+
**Then** the `sqlManagement` property MUST be `Full` and a deprecation
35+
warning MUST be emitted.
36+
37+
---
38+
39+
### User Story 2 - Remove LightWeight as an accepted value (Priority: P1)
40+
41+
As a CLI maintainer, I want the `LightWeight` value to no longer be accepted
42+
for `--sql-mgmt-type`, so that customers cannot accidentally deploy the
43+
extension in a limited mode.
44+
45+
**Why this priority**: Removing the LightWeight option is the direct
46+
requirement. Customers relying on lightweight mode need to be moved to full
47+
mode, and allowing LightWeight defeats the purpose of the change.
48+
49+
**Independent Test**: Attempt to run `az sql vm create --sql-mgmt-type LightWeight`.
50+
Verify the command rejects the value or ignores it with a clear warning.
51+
52+
**Acceptance Scenarios**:
53+
54+
1. **Given** a user runs `az sql vm create --sql-mgmt-type LightWeight`,
55+
**When** the CLI processes the command,
56+
**Then** the CLI MUST raise a hard error stating that LightWeight mode is
57+
no longer supported and the user should remove the `--sql-mgmt-type` flag
58+
(which defaults to Full) or use `NoAgent` if applicable.
59+
60+
2. **Given** a user runs `az sql vm update --sql-mgmt-type LightWeight`,
61+
**When** the CLI processes the command,
62+
**Then** the CLI MUST raise a hard error with the same message.
63+
64+
---
65+
66+
### User Story 3 - Restrict --sql-mgmt-type to Full and NoAgent (Priority: P2)
67+
68+
As a CLI maintainer, I want `--sql-mgmt-type` to only accept `Full` and
69+
`NoAgent` values (removing `LightWeight`), so that the parameter remains
70+
available for the NoAgent legacy scenario while preventing LightWeight usage.
71+
72+
**Why this priority**: The parameter must be retained for NoAgent (EOS SQL
73+
2008/R2) but LightWeight must be eliminated. Restricting accepted values
74+
achieves both goals without introducing new flags.
75+
76+
**Independent Test**: Run `az sql vm create --sql-mgmt-type Full` and verify a
77+
deprecation or removal message is displayed. Confirm `az sql vm create --help`
78+
no longer lists `--sql-mgmt-type` (or marks it deprecated).
79+
80+
**Acceptance Scenarios**:
81+
82+
1. **Given** the `--sql-mgmt-type` parameter is removed from `create`,
83+
**When** a user runs `az sql vm create --sql-mgmt-type Full`,
84+
**Then** the CLI MUST emit a deprecation warning (or error if fully removed)
85+
indicating the parameter is no longer needed.
86+
87+
2. **Given** the `--sql-mgmt-type` parameter is removed from `update`,
88+
**When** a user runs `az sql vm update --sql-mgmt-type Full`,
89+
**Then** the CLI MUST emit a deprecation warning (or error if fully removed).
90+
91+
---
92+
93+
### User Story 4 - Handle NoAgent mode (Priority: P2)
94+
95+
As a customer with an end-of-support SQL Server 2008/R2 VM, I need to
96+
continue using `--sql-mgmt-type NoAgent` with `--image-sku` and
97+
`--image-offer` to register my VM without an agent.
98+
99+
**Why this priority**: NoAgent is a distinct use case for legacy SQL Server
100+
versions. The existing `--sql-mgmt-type` parameter continues to serve this
101+
purpose without any mechanism change.
102+
103+
**Independent Test**: Run `az sql vm create --sql-mgmt-type NoAgent --image-sku <sku> --image-offer <offer>` and verify successful NoAgent registration.
104+
105+
**Acceptance Scenarios**:
106+
107+
1. **Given** a user needs NoAgent mode for SQL 2008 R2,
108+
**When** they create a SQL VM with the appropriate flags,
109+
**Then** the system MUST still allow NoAgent registration with `--image-sku`
110+
and `--image-offer`.
111+
112+
---
113+
114+
### User Story 5 - Update help text and examples (Priority: P3)
115+
116+
As a CLI user reading documentation, I want the help text and examples for
117+
`az sql vm create` and `az sql vm update` to reflect the new behavior—no
118+
mention of LightWeight mode, and clear guidance that Full mode is the default.
119+
120+
**Why this priority**: Documentation accuracy ensures users understand the
121+
current behavior without confusion.
122+
123+
**Independent Test**: Run `az sql vm create --help` and `az sql vm update --help`.
124+
Verify no references to LightWeight mode remain, and examples reflect
125+
Full mode as default.
126+
127+
**Acceptance Scenarios**:
128+
129+
1. **Given** a user runs `az sql vm create --help`,
130+
**When** the help text is displayed,
131+
**Then** it MUST NOT reference LightWeight mode and MUST indicate Full
132+
mode is the default.
133+
134+
2. **Given** a user runs `az sql vm update --help`,
135+
**When** the help text is displayed,
136+
**Then** it MUST NOT reference LightWeight mode.
137+
138+
---
139+
140+
### Edge Cases
141+
142+
- What happens when an existing SQL VM was registered in LightWeight mode and
143+
a user runs `az sql vm update`? The update should not forcibly change the
144+
mode, but should no longer offer LightWeight as a settable option.
145+
- What happens when `--sql-mgmt-type NoAgent` is used without the required
146+
`--image-sku` and `--image-offer`? The existing validation error must
147+
continue to function.
148+
- What happens when `--least-privilege-mode Enabled` is used? The current
149+
validator requires `--sql-mgmt-type Full`. Since Full is now the default,
150+
this validation should still pass but may need updating to no longer
151+
reference `--sql-mgmt-type` in the error message.
152+
- What happens with existing automation scripts that explicitly pass
153+
`--sql-mgmt-type LightWeight`? They will receive clear error messages
154+
indicating the value is no longer supported.
155+
156+
## Clarifications
157+
158+
### Session 2026-02-08
159+
160+
- Q: Should `--sql-mgmt-type` be fully removed or retained for NoAgent? → A: Keep `--sql-mgmt-type` but restrict accepted values to `Full` and `NoAgent` only (remove `LightWeight`).
161+
- Q: Should passing `LightWeight` produce a warning+override or a hard error? → A: Raise a hard error telling the user `LightWeight` is no longer supported.
162+
- Q: How should this change be classified for release? → A: Full breaking change with major release note and migration guidance.
163+
- Q: Should the registration pipeline still be able to create VMs in LightWeight mode? → A: Yes. The server-side registration pipeline retains LightWeight mode; only the Azure CLI blocks it.
164+
165+
## Requirements *(mandatory)*
166+
167+
### Functional Requirements
168+
169+
- **FR-001**: The `az sql vm create` command MUST default the `sql_management`
170+
property to `Full` instead of `LightWeight`.
171+
172+
- **FR-002**: The `LightWeight` value MUST be removed from the set of accepted
173+
values for `--sql-mgmt-type` on both `create` and `update` commands. Passing
174+
`LightWeight` MUST raise a hard error (not a warning) with a message
175+
directing the user to remove the flag or use `NoAgent`.
176+
177+
- **FR-003**: The `--sql-mgmt-type` parameter MUST be retained on both
178+
`az sql vm create` and `az sql vm update`, but its accepted values MUST
179+
be restricted to `Full` and `NoAgent` only. The `LightWeight` value MUST
180+
be rejected with a clear error message.
181+
182+
- **FR-004**: The `--sql-mgmt-type` parameter MUST continue to show a
183+
deprecation warning when used, since `Full` is now the default and the
184+
parameter is only needed for the `NoAgent` scenario.
185+
186+
- **FR-005**: The `NoAgent` mode MUST remain accessible via
187+
`--sql-mgmt-type NoAgent` for end-of-support SQL Server 2008/R2 scenarios.
188+
No new flags are needed; the existing parameter serves this purpose.
189+
190+
- **FR-006**: The `validate_sqlmanagement` validator MUST be updated to reflect
191+
the removal of LightWeight mode.
192+
193+
- **FR-007**: The `validate_least_privilege_mode` validator MUST be updated to
194+
no longer require explicit `--sql-mgmt-type Full`, since Full is now the
195+
implicit default.
196+
197+
- **FR-008**: All help text MUST be updated to remove references to LightWeight
198+
mode and reflect the new default behavior.
199+
200+
- **FR-009**: All CLI tests MUST be updated to reflect the new default
201+
(`Full` instead of `LightWeight`) and to remove test cases that exercise
202+
LightWeight mode.
203+
204+
- **FR-010**: The changelog MUST be updated with an entry documenting this
205+
as a full breaking change. The entry MUST include migration guidance
206+
instructing users to remove `--sql-mgmt-type LightWeight` from scripts
207+
(Full is now the default) or switch to `--sql-mgmt-type NoAgent` if
208+
applicable.
209+
210+
### Key Entities
211+
212+
- **SqlVirtualMachine**: The primary resource representing a SQL Server
213+
instance on an Azure VM. The `sql_management` property controls the
214+
extension mode (`Full`, `NoAgent`; `LightWeight` being removed).
215+
216+
- **SqlManagementMode enum**: The SDK enum that defines accepted values.
217+
The CLI must stop exposing `LightWeight` even if the SDK still defines it.
218+
219+
- **IaaS Extension (SQL IaaS Agent)**: The Azure extension installed on the
220+
VM, whose behavior depends on the management mode.
221+
222+
## Success Criteria *(mandatory)*
223+
224+
### Measurable Outcomes
225+
226+
- **SC-001**: 100% of new SQL VM creations via `az sql vm create` (without
227+
explicit mode flag) result in `sqlManagement=Full`.
228+
229+
- **SC-002**: Any CLI invocation with `--sql-mgmt-type LightWeight` produces
230+
a hard error with an actionable message; the command does not execute.
231+
232+
- **SC-003**: All existing CLI tests pass after the change, with updated
233+
assertions reflecting the new default.
234+
235+
- **SC-004**: The `az sql vm create --help` and `az sql vm update --help`
236+
output contains zero references to LightWeight mode.
237+
238+
- **SC-005**: NoAgent mode continues to function correctly for SQL 2008/R2
239+
scenarios without regression.
240+
241+
- **SC-006**: The `--least-privilege-mode Enabled` flag works without
242+
requiring an explicit `--sql-mgmt-type Full` argument.
243+
244+
## Assumptions
245+
246+
- The Azure SQL VM SDK server-side API continues to accept `Full` as a valid
247+
`sql_management` value.
248+
- The server-side registration pipeline continues to support LightWeight mode.
249+
This CLI change does NOT affect the registration pipeline or the underlying
250+
API—only the `az sql vm` CLI commands block LightWeight as a user-selectable
251+
option.
252+
- The `NoAgent` mode remains a valid server-side option and must be preserved.
253+
- The `--sql-mgmt-type` parameter is already marked as deprecated in the
254+
current codebase; this change completes the deprecation by removing
255+
LightWeight and making the parameter unnecessary for the common case.
256+
- Existing SQL VMs registered in LightWeight mode (via any pathway) are not
257+
affected by this CLI change—the server-side resource retains its current
258+
mode. This change only affects new CLI operations.

0 commit comments

Comments
 (0)