Local groups: 3 of 4 write cmdlets omit the required local_directory_service_names key and cannot reach the array

[juemerson-at-purestorage]

Found while working #58. Two things, one wire defect and one documentation defect, both in the local-groups family.

Part 1 — three of four write cmdlets cannot reach the array at all

POST, DELETE and PATCH on /directory-services/local/groups, and POST/DELETE on /directory-services/local/groups/members, all declare local_directory_service_names and local_directory_service_ids. The array treats one of them as required: with neither supplied it refuses the request outright rather than inferring the parent, even when exactly one local directory service exists on the array.

Only New-PfbLocalGroupMember exposes a parameter for it (-LocalDirectoryService → local_directory_service_names). The other three send nothing, and there is no argument a caller can pass to work around it:

Cmdlet	Endpoint	Array's response
New-PfbLocalGroup	POST /directory-services/local/groups	HTTP 400: Local directory service identifier is required.
Remove-PfbLocalGroup	DELETE /directory-services/local/groups	HTTP 400: Local directory service identifier is required.
Remove-PfbLocalGroupMember	DELETE /directory-services/local/groups/members	HTTP 400: Local directory service does not exist.

So the family's write side is unusable: you cannot create a local group, delete one, or remove a member from one. New-PfbLocalGroupMember works, which produces a membership the module cannot subsequently remove.

Evidence

Live on an AD-joined FlashBlade, Purity//FB with REST 2.26 as the negotiated version, code under test fix/stale-coverage-gates@af78fc4, connected as the local array account.

The same DELETE succeeds the moment the key is supplied, which is what isolates this to the missing parameter rather than to the endpoint or to permissions:

# through Remove-PfbLocalGroupMember -Group <grp> -Member <user>
DELETE /api/2.26/directory-services/local/groups/members
       ?group_names=<grp>&member_names=<user>
HTTP 400: Local directory service does not exist.

# byte-identical, plus the one key the cmdlet has no parameter for
DELETE /api/2.26/directory-services/local/groups/members
       ?group_names=<grp>&member_names=<user>
       &local_directory_service_names=<realm>::<domain>
200 OK

And the create, with New-PfbLocalGroupMember's existing -LocalDirectoryService supplied, passes end to end — so the parameter is the right shape, it is simply missing from three of its four siblings:

POST /api/2.26/directory-services/local/groups/members
     ?group_names=<grp>&local_directory_service_names=<realm>::<domain>
     { "members": [ { "member": { "name": "<user>" } } ] }
200 OK  -> group=<grp> member=<user> is_primary_group=false member_id=1000

A control ruled out the account and the session as explanations: a New-PfbFileSystem / Update-PfbFileSystem -Destroyed / Remove-PfbFileSystem -Eradicate lifecycle through the same connection passed on all three calls.

Suggested fix

Add -LocalDirectoryService to New-PfbLocalGroup, Remove-PfbLocalGroup and Remove-PfbLocalGroupMember, mapping to local_directory_service_names, matching the parameter New-PfbLocalGroupMember already declares. Worth considering in the same change:

• The endpoints also declare local_directory_service_ids; a -LocalDirectoryServiceId sibling would match how the rest of the module treats name/id pairs, though nothing observed here requires it.
• Update-PfbLocalGroup does not exist, and PATCH /directory-services/local/groups does. Out of scope for this issue, noted so it is not lost — it belongs with Local directory services — local user/group cmdlets #36.
• Whether the parameter should be [Parameter(Mandatory)]. The array requires it in practice, but that is observed behaviour on one REST version rather than a required: true in the spec, so a non-mandatory parameter with the array supplying the error may be the more conservative choice.

Part 2 — the documented example name is illegal

New-PfbLocalGroup and New-PfbLocalGroupMember both document the group name as domain-qualified:

New-PfbLocalGroup -Name "mydomain\share-admins"
New-PfbLocalGroupMember -Group "mydomain\share-admins" -Member "CORP\jdoe"

The array rejects that form. A local group name is bare — the parent travels in the query key from Part 1, not in the name — and it is length-limited:

POST /api/2.26/directory-services/local/groups
     ?names=<domain>\<group>&local_directory_service_names=<realm>::<domain>
HTTP 400: Group name is not valid. Group must be between 1 and 20 characters and
          cannot contain /\[]:;|=,+*?"@

Note \ is in the forbidden set, so the documented form cannot ever be a valid group name, and 20 characters is the whole budget. Copying either example verbatim fails twice over: once on the separator and, once Part 1 is fixed, again on anything longer than 20 characters.

-Member is a different matter and its DOMAIN\user documentation is not contradicted here — that value is a reference to an identity rather than a name the array validates under this rule. See #58 for what the array actually does with it.

The 20-character limit and the forbidden-character set are array-reported, not spec-declared — neither appears in tools/specs/fb2.26.json or fb2.28.json. Stating them in the docstrings is still an improvement over an example that cannot work, but they should be described as the array's behaviour rather than as a documented constraint.

Acceptance

• New-PfbLocalGroup, Remove-PfbLocalGroup and Remove-PfbLocalGroupMember accept -LocalDirectoryService and send local_directory_service_names.
• A live create → read → add member → remove member → delete lifecycle completes against a real array with no raw-REST step needed anywhere in it.
• The docstring examples use a legal bare group name.

Related: #36 (the family's coverage roadmap), #58 (external-principal membership, which is a separate question and blocked for other reasons), #127 (Remove-PfbLocalGroup's end-block structure — same cmdlet, unrelated defect).