다음을 통해 공유

Azure Stack Hub에 Azure CLI 설치

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. Azure CLI 설치 문서에 설명된 단계를 사용하여 CLI를 설치할 수 있습니다.

  3. 설치에 성공했는지 확인하려면 터미널 또는 명령 프롬프트 창을 열고 다음 명령을 실행합니다.

    az --version

    컴퓨터에 설치된 Azure CLI 및 기타 종속 라이브러리의 버전이 표시됩니다.

    Azure Stack Hub의 Python 위치에 있는 Azure CLI

  4. CLI의 Python 위치를 기록해 둡니다.

인증서 추가

연결이 끊긴 통합 시스템에 대한 Azure Stack Hub 인증서를 내보낸 다음 가져옵니다. 연결된 통합 시스템의 경우 인증서가 공개적으로 서명되며 이 단계는 필요하지 않습니다.

Azure CLI를 사용하여 연결

이 섹션에서는 MICROSOFT Entra ID를 ID 관리 서비스로 사용하고 Windows 컴퓨터에서 CLI를 사용하는 경우 CLI를 설정하는 방법을 안내합니다.

Azure Stack Hub에 연결

  1. 명령을 실행하여 Azure Stack Hub 환경을 등록합니다 az cloud register .

  2. 환경을 등록합니다. 실행할 az cloud register때 다음 매개 변수를 사용합니다.

    가치 예시 설명
    환경 이름 AzureStackUser 사용자 환경에 AzureStackUser을(를) 사용하십시오. 연산자라면 AzureStackAdmin을 지정하십시오.
    Resource Manager 엔드포인트 https://management.contoso.onmicrosoft.com 통합 시스템의 ResourceManagerUrl 은 다음과 https://management.<region>.<fqdn>/같습니다. 통합 시스템 엔드포인트에 대한 질문이 있는 경우 클라우드 운영자에게 문의하세요.
    스토리지 엔드포인트 local.contoso.onmicrosoft.com 통합 시스템의 경우 시스템에 엔드포인트를 사용합니다.
    Keyvault 접미사 .vault.contoso.onmicrosoft.com 통합 시스템의 경우 시스템에 엔드포인트를 사용합니다.
    엔드포인트 Active Directory 그래프 리소스 ID https://graph.microsoft.com/ Active Directory 리소스 ID입니다. 
    az cloud register `
    -n <environmentname> `
    --endpoint-resource-manager "https://management.<region>.<fqdn>" `
    --suffix-storage-endpoint "<fqdn>" `
    --suffix-keyvault-dns ".vault.<fqdn>"

    자세한 내용은 Azure CLI 참조 설명서의 register 명령을 참조하세요.

  3. 다음 명령을 사용하여 활성 환경을 설정합니다.

    az cloud set -n <environmentname>

  4. Azure Stack Hub 특정 API 버전 프로필을 사용하도록 환경 구성을 업데이트합니다. 구성을 업데이트하려면 다음 명령을 실행합니다.

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

  5. 명령을 사용하여 Azure Stack Hub 환경에 로그인합니다 az login .

    사용자 자격 증명을 사용하거나 클라우드 운영자가 제공한 SPN( 서비스 주체 )을 사용하여 Azure Stack Hub 환경에 로그인할 수 있습니다.

    • 사용자로 로그인합니다.

    az login 명령 내에 직접 사용자 이름과 암호를 지정하거나 브라우저를 사용하여 인증할 수 있습니다. 계정에 다단계 인증이 사용하도록 설정된 경우 브라우저를 사용하여 인증해야 합니다.

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

    비고

    사용자 계정에 다단계 인증이 사용하도록 설정된 경우 매개 변수를 az login-u 제공하지 않고 명령을 사용합니다. 이 명령을 실행하면 인증에 사용해야 하는 URL과 코드를 제공합니다.

    • 서비스 주체로 로그인합니다.

      로그인하기 전에 Azure Portal 또는 CLI를 통해 서비스 주체를 만들고 역할을 할당합니다. 이제 다음 명령을 사용하여 로그인합니다.

      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>

  6. 환경이 올바르게 설정되어 있고 환경이 활성 클라우드인지 확인합니다.

    az cloud list --output table

    환경이 나열되고 IsActivetrue가 표시됩니다. 다음은 그 예입니다.

    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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/RGCL11",
  "location": "local",
  "name": "RGCLI1",
  " properties ": {
    "provisioningState": "Succeeded"
  },
  "tags ": null
}

일반적인 알려진 문제

대부분의 문제에 대한 일반적인 해결 방법은 현재 Azure Stack 컨텍스트를 사용하는 명령을 사용하여 az rest 관련 명령에 대해 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를 지원하지 않으므로 AD FS 환경에 영향을 줍니다.

  • az keyvault create 는 Microsoft Graph와 상호 작용합니다. 다음은 AD FS에 대한 해결 방법의 예입니다. 주로 이 해결 방법은 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 Stack Hub용 Azure CLI에서 현재 지원되지 않습니다. 다음 해결 방법은 Microsoft Entra ID 또는 AD FS 모두에 필요합니다.

    # 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에 대한 자세한 내용은 역할 할당 문서를 참조하세요.

다음 단계