search

Azure / azure-cli

Azure Command-Line Interface
MIT License
4.02k stars 2.99k forks source link

Built-in examples are replaced by generated ones in Cloud Shell #19575

Open jiasli opened 3 years ago

jiasli commented 3 years ago

Previously, changes on core are made to incorporate azext_ai_examples:

In Cloud Shell, azext_ai_examples is pre-installed. It replaces built-in hand-crafted high-qualify large-quantity examples with auto-generated low-quality small-quantity examples.

For example, for az vm create --help:

Cloud Shell:

Examples
    Create an Azure Virtual Machine. (autogenerated)
        az vm create --admin-username deploy --generate-ssh-keys --image Centos --name MyVm
        --resource-group MyResourceGroup

    Create a default Ubuntu VM with automatic SSH authentication.
        az vm create --name MyVm --resource-group MyResourceGroup --image UbuntuLTS

    Create a VM by attaching to a managed operating system disk.
        az vm create --resource-group MyResourceGroup --name MyVm --attach-os-disk MyOsDisk --os-
        type linux

    Create an Ubuntu Linux VM using a cloud-init script for configuration. See:
    https://docs.microsoft.com/azure/virtual-machines/virtual-machines-linux-using-cloud-init.
        az vm create --resource-group MyResourceGroup --name MyVm --image debian --custom-data
        MyCloudInitScript.yml

    Create a default Windows Server VM with a private IP address.
        az vm create --name MyVm --resource-group MyResourceGroup --public-ip-address "" --image
        Win2012R2Datacenter

Some examples are even wrong:

Locally:

Examples
    Create a default Ubuntu VM with automatic SSH authentication.
        az vm create -n MyVm -g MyResourceGroup --image UbuntuLTS

    Create a default RedHat VM with automatic SSH authentication using an image URN.
        az vm create -n MyVm -g MyResourceGroup --image RedHat:RHEL:7-RAW:7.4.2018010506

    Create a default Windows Server VM with a private IP address.
        az vm create -n MyVm -g MyResourceGroup --public-ip-address "" --image Win2012R2Datacenter

    Create a VM from a custom managed image.
        az vm create -g MyResourceGroup -n MyVm --image MyImage

    Create a VM from a generalized gallery image version.
        az vm create -g MyResourceGroup -n MyVm --image /subscriptions/00000000-0000-0000-0000-00000
        0000000/resourceGroups/myRG/providers/Microsoft.Compute/galleries/myGallery/images/myImage/v
        ersions/1.0.0

    Create a VM from a specialized gallery image version.
        az vm create -g MyResourceGroup -n MyVm --image /subscriptions/00000000-0000-0000-0000-00000
        0000000/resourceGroups/myRG/providers/Microsoft.Compute/galleries/myGallery/images/myImage/v
        ersions/1.0.0 --specialized

    Create a VM from the latest version of a gallery image
        az vm create -g MyResourceGroup -n MyVm --image /subscriptions/00000000-0000-0000-0000-00000
        0000000/resourceGroups/myRG/providers/Microsoft.Compute/galleries/myGallery/images/myImage

    Create a VM by attaching to a managed operating system disk.
        az vm create -g MyResourceGroup -n MyVm --attach-os-disk MyOsDisk --os-type linux

    Create an Ubuntu Linux VM using a cloud-init script for configuration. See:
    https://docs.microsoft.com/azure/virtual-machines/linux/using-cloud-init.
        az vm create -g MyResourceGroup -n MyVm --image debian --custom-data MyCloudInitScript.yml

    Create a Debian VM with SSH key authentication and a public DNS entry, located on an existing
    virtual network and availability set.
        az vm create -n MyVm -g MyResourceGroup --image debian --vnet-name MyVnet --subnet subnet1 \
            --availability-set MyAvailabilitySet --public-ip-address-dns-name MyUniqueDnsName \
            --ssh-key-values @key-file

    Create a simple Ubuntu Linux VM with a public IP address, DNS entry, two data disks (10GB and
    20GB), and then generate ssh key pairs.
        az vm create -n MyVm -g MyResourceGroup --public-ip-address-dns-name MyUniqueDnsName \
            --image ubuntults --data-disk-sizes-gb 10 20 --size Standard_DS2_v2 \
            --generate-ssh-keys

    Create a Debian VM using Key Vault secrets.
        az keyvault certificate create --vault-name vaultname -n cert1 \
          -p "$(az keyvault certificate get-default-policy)"

        secrets=$(az keyvault secret list-versions --vault-name vaultname \
          -n cert1 --query "[?attributes.enabled].id" -o tsv)

        vm_secrets=$(az vm secret format -s "$secrets")

        az vm create -g group-name -n vm-name --admin-username deploy  \
          --image debian --secrets "$vm_secrets"

    Create a CentOS VM with a system assigned identity. The VM will have a 'Contributor' role with
    access to a storage account.
        az vm create -n MyVm -g rg1 --image centos --assign-identity [system] --scope
        /subscriptions/99999999-1bf0-4dda-
        aec3-cb9272f09590/MyResourceGroup/myRG/providers/Microsoft.Storage/storageAccounts/storage1

    Create a debian VM with a user assigned identity.
        az vm create -n MyVm -g rg1 --image debian --assign-identity
        /subscriptions/99999999-1bf0-4dda-aec3-cb9272f09590/resourcegroups/myRG/providers/Microsoft.
        ManagedIdentity/userAssignedIdentities/myID

    Create a debian VM with both system and user assigned identity.
        az vm create -n MyVm -g rg1 --image debian --assign-identity [system]
        /subscriptions/99999999-1bf0-4dda-aec3-cb9272f09590/resourcegroups/myRG/providers/Microsoft.
        ManagedIdentity/userAssignedIdentities/myID

    Create a VM in an availability zone in the current resource group's region.
        az vm create -n MyVm -g MyResourceGroup --image Centos --zone 1

    Create multiple VMs. In this example, 3 VMs are created. They are MyVm0, MyVm1, MyVm2.
        az vm create -n MyVm -g MyResourceGroup --image centos --count 3

    Create a VM from shared gallery image (private preview feature, please contact shared image
    gallery team by email sigpmdev@microsoft.com to register for preview if you're interested in
    using this feature).
        az vm create -n MyVm -g MyResourceGroup --image
        /SharedGalleries/{gallery_unique_name}/Images/{image}/Versions/{version}

This impedes Azure CLI's capability in Cloud Shell.

jiasli commented 3 years ago

Known problems with AI-generated examples:

  1. Without human inspection, the command may be wrong, or not follow the best practice.
  2. The command may be too old and not work work anymore due to breaking changes.
  3. The example description may be too old and contain incorrect or deprecated contents, like URLs.
  4. The number of auto-generated examples are significantly smaller than built-in hand-written ones.
  5. There may be duplicate examples that are very similar, providing less useful information.
jiasli commented 3 years ago

The examples of az login are completely erased:

$ az login --help

Examples
    Log in interactively.
        az login

Locally:

Examples
    Log in interactively.
        az login

    Log in with user name and password. This doesn't work with Microsoft accounts or accounts that
    have two-factor authentication enabled. Use -p=secret if the first character of the password is
    '-'.
        az login -u johndoe@contoso.com -p VerySecret

    Log in with a service principal using client secret. Use -p=secret if the first character of the
    password is '-'.
        az login --service-principal -u http://azure-cli-2016-08-05-14-31-15 -p VerySecret --tenant
        contoso.onmicrosoft.com

    Log in with a service principal using client certificate.
        az login --service-principal -u http://azure-cli-2016-08-05-14-31-15 -p ~/mycertfile.pem
        --tenant contoso.onmicrosoft.com

    Log in using a VM's system assigned identity
        az login --identity

    Log in using a VM's user assigned identity. Client or object ids of the service identity also
    work
        az login --identity -u /subscriptions/<subscriptionId>/resourcegroups/myRG/providers/Microso
        ft.ManagedIdentity/userAssignedIdentities/myID
ghost commented 3 years ago

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @maertendMSFT.

Issue Details
Previously, changes on core are made to incorporate `azext_ai_examples`: - `azext_ai_examples` is always loaded: https://github.com/Azure/azure-cli/pull/13294 - `azext_ai_examples` hooks into `azure-cli-core` to modify the built-in examples: https://github.com/Azure/azure-cli/pull/10987 In Cloud Shell, `azext_ai_examples` is pre-installed. It replaces built-in hand-crafted high-qualify large-quantity examples with auto-generated low-quality small-quantity examples. For example, for `az vm create --help`: Cloud Shell: ``` Examples Create an Azure Virtual Machine. (autogenerated) az vm create --admin-username deploy --generate-ssh-keys --image Centos --name MyVm --resource-group MyResourceGroup Create a default Ubuntu VM with automatic SSH authentication. az vm create --name MyVm --resource-group MyResourceGroup --image UbuntuLTS Create a VM by attaching to a managed operating system disk. az vm create --resource-group MyResourceGroup --name MyVm --attach-os-disk MyOsDisk --os- type linux Create an Ubuntu Linux VM using a cloud-init script for configuration. See: https://docs.microsoft.com/azure/virtual-machines/virtual-machines-linux-using-cloud-init. az vm create --resource-group MyResourceGroup --name MyVm --image debian --custom-data MyCloudInitScript.yml Create a default Windows Server VM with a private IP address. az vm create --name MyVm --resource-group MyResourceGroup --public-ip-address "" --image Win2012R2Datacenter ``` Some examples are even wrong: - This link returns 404: https://docs.microsoft.com/azure/virtual-machines/virtual-machines-linux-using-cloud-init Locally: ``` Examples Create a default Ubuntu VM with automatic SSH authentication. az vm create -n MyVm -g MyResourceGroup --image UbuntuLTS Create a default RedHat VM with automatic SSH authentication using an image URN. az vm create -n MyVm -g MyResourceGroup --image RedHat:RHEL:7-RAW:7.4.2018010506 Create a default Windows Server VM with a private IP address. az vm create -n MyVm -g MyResourceGroup --public-ip-address "" --image Win2012R2Datacenter Create a VM from a custom managed image. az vm create -g MyResourceGroup -n MyVm --image MyImage Create a VM from a generalized gallery image version. az vm create -g MyResourceGroup -n MyVm --image /subscriptions/00000000-0000-0000-0000-00000 0000000/resourceGroups/myRG/providers/Microsoft.Compute/galleries/myGallery/images/myImage/v ersions/1.0.0 Create a VM from a specialized gallery image version. az vm create -g MyResourceGroup -n MyVm --image /subscriptions/00000000-0000-0000-0000-00000 0000000/resourceGroups/myRG/providers/Microsoft.Compute/galleries/myGallery/images/myImage/v ersions/1.0.0 --specialized Create a VM from the latest version of a gallery image az vm create -g MyResourceGroup -n MyVm --image /subscriptions/00000000-0000-0000-0000-00000 0000000/resourceGroups/myRG/providers/Microsoft.Compute/galleries/myGallery/images/myImage Create a VM by attaching to a managed operating system disk. az vm create -g MyResourceGroup -n MyVm --attach-os-disk MyOsDisk --os-type linux Create an Ubuntu Linux VM using a cloud-init script for configuration. See: https://docs.microsoft.com/azure/virtual-machines/linux/using-cloud-init. az vm create -g MyResourceGroup -n MyVm --image debian --custom-data MyCloudInitScript.yml Create a Debian VM with SSH key authentication and a public DNS entry, located on an existing virtual network and availability set. az vm create -n MyVm -g MyResourceGroup --image debian --vnet-name MyVnet --subnet subnet1 \ --availability-set MyAvailabilitySet --public-ip-address-dns-name MyUniqueDnsName \ --ssh-key-values @key-file Create a simple Ubuntu Linux VM with a public IP address, DNS entry, two data disks (10GB and 20GB), and then generate ssh key pairs. az vm create -n MyVm -g MyResourceGroup --public-ip-address-dns-name MyUniqueDnsName \ --image ubuntults --data-disk-sizes-gb 10 20 --size Standard_DS2_v2 \ --generate-ssh-keys Create a Debian VM using Key Vault secrets. az keyvault certificate create --vault-name vaultname -n cert1 \ -p "$(az keyvault certificate get-default-policy)" secrets=$(az keyvault secret list-versions --vault-name vaultname \ -n cert1 --query "[?attributes.enabled].id" -o tsv) vm_secrets=$(az vm secret format -s "$secrets") az vm create -g group-name -n vm-name --admin-username deploy \ --image debian --secrets "$vm_secrets" Create a CentOS VM with a system assigned identity. The VM will have a 'Contributor' role with access to a storage account. az vm create -n MyVm -g rg1 --image centos --assign-identity [system] --scope /subscriptions/99999999-1bf0-4dda- aec3-cb9272f09590/MyResourceGroup/myRG/providers/Microsoft.Storage/storageAccounts/storage1 Create a debian VM with a user assigned identity. az vm create -n MyVm -g rg1 --image debian --assign-identity /subscriptions/99999999-1bf0-4dda-aec3-cb9272f09590/resourcegroups/myRG/providers/Microsoft. ManagedIdentity/userAssignedIdentities/myID Create a debian VM with both system and user assigned identity. az vm create -n MyVm -g rg1 --image debian --assign-identity [system] /subscriptions/99999999-1bf0-4dda-aec3-cb9272f09590/resourcegroups/myRG/providers/Microsoft. ManagedIdentity/userAssignedIdentities/myID Create a VM in an availability zone in the current resource group's region. az vm create -n MyVm -g MyResourceGroup --image Centos --zone 1 Create multiple VMs. In this example, 3 VMs are created. They are MyVm0, MyVm1, MyVm2. az vm create -n MyVm -g MyResourceGroup --image centos --count 3 Create a VM from shared gallery image (private preview feature, please contact shared image gallery team by email sigpmdev@microsoft.com to register for preview if you're interested in using this feature). az vm create -n MyVm -g MyResourceGroup --image /SharedGalleries/{gallery_unique_name}/Images/{image}/Versions/{version} ``` This impedes Azure CLI's capability in Cloud Shell.
Author: jiasli
Assignees: jiasli
Labels: `Service Attention`, `Cloud Shell`
Milestone: Backlog