Partilhar via

Criar e gerir localizações personalizadas no Kubernetes com suporte do Azure Arc

O recurso de locais personalizados fornece uma maneira de configurar seus clusters Kubernetes habilitados para Azure Arc como locais de destino para implantar instâncias de ofertas do Azure. Exemplos de ofertas do Azure que podem ser implantadas em locais personalizados incluem bancos de dados, como a Instância Gerenciada SQL habilitada pelo Azure Arc, ou instâncias de aplicativos, como Aplicativos de Contêiner, Aplicativos Lógicos, Grade de Eventos, Aplicativos Lógicos e Gerenciamento de API.

Uma localização personalizada tem um mapeamento um-para-um para um namespace em um cluster Kubernetes com suporte ao Azure Arc. O recurso do Azure de local personalizado combinado com o controle de acesso baseado em função do Azure (Azure RBAC) pode ser usado para conceder permissões granulares a desenvolvedores de aplicativos ou administradores de banco de dados, permitindo que eles implantem recursos como bancos de dados ou instâncias de aplicativos sobre clusters Kubernetes habilitados para Arc em um ambiente multilocatário.

Neste artigo, você aprenderá como habilitar locais personalizados em um cluster Kubernetes habilitado para Arc e como criar um local personalizado.

Pré-requisitos

  • Instale ou atualize a CLI do Azure para a versão mais recente.

  • Instale as versões mais recentes das seguintes extensões da CLI do Azure:

    • connectedk8s

    • k8s-extension

    • customlocation

      az extension add --name connectedk8s
az extension add --name k8s-extension
az extension add --name customlocation

      Se você já instalou o connectedk8s, k8s-extensione customlocation extensões, atualize para a versão mais recente usando o seguinte comando:

      az extension update --name connectedk8s
az extension update --name k8s-extension
az extension update --name customlocation

  • Verifique se o registro do provedor foi concluído para Microsoft.ExtendedLocation.

    1. Introduza os seguintes comandos:

      az provider register --namespace Microsoft.ExtendedLocation

    2. Monitorize o processo de registo. O registo pode demorar até 10 minutos.

      az provider show -n Microsoft.ExtendedLocation -o table

      Uma vez cadastrado, o RegistrationState estado fica com o valor Registered.

  • Verifique se você tem um cluster conectado ao Kubernetes habilitado para Azure Arc existente e atualize seus agentes para a versão mais recente. Confirme se a máquina na qual você executará os comandos descritos neste artigo tem um kubeconfig arquivo que aponta para esse cluster.

Ativar localizações personalizadas no cluster

Importante

A funcionalidade de localizações personalizadas depende da funcionalidade Ligação do Cluster. Ambas as funcionalidades têm de estar ativadas no cluster para que as localizações personalizadas funcionem.

O OID (Custom Location Object ID) é necessário para habilitar o local personalizado. Se sua conta de usuário tiver as permissões necessárias, o OID será recuperado automaticamente durante a ativação do recurso. Se você não tiver uma conta de usuário válida, o OID passado manualmente será usado, mas o OID não poderá ser validado. Se o OID for inválido, o local personalizado pode não estar habilitado corretamente.

O recurso de locais personalizados deve ser habilitado antes de criar locais personalizados, porque a habilitação fornece as permissões necessárias para criar o namespace de locais personalizados no cluster do Kubernetes.

Habilitar locais personalizados como um usuário do Microsoft Entra

Entre na CLI do Azure como um usuário do Microsoft Entra e execute o seguinte comando:

az connectedk8s enable-features -n <clusterName> -g <resourceGroupName> --features cluster-connect custom-locations

Ativar locais personalizados com um principal de serviço

Recupere manualmente o OID de local personalizado seguindo estas etapas.

Importante

Copie e execute o comando na etapa 2 exatamente como mostrado. Não substitua o valor passado para o --id parâmetro por um valor diferente.

  1. Entre na CLI do Azure como um usuário do Microsoft Entra.

  2. Execute o seguinte comando para buscar o local oid personalizado (ID do objeto), onde --id se refere ao próprio aplicativo de serviço de Local Personalizado, e é predefinido e definido como bc313c14-388c-4e7d-a58e-70017303ee3b:

    az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query id -o tsv

  3. Inicie sessão na CLI do Azure com o principal de serviço. Execute o seguinte comando para habilitar o recurso de locais personalizados no cluster, usando o oid valor (ID do objeto) da etapa anterior para o --custom-locations-oid parâmetro:

    az connectedk8s enable-features -n <cluster-name> -g <resource-group-name> --custom-locations-oid <cl-oid> --features cluster-connect custom-locations

Criar local personalizado

  1. Implemente a extensão do cluster do serviço do Azure da instância de serviço do Azure que quer instalar no cluster:

  2. Obtenha o identificador do Azure Resource Manager do cluster do Kubernetes compatível com o Azure Arc, referido em passos posteriores como connectedClusterId:

    az connectedk8s show -n <clusterName> -g <resourceGroupName>  --query id -o tsv

  3. Obtenha o identificador do Azure Resource Manager da extensão de cluster que você implantou no cluster Kubernetes habilitado para Azure Arc, referenciado em etapas posteriores como extensionId:

    az k8s-extension show --name <extensionInstanceName> --cluster-type connectedClusters -c <clusterName> -g <resourceGroupName>  --query id -o tsv

  4. Crie o local personalizado fazendo referência ao cluster Kubernetes habilitado para Azure Arc e à extensão:

    az customlocation create -n <customLocationName> -g <resourceGroupName> --namespace <name of namespace> --host-resource-id <connectedClusterId> --cluster-extension-ids <extensionId>

    • Parâmetros necessários:

      Nome do parâmetro Descrição
      --name, --n Nome do local personalizado.
      --resource-group, --g Grupo de recursos da localização personalizada.
      --namespace Namespace no cluster vinculado ao local personalizado que está sendo criado.
      --host-resource-id Identificador do Azure Resource Manager do cluster Kubernetes habilitado para Azure Arc (cluster conectado).
      --cluster-extension-ids Identificador do Azure Resource Manager de uma instância de extensão de cluster instalada no cluster conectado. Para várias extensões, forneça uma lista separada por espaço de IDs de extensão de cluster.

    • Parâmetros opcionais:

      Nome do parâmetro Descrição
      --location, --l Localização do recurso do Azure Resource Manager para a localização personalizada no Azure. Se não for especificado, o local do cluster conectado será usado.
      --tags Lista separada por espaços de tags no formato key[=value]. Use '' para limpar tags existentes.
      --kubeconfig Administração do cluster.

  5. Confirme se o local personalizado foi habilitado com êxito executando o seguinte comando e verificando se ProvisioningState é Succeeded:

az customlocation show -n <customLocationName> -g <resourceGroupName>

Verificar o uso de um local personalizado

Para determinar se um local personalizado está sendo usado ativamente por outros recursos do Azure, você pode listar os tipos de recursos habilitados para ele usando a CLI do Azure.

az customlocation list-enabled-resource-types -n <customLocationName> -g <resourceGroupName>

Este comando retorna uma lista de tipos de recursos do Azure configurados para usar o local personalizado especificado. Se a lista não estiver vazia, isso indica que o local personalizado está sendo usado por esses tipos de recursos.

Exemplo de saída:

[
  {
    "resourceType": "Microsoft.App/containerApps"
  },
  {
    "resourceType": "Microsoft.Data/sqlManagedInstances"
  }
]

Mostrar detalhes de um local personalizado

Para mostrar os detalhes de um local personalizado, use o seguinte comando:

az customlocation show -n <customLocationName> -g <resourceGroupName>

Listar locais personalizados

Para listar todos os locais personalizados em um grupo de recursos, use o seguinte comando:

az customlocation list -g <resourceGroupName>

Atualizar um local personalizado

Utilize o comando update para adicionar novos valores para --tags ou associar novos --cluster-extension-ids ao local personalizado, mantendo os valores existentes para marcas e extensões de cluster associadas.

az customlocation update -n <customLocationName> -g <resourceGroupName> --namespace <name of namespace> --host-resource-id <connectedClusterId> --cluster-extension-ids <extensionIds>

Aplicar um patch a um local personalizado

Utilize o comando patch para substituir os valores existentes para --cluster-extension-ids ou --tags. Os valores anteriores não são mantidos.

az customlocation patch -n <customLocationName> -g <resourceGroupName> --namespace <name of namespace> --host-resource-id <connectedClusterId> --cluster-extension-ids <extensionIds>

Excluir um local personalizado

Para excluir um local personalizado, use o seguinte comando:

az customlocation delete -n <customLocationName> -g <resourceGroupName>

Resolução de Problemas

Obter erro de credenciais de login na CLI do Azure v2.70.0

Você pode encontrar um erro que contém: TypeError: get_login_credentials() got an unexpected keyword argument 'resource'. A CLI do Azure v2.70.0 lançou uma alteração disruptiva que aciona este erro. Uma correção está disponível na az customlocation v0.1.4 para compatibilidade com a CLI do Azure v2.70.0 e superior.

Para usar uma versão inferior do az customlocation, você também deve usar a CLI do Azure versão 2.69.0 ou anterior. Se tiver usado o instalador da CLI do Azure, pode desinstalar a versão atual e instalar a CLI do Azure v2.69.0 a Azure CLI installation page partir do. Se você usou o instalador pip, você pode executar o seguinte comando para fazer downgrade: pip install azure-cli==2.69.0. No entanto, geralmente recomendamos o uso da versão mais recente do az customlocation e da CLI do Azure.

Erro de proxy desconhecido

Se a criação de um local personalizado falhar com o erro Unknown proxy error occurred, modifique a sua política de rede para permitir a comunicação interna entre pods dentro do namespace azure-arc. Certifique-se também de adicionar o azure-arc namespace como parte da lista de exclusão sem proxy para sua política configurada.

Aviso do service principal

Ao tentar habilitar o local personalizado enquanto estiver assinado na CLI do Azure usando um principal de serviço, poderá observar o seguinte aviso:

Unable to fetch oid of 'custom-locations' app. Proceeding without enabling the feature. Insufficient privileges to complete the operation.

Esse aviso ocorre porque a entidade de serviço não tem as permissões necessárias para recuperar a oid (ID do objeto) do local personalizado usado pelo serviço Azure Arc. Siga as instruções fornecidas para habilitar a funcionalidade de localização personalizada usando um principal de serviço.

O provedor de recursos não tem as permissões necessárias

Se você tentar criar o local personalizado antes que o recurso de local personalizado é habilitado no cluster Kubernetes, você receberá a seguinte mensagem de erro:

Deployment failed. Correlation ID: ... "Microsoft.ExtendedLocation" resource provider does not have the required permissions to create a namespace on the cluster. Refer to https://aka.ms/ArcK8sCustomLocationsDocsEnableFeature to provide the required permissions to the resource provider.

Primeiro, habilite o recurso de local personalizado no cluster. Depois que o recurso estiver habilitado, você poderá seguir as etapas para criar o local personalizado.

Próximos passos

  • Last updated on