Menginstal Azure CLI di Azure Stack Hub

  • Artikel

Anda dapat menginstal Azure CLI untuk mengelola Azure Stack Hub dengan mesin Windows atau Linux. Artikel ini memandu Anda dalam langkah-langkah menginstal dan menyiapkan Azure CLI.

Menginstal Azure CLI

  1. Masuk ke stasiun kerja pengembangan Anda dan instal CLI. Azure Stack Hub memerlukan CLI Azure versi 2.0 atau yang lebih baru.

    Penting

    Karena CVE yang memengaruhi versi Azure CLI sebelumnya ke 2.40.0, tidak disarankan lagi agar Anda menggunakan Azure CLI 2.29.2 untuk Layanan Federasi Direktori Aktif di Azure Stack Hub. Anda dapat memperbarui ke Azure CLI 2.40.0 atau yang lebih tinggi. Namun, pelanggan Layanan Federasi Direktori Aktif mungkin mengalami masalah dengan perintah Azure CLI yang berinteraksi dengan titik akhir Microsoft Graph. Ini karena Microsoft Graph tidak didukung untuk Layanan Federasi Direktori Aktif. Untuk solusi untuk masalah Microsoft Graph, lihat bagian Masalah umum yang diketahui .

  2. Anda memasang CLI dengan menggunakan langkah-langkah yang dijelaskan dalam artikel Menginstal CLI Azure.

  3. Untuk memverifikasi apakah penginstalan berhasil, buka terminal atau jendela perintah dan jalankan perintah berikut:

    az --version

    Anda akan melihat versi CLI Azure dan pustaka dependen lainnya yang dipasang di komputer Anda.

    Azure CLI di lokasi Azure Stack Hub Python

  4. Catat lokasi Python CLI.

Tambah sertifikat

Ekspor lalu impor sertifikat Azure Stack Hub untuk sistem terintegrasi yang terputus dan untuk ASDK. Untuk sistem terintegrasi yang tersambung, sertifikat ditandatangani secara publik dan langkah ini tidak diperlukan. Untuk petunjuknya, lihat Menyiapkan sertifikat untuk Azure CLI di Azure Stack Development Kit.

Menyambungkan dengan Azure CLI

Bagian ini memandu Anda menyiapkan CLI jika Anda menggunakan ID Microsoft Entra sebagai layanan manajemen identitas Anda, dan menggunakan CLI pada komputer Windows.

Menyambungkan ke Azure Stack Hub

  1. Jika Anda menggunakan ASDK, percayai sertifikat akar Azure Stack Hub CA. Untuk instruksi, lihat Mempercayai sertifikat.

  2. Daftarkan lingkungan Azure Stack Hub Anda dengan menjalankan perintah az cloud register.

  3. Daftarkan lingkungan Anda. Gunakan parameter berikut saat menjalankan az cloud register:

    Nilai Contoh Deskripsi
    Nama lingkungan AzureStackUser Gunakan AzureStackUser untuk lingkungan pengguna. Jika Anda operator, tentukan AzureStackAdmin.
    Titik akhir Resource Manager https://management.contoso.onmicrosoft.com ResourceManagerUrl di ASDK adalah: https://management.local.azurestack.external/ResourceManagerUrl dalam sistem terintegrasi adalah: https://management.<region>.<fqdn>/ Jika Anda memiliki pertanyaan tentang titik akhir sistem terintegrasi, hubungi operator cloud Anda.
    Titik akhir penyimpanan local.contoso.onmicrosoft.com local.azurestack.external adalah untuk ASDK. Untuk sistem terintegrasi, gunakan titik akhir untuk sistem Anda.
    Akhiran Keyvault .vault.contoso.onmicrosoft.com .vault.local.azurestack.external adalah untuk ASDK. Untuk sistem terintegrasi, gunakan titik akhir untuk sistem Anda.
    ID sumber daya grafik direktori aktif titik akhir https://graph.windows.net/ ID sumber daya Active Directory. 
    az cloud register `
    -n <environmentname> `
    --endpoint-resource-manager "https://management.<region>.<fqdn>" `
    --suffix-storage-endpoint "<fqdn>" `
    --suffix-keyvault-dns ".vault.<fqdn>"

    Anda dapat menemukan referensi untuk perintah register di dokumentasi referensi Azure CLI.

  4. Atur lingkungan aktif dengan menggunakan perintah berikut.

    az cloud set -n <environmentname>

  5. Perbarui konfigurasi lingkungan Anda untuk menggunakan profil versi API khusus Azure Stack Hub. Untuk memperbarui konfigurasi, jalankan perintah berikut:

    az cloud update --profile 2020-09-01-hybrid

  6. Masuk ke lingkungan Azure Stack Hub Anda dengan menggunakan perintah az login.

    Anda dapat masuk ke lingkungan Azure Stack Hub menggunakan kredensial pengguna, atau dengan perwakilan layanan (SPN) yang diberikan kepada Anda oleh operator cloud Anda.

    • Masuk sebagai pengguna:

      Anda dapat menentukan nama pengguna dan kata sandi langsung dalam perintah az login, atau melalui autentikasi dengan menggunakan browser. Anda harus melakukan pilihan kedua jika akun Anda mengaktifkan autentikasi multifaktor:

      az login -u "user@contoso.onmicrosoft.com" -p 'Password123!' --tenant contoso.onmicrosoft.com

      Catatan

      Jika akun pengguna Anda mengaktifkan autentikasi multifaktor, gunakan perintah az login tanpa menyediakan parameter -u. Menjalankan perintah ini akan memberi Anda URL dan kode yang harus Anda gunakan untuk diautentikasi.

    • Masuk sebagai perwakilan layanan:

      Sebelum Anda masuk, buat perwakilan layanan melalui portal Microsoft Azure atau CLI dan tetapkan perannya. Sekarang, masuk dengan menggunakan perintah berikut:

      az login `
  --tenant <Azure Active Directory Tenant name. `
            For example: myazurestack.onmicrosoft.com> `
--service-principal `
  -u <Application Id of the Service Principal> `
  -p <Key generated for the Service Principal>

  7. Pastikan lingkungan Anda diatur dengan benar dan adalah cloud aktif.

        az cloud list --output table

    Anda harus melihat bahwa lingkungan Anda terdaftar dan IsActive adalah true. Contohnya:

    IsActive    Name               Profile
----------  -----------------  -----------------
False       AzureCloud         2020-09-01-hybrid
False       AzureChinaCloud    latest
False       AzureUSGovernment  latest
False       AzureGermanCloud   latest
True        AzureStackUser     2020-09-01-hybrid

Menguji konektivitas

Setelah semua disiapkan, gunakan CLI untuk membuat sumber daya di dalam Azure Stack Hub. Misalnya, Anda dapat membuat grup sumber daya untuk aplikasi dan menambahkan mesin virtual. Gunakan perintah berikut untuk membuat grup sumber daya bernama "MyResourceGroup":

az group create -n MyResourceGroup -l local

Jika grup sumber daya berhasil dibuat, perintah sebelumnya akan menghasilkan properti berikut dari sumber daya yang baru dibuat:

{
  "id": "/subscriptions/84edee99-XXXX-4f5c-b646-5cdab9759a03/resourceGroups/RGCL11",
  "location": "local",
  "name": "RGCLI1",
  " properties ": {
    "provisioningState": "Succeeded"
  },
  "tags ": null
}

Masalah umum yang diketahui

Perbaikan umum untuk sebagian besar masalah adalah menggunakan az rest perintah yang menggunakan konteks Azure Stack saat ini, untuk melakukan panggilan REST API untuk perintah terkait dengan masalah tersebut. Solusi dalam daftar masalah berikut umumnya dapat diadaptasi untuk masalah Azure CLI lainnya selama masalah ini disebabkan oleh Azure CLI dan bukan penyedia sumber daya Azure Stack Hub atau layanan Azure Stack Hub lainnya.

Masalah Microsoft Graph

Ini adalah masalah Microsoft Graph yang diketahui untuk Azure CLI 2.40.0, atau yang lebih besar, untuk Azure Stack Hub. Ini terutama memengaruhi lingkungan ADFS karena tidak mendukung Microsoft Graph.

  • az keyvault create berinteraksi dengan Microsoft Graph. Berikut ini adalah contoh solusi untuk ADFS. Terutama, solusinya menggunakan Azure AD Graph untuk mengambil informasi pengguna seperti objectId bukan Microsoft Graph.

    # First, sign into Azure CLI account you want to create the Key Vault from.
# TODO: change the principal name to name of principal you want to create the key vault with.
$principalNameLike = "CloudUser*"
# TODO: change location to your preference.
$location = "local"
$aadGraph = az cloud show --query endpoints.activeDirectoryGraphResourceId --output tsv
$tenantId = az account show --query tenantId --output tsv
if ($aadGraph[-1] -ne '/')
{
    $aadGraph += '/'
}
$userObject = az rest --method get --url "${aadGraph}${tenantId}/users?api-version=1.6" `
    | ConvertFrom-Json `
    | Select-Object -ExpandProperty value `
    | Where-Object {$_.userPrincipalName -like $principalNameLike}
$body = '{
  "location": "' + $location + '",
  "properties": {
    "tenantId": "' + $tenantId + '",
    "sku": {
      "family": "A",
      "name": "standard"
    },
    "accessPolicies": [
      {
        "tenantId": "' + $tenantId + '",
        "objectId": "' + $userObject.objectId + '",
        "permissions": {
          "keys": [
            "get",
            "create",
            "delete",
            "list",
            "update",
            "import",
            "backup",
            "restore",
            "recover"
          ],
          "secrets": [
            "get",
            "list",
            "set",
            "delete",
            "backup",
            "restore",
            "recover"
          ],
          "certificates": [
            "get",
            "list",
            "delete",
            "create",
            "import",
            "update",
            "managecontacts",
            "getissuers",
            "listissuers",
            "setissuers",
            "deleteissuers",
            "manageissuers",
            "recover"
          ],
          "storage": [
            "get",
            "list",
            "delete",
            "set",
            "update",
            "regeneratekey",
            "setsas",
            "listsas",
            "getsas",
            "deletesas"
          ]
        }
      }
    ],
    "enabledForDeployment": true,
    "enabledForTemplateDeployment": true
  }
}'
$body | Out-File -FilePath (Join-Path -Path "." -ChildPath "body.json")
$resourceGroupName = "testrg123"
az group create -n $resourceGroupName -l $location
$armEndpoint = az cloud show --query endpoints.resourceManager --output tsv
if ($armEndpoint[-1] -ne '/')
{
    $armEndpoint += '/'
}
$subscriptionId = az account show --query id --output tsv
$keyVaultName = "testkv123"
az rest --method put --url "${armEndpoint}subscriptions/${subscriptionId}/resourceGroups/${resourceGroupName}/providers/Microsoft.KeyVault/vaults/${keyVaultName}?api-version=2016-10-01" --body `@body.json
# OPTIONAL: test access to the Key Vault.
# az keyvault secret set --name MySecretName --vault-name $keyVaultName --value MySecret

    Untuk informasi selengkapnya tentang Key Vault REST API, lihat referensi Key Vault REST API.

Masalah lain

Berikut ini adalah masalah yang tidak terbatas pada versi atau rentang versi Azure CLI tertentu.

  • az role assignment create saat ini tidak didukung oleh Azure CLI untuk Azure Stack Hub karena masalah API lama. Solusi berikut diperlukan untuk ID Microsoft Entra atau ADFS. 
    # First, sign into account with access to the resource that is being given access or a role to another user.
# TODO: change the principal name to name of principal you want to assign the role to.
$principalNameLike = "CloudUser*"
# TODO: change role name to your preference.
$roleName = "Owner"
# TODO: change location to your preference.
$location = "local"
$aadGraph = az cloud show --query endpoints.activeDirectoryGraphResourceId --output tsv
$tenantId = az account show --query tenantId --output tsv
if ($aadGraph[-1] -ne '/')
{
    $aadGraph += '/'
}
$userObject = az rest --method get --url "${aadGraph}${tenantId}/users?api-version=1.6" `
    | ConvertFrom-Json `
    | Select-Object -ExpandProperty value `
    | Where-Object {$_.userPrincipalName -like $principalNameLike}
$roleDefinitionId = az role definition list --query "[?roleName=='${roleName}'].id" --output tsv
$body = @{
    properties = @{
        roleDefinitionId = $roleDefinitionId
        principalId = $userObject.objectId
    }
}
$body | ConvertTo-Json | Out-File -FilePath (Join-Path -Path "." -ChildPath "body.json")
$resourceGroupName = "testrg123"
az group create -n $resourceGroupName -l $location
$armEndpoint = az cloud show --query endpoints.resourceManager --output tsv
if ($armEndpoint[-1] -ne '/')
{
    $armEndpoint += '/'
}
$scope =  az group show --name $resourceGroupName --query id --output tsv
$guid = (New-Guid).ToString()
az rest --method put --url "${armEndpoint}${scope}/providers/Microsoft.Authorization/roleAssignments/${guid}?api-version=2015-07-01" --body `@body.json
# OPTIONAL: test access to the resource group, or use the portal.
# az login -u <assigned user name> -p <assigned user password> --tenant $tenantId
# Test a resource creation command in the resource group:
# az network dns zone create -g $resourceGroupName -n "www.mysite.com"
    Untuk informasi selengkapnya tentang REST API penetapan peran, lihat artikel penetapan peran.

Langkah berikutnya