[az fleet] updated help examples (#6995)

* updated fleet help text

* bumped version

* help text fix

* white space

* More help text updates.

* fleet list example +1

* lint

* test recording update

* bug fix: return response instead of exception

* updated version notes

* lint fixes

---------

Co-authored-by: pdaru <pdaru@microsoft.com>

src/fleet/HISTORY.rst

@@ -59,4 +59,9 @@ Release History
 1.0.0
 ++++++
 * Promoted extension to GA.
-* Added `az fleet create` preview parameter `vm-size` for Hubful fleets.
+* Added `az fleet create` preview parameter `vm-size` for Hubful fleets.
+
+1.0.1
+++++++
+* Updated help examples.
+* Fixed serialization bug.

src/fleet/azext_fleet/_help.py

@@ -14,57 +14,76 @@
 
 helps['fleet create'] = """
     type: command
-    short-summary: Creates or updates a Fleet.
+    short-summary: Creates or updates a fleet.
     parameters:
         - name: --dns-name-prefix -p
           type: string
-          short-summary: Prefix for hostnames that are created. If not specified, generate a hostname using the
+          short-summary: Prefix for host names that are created. If not specified, generate a host name using the
                          managed cluster and resource group names.
     examples:
-        - name: Create a hubless fleet
-          text: az fleet create -g MyResourceGroup -l MyLocation -n MyFleetName --tags "TagKey=TagValue"
-        - name: Create a hubful fleet
-          text: az fleet create -g MyResourceGroup -l MyLocation -n MyFleetName --enable-hub --tags "TagKey=TagValue"
-
+        - name: Create a hubless fleet.
+          text: az fleet create -g MyFleetResourceGroup -l MyLocation -n MyFleetName --tags "TagKey=TagValue"
+        - name: Create a hubful fleet.
+          text: az fleet create -g MyFleetResourceGroup -l MyLocation -n MyFleetName --enable-hub --tags "TagKey=TagValue"
+        - name: Create a fleet with a system assigned managed service identity.
+          text: az fleet create -g MyFleetResourceGroup -l MyLocation -n MyFleetName --enable-managed-identity
+        - name: Create a fleet with a user provided managed service identity.
+          text: az fleet create -g MyFleetResourceGroup -l MyLocation -n MyFleetName --enable-managed-identity --assign-identity "/subscription/00000000-0000-0000-0000-000000000000/resourcegroup/MyFleetResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/MyIdentity"
 """
 
 helps['fleet update'] = """
     type: command
     short-summary: Patches a fleet resource.
     examples:
-        - name: Update a Fleet's tags
-          text: az fleet update -g MyResourceGroup -n MyFleetName --tags Key=Value
-        - name: Update a Fleet to use a system assigned managed service identity.
-          text: az fleet update -g MyResourceGroup -n MyFleetName --enable-managed-identity --tags Key=Value
-        - name: Update a Fleet to use a user assigned managed service identity.
-          text: az fleet update -g MyResourceGroup -n MyFleetName --enable-managed-identity --assign-identity "/subscription/00000000-0000-0000-0000-000000000000/resourcegroup/MyResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/MyIdentity" --tags Key=Value
+        - name: Update a fleet's tags.
+          text: az fleet update -g MyFleetResourceGroup -n MyFleetName --tags Key=Value
+        - name: Update a fleet to use a system assigned managed service identity.
+          text: az fleet update -g MyFleetResourceGroup -n MyFleetName --enable-managed-identity --tags Key=Value
+        - name: Update a fleet to use a user assigned managed service identity.
+          text: az fleet update -g MyFleetResourceGroup -n MyFleetName --enable-managed-identity --assign-identity "/subscription/00000000-0000-0000-0000-000000000000/resourcegroup/MyFleetResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/MyIdentity" --tags Key=Value
 """
 
 helps['fleet show'] = """
     type: command
-    short-summary: Gets a Fleet.
+    short-summary: Gets a fleet.
+    examples:
+        - name: Show the details of a fleet.
+          text: az fleet show -g MyFleetResourceGroup -n MyFleetName
 """
 
 helps['fleet list'] = """
     type: command
-    short-summary: Lists fleets in the specified subscription and resource group.
+    short-summary: Lists all fleets within a resource group.
+    examples:
+        - name: List all fleets with a specific subscription.
+          text: az fleet list
+        - name: List all fleets that exist within a specific subscription and resource group.
+          text: az fleet list -g MyResourceGroup
 """
 
 helps['fleet delete'] = """
     type: command
-    short-summary: Deletes a Fleet.
+    short-summary: Deletes a fleet.
+    examples:
+        - name: Delete a specific fleet.
+          text: az fleet delete -g MyFleetResourceGroup -n MyFleetName
 """
 
 helps['fleet get-credentials'] = """
     type: command
-    short-summary: Lists the user credentials of a Fleet.
+    short-summary: For hubful fleets, gets the kubeconfig for the fleet's hub cluster.
     parameters:
     - name: --overwrite-existing
       type: bool
       short-summary: Overwrite any existing cluster entry with the same name.
     - name: --file -f
       type: string
       short-summary: Kubernetes configuration file to update. Use "-" to print YAML to stdout instead.
+    examples:
+        - name: Get a fleet's hub cluster kubeconfig.
+          text: az fleet get-credentials -g MyFleetResourceGroup -n MyFleetName
+        - name: Get a fleet's hub cluster kubeconfig, and save it to a specific file.
+          text: az fleet get-credentials -g MyFleetResourceGroup -n MyFleetName -f ~/mykubeconfigfile.txt
 """
 
 helps['fleet wait'] = """
@@ -75,80 +94,97 @@
 
 helps['fleet member'] = """
     type: group
-    short-summary: Commands to manage a fleet member.
+    short-summary: Commands to manage members.
 """
 
 helps['fleet member create'] = """
     type: command
-    short-summary: Creates or updates a fleet member.
+    short-summary: Creates or updates a member.
     parameters:
         - name: --member-cluster-id
           type: string
           short-summary: ID of the managed cluster.
         - name: --update-group
           type: string
-          short-summary: Group of the fleet member.
+          short-summary: Update group of the member.
+    examples:
+        - name: Create a member and assign it to an update group.
+          text: az fleet member create -g MyFleetResourceGroup -f MyFleetName -n NameOfMember --update-group UpdateGroup1 --member-cluster-id "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MyFleetResourceGroup/providers/Microsoft.ContainerService/managedClusters/MyManagedCluster"
 """
 
 helps['fleet member update'] = """
     type: command
-    short-summary: Update a fleet member.
+    short-summary: Update a member.
     parameters:
         - name: --update-group
           type: string
-          short-summary: Group of the fleet member.
+          short-summary: Update group of the member.
+    examples:
+        - name: Update an existing member's update group.
+          text: az fleet member update -g MyFleetResourceGroup -f MyFleetName -n NameOfMember --update-group UpdateGroup2
 """
 
 helps['fleet member list'] = """
     type: command
-    short-summary: Lists the members of a fleet.
+    short-summary: Lists a fleet's members.
+    examples:
+        - name: List all members for a given fleet.
+          text: az fleet member list -g MyFleetResourceGroup -f MyFleetName
 """
 
 helps['fleet member show'] = """
     type: command
-    short-summary: Gets a Fleet member.
+    short-summary: Gets a fleet member.
+    examples:
+        - name: Show the details of a specific fleet member.
+          text: az fleet member show -g MyFleetResourceGroup -f MyFleetName -n NameOfMember
 """
 
 helps['fleet member delete'] = """
     type: command
     short-summary: Deletes a fleet member.
+    examples:
+        - name: Delete a specific fleet member.
+          text: az fleet member delete -g MyFleetResourceGroup -f MyFleetName -n NameOfMember
 """
 
 helps['fleet member wait'] = """
     type: command
-    short-summary: Wait for a fleet member resource to reach a desired state.
-    long-summary: If an operation on fleet member was interrupted or was started with `--no-wait`, use this command to wait for it to complete.
+    short-summary: Wait for a member resource to reach a desired state.
+    long-summary: If an operation on member was interrupted or was started with `--no-wait`, use this command to wait for it to complete.
 """
 
 helps['fleet updaterun'] = """
     type: group
-    short-summary: Commands to manage a fleet update run.
+    short-summary: Commands to manage update runs.
 """
 
 helps['fleet updaterun create'] = """
     type: command
-    short-summary: Creates or updates a fleet update run.
+    short-summary: Creates or updates an update run.
     parameters:
         - name: --upgrade-type
           type: string
-          short-summary: Specify the upgrade type of fleet members. Acceptable values are 'Full' and 'NodeImageOnly'.
+          short-summary: Specify the upgrade type of members. Acceptable values are 'Full' and 'NodeImageOnly'.
         - name: --kubernetes-version
           type: string
-          short-summary: Specify the kubernetes version to upgrade fleet member(s) to, when --upgrade-type is set to 'Full'. Acceptable format is x.x.x (eg. 1.2.3).
+          short-summary: Specify the kubernetes version to upgrade member(s) to, when --upgrade-type is set to 'Full'. Acceptable format is x.x.x (eg. 1.2.3).
         - name: --stages
           type: string
-          short-summary: Path to a json file that defines stages to upgrade a fleet. See examples for further reference.
+          short-summary: Path to a JSON file that defines stages to upgrade a fleet. See examples for reference.
     examples:
-        - name: Create updaterun for a fleet with 'Full' upgrade type.
+        - name: Create an update run for a fleet with 'Full' upgrade type.
           text: az fleet updaterun create -g MyResourceGroup -f MyFleet -n MyUpdateRun --upgrade-type Full --kubernetes-version 1.25.0 --node-image-selection Latest
-        - name: Create updaterun for a fleet with 'NodeImageOnly' upgrade type.
+        - name: Create an update run for a fleet with 'NodeImageOnly' upgrade type.
           text: az fleet updaterun create -g MyResourceGroup -f MyFleet -n MyUpdateRun --upgrade-type NodeImageOnly --node-image-selection Latest
-        - name: Create updaterun for a fleet with 'Full' upgrade type & stages.
+        - name: Create an update run for a fleet with 'Full' upgrade type & stages.
           text: |
             az fleet updaterun create -g MyResourceGroup -f MyFleet -n MyUpdateRun --upgrade-type Full --kubernetes-version 1.25.0 --node-image-selection Latest --stages ./test/stages.json
 
-                A sample json to demonstrate the expected format. It takes a stages array. Each stage consists of the stage name, groups array and an optional afterStageWaitInSeconds integer.
-                Within groups, each group consists of group name, given to a fleet's member(s).
+                The following JSON structure represents example contents of the parameter '--stages ./test/stages.json'.
+                A stages array is composed of one or more stages, each containing one or more groups.
+                Each group contains the 'name' property, which represents the group to which a cluster belongs (see 'az fleet member create --help').
+                Stages have an optional 'afterStageWaitInSeconds' integer property, acting as a delay between stage execution.
                 {
                     "stages": [
                         {
@@ -186,66 +222,94 @@
 
 helps['fleet updaterun show'] = """
     type: command
-    short-summary: Shows a fleet update run.
+    short-summary: Shows an update run.
+    examples:
+        - name: Show the details of an update run.
+          text: az fleet updaterun show -g MyFleetResourceGroup -f MyFleetName -n NameofUpdateRun
 """
 
 helps['fleet updaterun list'] = """
     type: command
-    short-summary: Lists the update runs of a fleet.
+    short-summary: Lists a fleet's update runs.
+    examples:
+        - name: Show the details of an update run.
+          text: az fleet updaterun list -g MyFleetResourceGroup -f MyFleetName
 """
 
 helps['fleet updaterun delete'] = """
     type: command
-    short-summary: Deletes a fleet update run.
+    short-summary: Deletes an update run.
+    examples:
+        - name: Delete an update run.
+          text: az fleet updaterun delete -g MyFleetResourceGroup -f MyFleetName -n NameofUpdateRun
 """
 
 helps['fleet updaterun start'] = """
     type: command
-    short-summary: Starts a fleet update run.
+    short-summary: Starts an update run.
+    examples:
+        - name: Start an update run.
+          text: az fleet updaterun start -g MyFleetResourceGroup -f MyFleetName -n NameofUpdateRun
 """
 
 helps['fleet updaterun stop'] = """
     type: command
-    short-summary: Stops a fleet update run.
+    short-summary: Stops an update run.
+    examples:
+        - name: Stop an update run.
+          text: az fleet updaterun stop -g MyFleetResourceGroup -f MyFleetName -n NameofUpdateRun
+
 """
 
 helps['fleet updaterun wait'] = """
     type: command
-    short-summary: Wait for a fleet updateraun resource to reach a desired state.
-    long-summary: If an operation on fleet updateraun was interrupted or was started with `--no-wait`, use this command to wait for it to complete.
+    short-summary: Wait for an update run resource to reach a desired state.
+    long-summary: If an operation on an update run was interrupted or was started with `--no-wait`, use this command to wait for it to complete.
 """
 
 helps['fleet updatestrategy'] = """
     type: group
-    short-summary: Commands to manage a fleet update strategy.
+    short-summary: Commands to manage update strategies.
 """
 
 helps['fleet updatestrategy create'] = """
     type: command
-    short-summary: Creates or updates a update strategy
+    short-summary: Creates or updates an update strategy.
     parameters:
         - name: --stages
           type: string
-          short-summary: Path to a json file that defines the update strategy.
+          short-summary: Path to a JSON file that defines the update strategy.
+    examples:
+        - name: Create an update strategy from a JSON file.
+          text: az fleet updatestrategy create -g MyFleetResourceGroup -f MyFleetName -n MyUpdateStrategy --stages MyUpdateStrategyFile.json
 """
 
 helps['fleet updatestrategy show'] = """
     type: command
-    short-summary: Shows a update strategy.
+    short-summary: Shows an update strategy.
+    examples:
+        - name: Show the details of an update strategy.
+          text: az fleet updatestrategy show -g MyFleetResourceGroup -f MyFleetName -n MyUpdateStrategy
 """
 
 helps['fleet updatestrategy list'] = """
     type: command
     short-summary: Lists the fleet's update strategies.
+    examples:
+        - name: List all update strategies for a given fleet.
+          text: az fleet updatestrategy list -g MyFleetResourceGroup -f MyFleetName
 """
 
 helps['fleet updatestrategy delete'] = """
     type: command
     short-summary: Deletes a update strategy.
+    examples:
+        - name: Delete an update strategy.
+          text: az fleet updatestrategy delete -g MyFleetResourceGroup -f MyFleetName -n MyUpdateStrategy
 """
 
 helps['fleet updatestrategy wait'] = """
     type: command
-    short-summary: Wait for a fleet updatestrategy resource to reach a desired state.
-    long-summary: If an operation on fleet updatestrategy was interrupted or was started with `--no-wait`, use this command to wait for it to complete.
+    short-summary: Wait for a update strategy resource to reach a desired state.
+    long-summary: If an operation on an update strategy was interrupted or was started with `--no-wait`, use this command to wait for it to complete.
 """

src/fleet/azext_fleet/custom.py

@@ -333,14 +333,9 @@ def create_update_run(cmd,
         strategy=update_run_strategy,
         managed_cluster_update=managed_cluster_update)
 
-    result = None
-    try:
-        result = sdk_no_wait(no_wait, client.begin_create_or_update, resource_group_name, fleet_name, name, update_run)
-        print("After successfully creating the run, you need to use the following command to start the run:"
-              f"az fleet updaterun start --resource-group={resource_group_name} --fleet={fleet_name} --name={name}")
-    except Exception as e:
-        return e
-
+    result = sdk_no_wait(no_wait, client.begin_create_or_update, resource_group_name, fleet_name, name, update_run)
+    print("After successfully creating the run, you need to use the following command to start the run:"
+          f"az fleet updaterun start --resource-group={resource_group_name} --fleet={fleet_name} --name={name}")
     return result