Использование служебного принципала с Azure Kubernetes Service (AKS)

1. Создайте служебный принципал с помощью команды az ad sp create-for-rbac.

   az ad sp create-for-rbac --name myAKSClusterServicePrincipal
   

   Выходные данные должны совпадать со следующим примером выходных данных:

   {
     "appId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "displayName": "myAKSClusterServicePrincipal",
     "name": "http://myAKSClusterServicePrincipal",
     "password": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "tenant": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
   }
   

2. Скопируйте значения appId и password из выходных данных. Они используются при создании кластера AKS в следующем разделе.

1. Создайте служебный принципал с помощью команды New-AzADServicePrincipal.

   New-AzADServicePrincipal -DisplayName myAKSClusterServicePrincipal -OutVariable sp
   

   Выходные данные должны совпадать со следующим примером выходных данных:

   Secret                : System.Security.SecureString
   ServicePrincipalNames : {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, http://myAKSClusterServicePrincipal}
   ApplicationId         : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   ObjectType            : ServicePrincipal
   DisplayName           : myAKSClusterServicePrincipal
   Id                    : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   Type                  :
   

   Значения хранятся в переменной, используемой при создании кластера AKS в следующем разделе.

2. Расшифровка значения, хранящегося в защищенной строке секрета, с помощью следующей команды.

   $BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($sp.Secret)
   [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)
   

• Используйте существующего служебного принципала для нового кластера AKS, используя команду az aks create и параметры --service-principal и --client-secret, чтобы указать appId и password из полученных данных в предыдущем разделе.

  az aks create \
      --resource-group myResourceGroup \
      --name myAKSCluster \
      --service-principal <appId> \
      --client-secret <password> \
      --generate-ssh-keys
  

  Примечание.

  Если вы используете существующую учетную запись службы с настроенным секретом, убедитесь, что длина секрета не превышает 190 байтов.

1. Преобразуйте субъект-службу ApplicationId и Secret в объект PSCredential с помощью следующей команды.

   $Cred = New-Object -TypeName System.Management.Automation.PSCredential ($sp.ApplicationId, $sp.Secret)
   

2. Используйте существующего представителя службы для нового кластера AKS, используя команду New-AzAksCluster, и укажите параметр ServicePrincipalIdAndSecret с ранее созданным объектом PSCredential в качестве его значения.

   New-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster -ServicePrincipalIdAndSecret $Cred
   

   Примечание.

   Если вы используете существующую учетную запись службы с настроенным секретом, убедитесь, что длина секрета не превышает 190 байтов.

• Создайте назначение роли с помощью az role assignment create команды. Укажите значение идентификатора приложения субъекта-службы для appId параметра. Укажите область назначения роли, например группу ресурсов или ресурс виртуальной сети. Назначение роли определяет, какие разрешения доверенное лицо службы имеет на ресурсе и в каком объеме.

  Например, чтобы назначить служебному принципалу разрешения на доступ к секретам в хранилище ключей, можно использовать следующую команду:

  az role assignment create \
      --assignee <appId> \
      --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name>" \
      --role "Key Vault Secrets User"
  

  Примечание.

  Для --scope ресурса должен быть полный идентификатор ресурса, например /subscriptions/<guid>/resourceGroups/myResourceGroup или /subscriptions/<guid>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet.

• Создайте назначение роли с помощью New-AzRoleAssignment команды. Укажите значение идентификатора приложения субъекта-службы для ApplicationId параметра. Укажите область назначения роли, например группу ресурсов или ресурс виртуальной сети. Назначение роли определяет, какие разрешения доверенное лицо службы имеет на ресурсе и в каком объеме.

  Например, чтобы назначить служебному принципалу разрешения на доступ к секретам в хранилище ключей, можно использовать следующую команду:

  New-AzRoleAssignment -ApplicationId <ApplicationId> `
      -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name>" `
      -RoleDefinitionName "Key Vault Secrets User"
  

  Примечание.

  Для Scope ресурса нужно указать полный идентификатор ресурса, например /subscriptions/<GUID>/resourceGroups/myResourceGroup или /subscriptions/<GUID>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet

Если вы используете Реестр контейнеров Azure (ACR) в качестве хранилища образов контейнера, необходимо предоставить служебному принципалу вашего кластера AKS разрешения на чтение и извлечение (pull) образов. Мы рекомендуем использовать команду az aks create или az aks update для интеграции с реестром и назначения соответствующей роли учетной записи службы. Подробные инструкции см. в разделе Аутентификация с помощью Реестра контейнеров Azure из службы контейнеров Azure.

Если вы используете Реестр контейнеров Azure (ACR) в качестве хранилища образов контейнера, необходимо предоставить служебному принципалу вашего кластера AKS разрешения на чтение и извлечение (pull) образов. Мы рекомендуем использовать команду New-AzAksCluster или Set-AzAksCluster для интеграции с реестром и назначения соответствующей роли учетной записи службы. Подробные инструкции см. в разделе Аутентификация с помощью Реестра контейнеров Azure из службы контейнеров Azure.

При использовании AKS и учетной записи службы Microsoft Entra, учтите следующее:

• Служебный принципал Kubernetes является частью конфигурации кластера, но не используйте эту учетную запись для развертывания кластера.
• По умолчанию учетные данные служебного субъекта действительны в течение одного года. Вы можете обновить или поменять учетные данные служебного принципала в любое время.
• Каждая учетная запись службы связана с приложением Microsoft Entra. Служебный принципал для кластера Kubernetes можно связать с любым действительным именем приложения Microsoft Entra (например: https://www.contoso.org/example). URL-адрес приложения не обязательно должен быть реальной конечной точкой.
• При указании идентификатора клиента учетной записи службы используйте значение appId.
• На виртуальных машинах узла агента в кластере Kubernetes учетные данные учетной записи службы хранятся в /etc/kubernetes/azure.json файле.
• При удалении кластера AKS, созданного с помощью az aks create команды, созданный субъект-служба не удаляется автоматически.

  • Чтобы удалить служебный принципал, выполните запрос для servicePrincipalProfile.clientId кластера и удалите его, используя команду az ad sp delete. Замените значения параметра -g для имени группы ресурсов и -n параметра для имени кластера:

    az ad sp delete --id $(az aks show \
      --resource-group myResourceGroup \
      --name myAKSCluster \
      --query servicePrincipalProfile.clientId \
      --output tsv)
    

При использовании AKS и учетной записи службы Microsoft Entra, учтите следующее:

• Служебный принципал Kubernetes является частью конфигурации кластера, но не используйте эту учетную запись для развертывания кластера.
• По умолчанию учетные данные служебного субъекта действительны в течение одного года. Вы можете обновить или поменять учетные данные служебного принципала в любое время.
• Каждая учетная запись службы связана с приложением Microsoft Entra. Служебный принципал для кластера Kubernetes можно связать с любым действительным именем приложения Microsoft Entra (например: https://www.contoso.org/example). URL-адрес приложения не обязательно должен быть реальной конечной точкой.
• При указании идентификатора клиента учетной записи службы используйте значение ApplicationId.
• На виртуальных машинах узла агента в кластере Kubernetes учетные данные учетной записи службы хранятся в /etc/kubernetes/azure.json файле.
• При удалении кластера AKS, созданного с помощью New-AzAksCluster, учетная запись службы, созданная автоматически, не удаляется.

  • Чтобы удалить принципал службы, выполните запрос на ClientId профиля ServicePrincipalProfile вашего кластера и удалите его, используя команду Remove-AzADServicePrincipal. Замените значения параметра -ResourceGroupName для имени группы ресурсов и -Name параметра для имени кластера:

    $ClientId = (Get-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster ).ServicePrincipalProfile.ClientId
    Remove-AzADServicePrincipal -ApplicationId $ClientId
    

Azure CLI кэширует учетные данные служебного субъекта для кластеров AKS. Если срок действия этих учетных данных истекает, во время развертывания кластера AKS могут возникнуть ошибки. Если вы выполните команду az aks create и получите сообщение об ошибке, похожее на следующее, это может указывать на проблему с учетными данными кэшированного основного сервиса.

Operation failed with status: 'Bad Request'.
Details: The credentials in ServicePrincipalProfile were invalid. Please see https://aka.ms/aks-sp-help for more details.
(Details: adal: Refresh request failed. Status Code = '401'.

Вы можете проверить дату окончания срока действия учетных данных сервисного принципала с помощью команды az ad app credential list с параметром "[].endDateTime".

az ad app credential list \
    --id <app-id> \
    --query "[].endDateTime" \
    --output tsv

Срок действия учетных данных служебного аккаунта по умолчанию составляет один год. Если учетные данные старше одного года, можно сбросить существующие учетные данные или создать новый служебный принципал.

Общие сведения об устранении неполадок с помощью Azure CLI

Azure CLI может выполняться в нескольких средах оболочки, но с небольшими вариантами формата. Если вы столкнулись с непредвиденными результатами команд Azure CLI, см. статью Как успешно использовать Azure CLI.

Azure PowerShell кэширует учетные данные служебного принципала для кластеров AKS. Если срок действия этих учетных данных истекает, во время развертывания кластера AKS возникают ошибки. Если вы выполните команду New-AzAksCluster и получите сообщение об ошибке, похожее на следующее, это может указывать на проблему с учетными данными кэшированного основного сервиса.

Operation failed with status: 'Bad Request'.
Details: The credentials in ServicePrincipalProfile were invalid. Please see https://aka.ms/aks-sp-help for more details.
(Details: adal: Refresh request failed. Status Code = '401'.

Вы можете проверить дату окончания срока действия учетных данных служебного принципала с помощью команды Get-AzADAppCredential. В выходных данных отображается StartDateTime ваших учетных данных.

Get-AzADAppCredential -ApplicationId <ApplicationId> 

Срок действия учетных данных служебного аккаунта по умолчанию составляет один год. Если учетные данные старше одного года, можно сбросить существующие учетные данные или создать новый служебный принципал.