Azure CLI を Azure Stack Hub にインストールする

  • [アーティクル]

Azure CLI をインストールすると、Windows マシンまたは Linux マシンで Azure Stack Hub を管理することができます。 この記事では、Azure CLI のインストールと設定の手順について説明します。

Azure CLI のインストール

  1. 開発ワークステーションにサインインし、CLI をインストールします。 Azure Stack Hub には、Azure CLI のバージョン 2.0 以降が必要です。

    重要

    2.40.0 より前のバージョンの Azure CLI に影響する CVE が原因で、Azure Stack Hub で AD FS に Azure CLI 2.29.2 を使用することは推奨されなくなりました。 Azure CLI 2.40.0 以降に更新できます。 ただし、AD FS のお客様は、Microsoft Graph エンドポイントと対話する Azure CLI コマンドで問題が発生する可能性があります。 これは、Microsoft Graph が AD FS でサポートされていないためです。 Microsoft Graph の問題の回避策については、「 一般的な既知の問題 」セクションを参照してください。

  2. CLI は、「Azure CLI のインストール」で説明されている手順を使用してインストールできます。

  3. インストールが正常に完了したことを確認するには、ターミナルまたはコマンド プロンプト ウィンドウを開いて次のコマンドを実行します。

    az --version

    お使いのコンピューターにインストールされている Azure CLI と依存するその他のライブラリのバージョンが表示されます。

    Azure Stack Hub 上の Azure CLI の Python の場所

  4. CLI の Python の場所を書き留めておきます。

証明書を追加する

切断された統合システムと ASDK の場合は、Azure Stack Hub 証明書をエクスポートしてインポートします。 接続されている統合システムの場合は、証明書はパブリック的に署名されており、この手順は必要ありません。 手順については、「 Azure Stack Development Kit での Azure CLI の証明書の設定」を参照してください。

Azure CLI との接続

このセクションでは、ID 管理サービスとして Microsoft Entra ID を使用していて、Windows マシンで CLI を使用している場合に CLI を設定する手順について説明します。

Azure Stack Hub に接続する

  1. ASDK を使用している場合、Azure Stack Hub の CA ルート証明書を信頼します。 手順については、「証明書を信頼する」を参照してください。

  2. az cloud register コマンドを実行して Azure Stack Hub 環境を登録します。

  3. お客様の環境を登録します。 az cloud register を実行するときに、次のパラメーターを使用します。

    値 例 説明
    環境名 AzureStackUser ユーザー環境には、AzureStackUser を使用します。 オペレーターの場合は、AzureStackAdmin を指定します。
    Resource Manager エンドポイント https://management.contoso.onmicrosoft.com ASDK の ResourceManagerUrl は次のとおりです。https://management.local.azurestack.external/ になります。統合システムの ResourceManagerUrl はhttps://management.<region>.<fqdn>/ になります。統合システム エンドポイントに関する質問がある場合は、お客様のクラウド オペレーターにお問い合わせください。
    ストレージ エンドポイント local.contoso.onmicrosoft.com local.azurestack.external は、ASDK の場合です。 統合システムの場合は、システムのエンドポイントを使用します。
    Keyvault のサフィックス .vault.contoso.onmicrosoft.com .vault.local.azurestack.external は、ASDK の場合です。 統合システムの場合は、システムのエンドポイントを使用します。
    エンドポイント Azure Active Directory Graph リソース ID https://graph.windows.net/ Active Directory リソース ID。 
    az cloud register `
    -n <environmentname> `
    --endpoint-resource-manager "https://management.<region>.<fqdn>" `
    --suffix-storage-endpoint "<fqdn>" `
    --suffix-keyvault-dns ".vault.<fqdn>"

    register コマンドのリファレンスは、Azure CLI リファレンス ドキュメントにあります。

  4. 次のコマンドを使用して、アクティブな環境を設定します。

    az cloud set -n <environmentname>

  5. Azure Stack Hub 固有の API バージョンのプロファイルを使用するようにお使いの環境の構成を更新します。 構成を更新するには、次のコマンドを実行します。

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

  6. az login コマンドを使用して Azure Stack Hub 環境にサインインします。

    Azure Stack Hub 環境にサインインするには、ユーザー資格情報を使用するか、クラウド オペレーターによって提供されるサービス プリンシパル (SPN) を使用します。

    • ユーザーとしてサインインする場合:

      az login コマンド内で直接ユーザー名とパスワードを指定するか、ブラウザーを使用して認証できます。 多要素認証が有効になっているアカウントの場合は、後者を実行する必要があります。

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

      Note

      お使いのユーザー アカウントで多要素認証が有効になっている場合は、-u パラメーターを指定しないで、az login コマンドを使用します。 このコマンドを実行すると、認証で使用する必要がある URL とコードを取得できます。

    • サービス プリンシパルを使ってサインインする｡

      サインインする前に、CLI または Azure Portal でサービス プリンシパルを作成してロールに割り当てます。 次のコマンドを使用してサインインします。

      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. 環境が正しく設定されていること、環境がアクティブなクラウドであることを確認します。

        az cloud list --output table

    環境が一覧表示され、IsActive が true になっていることを確認します。 例:

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

接続のテスト

すべての設定が完了したら、CLI を使用し、Azure Stack Hub 内でリソースを作成します。 たとえば、アプリのリソース グループを作成し、VM を追加できます。 次のコマンドを使用して、"MyResourceGroup" という名前のリソース グループを作成します。

az group create -n MyResourceGroup -l local

リソース グループが正常に作成されると、上記のコマンドによって、新たに作成されたリソースの次のプロパティが出力されます。

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

全般的な既知の問題

ほとんどの問題の一般的な修正は、現在の az rest Azure Stack コンテキストを使用するコマンドを使用して、問題に関連付けられているコマンドの REST API 呼び出しを行う方法です。 次の問題の一覧の回避策は、通常、これらの問題が Azure Stack Hub リソース プロバイダーや他の Azure Stack Hub サービスではなく Azure CLI によって発生している限り、他の Azure CLI の問題に対応できます。

Microsoft Graph の問題

これらは、Azure Stack Hub の Azure CLI 2.40.0 以降の Microsoft Graph の既知の問題です。 これは主に、Microsoft Graph をサポートしていないため、ADFS 環境に影響します。

  • az keyvault create は Microsoft Graph と対話します。 ADFS の回避策の例を次に示します。 主に、回避策では、Azure AD Graph を使用して、Microsoft Graph ではなく などの objectId ユーザー情報を取得します。

    # 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

    KEY VAULT REST API の詳細については、「Key Vault REST API リファレンス」を参照してください。

その他の問題

Azure CLI の特定のバージョンまたはバージョンの範囲に限定されない問題を次に示します。

  • az role assignment create は、古い API の問題のため、Azure CLI for Azure Stack Hub では現在サポートされていません。 Microsoft Entra ID と 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"
    ロールの割り当て REST API の詳細については、 ロールの割り当てに関する記事を参照してください。

次のステップ