feat: add FlexGroup create support to create_volume #215

Context

create_volume today always maps a single aggregate_name and never sets style or FlexGroup placement fields. Agents cannot create a FlexGroup through the typed tool and have to drop to REST.

ONTAP uses one POST /api/storage/volumes catalog for every personality. GET /api/cluster disaggregated and san_optimized change what that POST means. This proposal extends create_volume for Unified NAS FlexGroups and fails closed on personalities where that body is wrong, instead of sending a Unified FlexGroup payload at the wrong cluster.

Related: #189 (AFX volume create requires omitting aggregates / using constituent_count). This issue does not implement that AFX success path.

I plan to open a pull request for this.

Gap

create_volume cannot express:

• style=flexgroup
• multiple aggregates
• constituents_per_aggregate
• optimize_aggregates (CLI optimize-aggr-list)
• granular data mode (disabled / basic / advanced)

aggregate_name is also schema-required, so a FlexGroup call cannot omit the singular field.

Proposal

Extend tool.VolumeCreate only (not update_volume):

• style — flexvol (default) or flexgroup. Reject flexgroup_constituent.
• aggregate_names — required when style=flexgroup.
• constituents_per_aggregate — optional on FlexGroup (ONTAP defaults to 4 when multiple aggregates are given).
• optimize_aggr_list — optional bool, default false (same as REST). Omit REST optimize_aggregates unless the agent sets true.
• granular_data — disabled (default), basic, or advanced. Maps to REST granular_data + granular_data_mode. Omit both REST fields when disabled.

Make aggregate_name schema-optional (omitzero) and enforce in newCreateVolume:

• Cannot set both aggregate_name and aggregate_names.
• FlexVol: aggregate_name required; reject FlexGroup-only fields.
• FlexGroup: aggregate_names required (len >= 1). Do not infer FlexGroup from a multi-name list if style is omitted. Do not allow FlexGroup with no aggregates (UDO auto-provision).

Existing fields (size, nas.path, guarantee.type, efficiency, QoS, snapshot policy) stay as they are.

create_volume will read cluster disaggregated / san_optimized (already fetched in GetClusterInfo) and apply these gates before building the REST body:

• Unified NAS (AFF/FAS): FlexVol and FlexGroup as above.
• Classic ASA (san_optimized, not disaggregated): FlexVol allowed; FlexGroup refused (ONTAP 13107413).
• AFX (disaggregated, not SAN-optimized): FlexGroup fields refused (placement omits aggregates; see volume provisioning in AFX cluster failed with error #189).
• ASA r2 (both flags): create_volume refused; provision a storage unit instead.

Out of scope

• AFX auto-placement (constituent_count, omit aggregates)
• ASA r2 storage-unit provisioning
• FlexGroup expand on update_volume
• Aggregate/disk lifecycle
• A separate create_flexgroup tool

Files

• tool/tool.go — FlexGroup fields on VolumeCreate; aggregate_name omitzero
• ontap/ontap.go — constituents_per_aggregate, optimize_aggregates, granular_data, granular_data_mode
• server/volume.go — personality-aware newCreateVolume
• rest/client.go — accessor for cached cluster flags (avoid a second /api/cluster when possible)
• server/volume_test.go — JSON-body and rejection tests
• descriptions/descriptions.go, docs/tools.md, docs/examples.md

Test plan

Unit tests for: FlexVol body unchanged when new fields are unset; FlexGroup body with two aggregates and constituents_per_aggregate; reject both aggregate fields; reject FlexGroup without aggregate_names; reject flexgroup_constituent; reject FlexGroup fields on FlexVol; optimize_aggr_list omit/true; granular_data disabled/basic/advanced/invalid; classic ASA FlexGroup refuse; ASA r2 create refuse; AFX FlexGroup-field refuse. FlexVol on classic ASA remains allowed.