Compartilhar via

Usar o Conector de Serviço no AKS (Serviço de Kubernetes do Azure)

  • Artigo

O AKS (Serviço de Kubernetes do Azure) é um dos serviços de computação com suporte do Service Connector. Este artigo tem como objetivo ajudá-lo a entender:

  • Quais operações são feitas no cluster ao criar uma conexão de serviço.
  • Como usar os recursos Kubernetes criados pelo Conector de Serviço.
  • Como solucionar problemas e exibir logs do Conector de Serviço em um cluster do AKS.

Pré-requisitos

Operações executadas pelo Conector de Serviço no cluster do AKS

Dependendo dos diferentes serviços de destino e tipos de autenticação selecionados ao criar uma conexão de serviço, o Service Connector faz operações diferentes no cluster do AKS. Listaremos as possíveis operações feitas pelo Service Connector.

Adicionando a extensão Kubernetes ao Conector de Serviço

Uma extensão Kubernetes nomeada sc-extension é adicionada ao cluster na primeira vez que uma conexão de serviço é criada. Posteriormente, a extensão ajuda a criar recursos do Kubernetes no cluster do usuário, sempre que uma solicitação de conexão de serviço chega ao Conector de Serviço. Você pode encontrar a extensão no seu cluster do AKS no portal do Azure, no menu Extensões + aplicativos.

Captura de tela do portal do Azure, exiba a extensão do AKS.

A extensão também é onde os metadados de conexões de cluster são armazenados. Desinstalar a extensão torna todas as conexões no cluster indisponíveis. O operador de extensão é hospedado no namespace sc-system do cluster.

Criando recursos do Kubernetes

O Conector de Serviço cria alguns recursos do Kubernetes para o namespace especificado pelo usuário ao criar uma conexão de serviço. Os recursos do Kubernetes armazenam as informações de conexão, que são necessárias pelas definições de carga de trabalho do usuário ou pelo código do aplicativo para conversar com os serviços de destino. Dependendo de diferentes tipos de autenticação, recursos diferentes do Kubernetes são criados. Para os tipos de autenticaçãoConnection String e Service Principal, um segredo do Kubernetes é criado. Para o tipo de autenticação Workload Identity, uma conta de serviço do Kubernetes também é criada além de um segredo do Kubernetes.

Você pode encontrar os recursos do Kubernetes criados pelo Conector de Serviço para cada conexão de serviço no portal do Azure no recurso Kubernetes, no menu do Conector de Serviço.

Captura de tela do portal do Azure, exibir os recursos do Kubernetes criados pelo Conector de Serviço.

Excluir uma conexão de serviço não exclui o recurso do Kubernetes associado. Se necessário, remova seu recurso manualmente, usando, por exemplo, o comando kubectl delete.

Habilitação do complemento azureKeyvaultSecretsProvider

Se o serviço de destino for o Azure Key Vault e o Driver CSI do Repositório Secreto estiver habilitado ao criar uma conexão de serviço, o Service Connector habilitará o complemento azureKeyvaultSecretsProvider para o cluster.

Captura de tela do portal do Azure, habilitando o driver CSI para keyvault ao criar uma conexão.

Siga o tutorial Conectar-se ao Azure Key Vault usando o driver CSI para configurar uma conexão com o Azure Key Vault usando o driver CSI do Repositório Secreto.

Habilitando a identidade da carga de trabalho e o emissor do OpenID Connect (OIDC)

Se o tipo de autenticação for Workload Identity ao criar uma conexão de serviço, o Service Connector habilitará a identidade da carga de trabalho e o emissor do OIDC para o cluster.

Captura de tela do portal do Azure usando a identidade da carga de trabalho para criar uma conexão.

Quando o tipo de autenticação é Workload Identity, uma identidade gerenciada atribuída pelo usuário é necessária para criar a credencial de identidade federada. Saiba mais sobre o que são identidades de carga de trabalho ou siga o tutorial para configurar uma conexão com o Armazenamento do Microsoft Azure usando a identidade da carga de trabalho.

Usar os recursos Kubernetes criados pelo Conector de Serviço

Vários recursos do Kubernetes são criados pelo Conector de Serviço dependendo do tipo de serviço de destino e do tipo de autenticação. As seções a seguir mostram como usar os recursos do Kubernetes criados pelo Conector de Serviço em sua definição de cargas de trabalho de cluster e código de aplicativo.

Segredo do Kubernetes

Um segredo do Kubernetes é criado quando o tipo de autenticação é Connection String ou Service Principal. A definição da carga de trabalho do cluster pode referenciar o segredo diretamente. O snippet a seguir fornece um exemplo.

apiVersion: batch/v1
kind: Job
metadata:
  namespace: default
  name: sc-sample-job
spec:
  template:
    spec:
      containers:
      - name: raw-linux
        image: alpine
        command: ['printenv']
        envFrom:
          - secretRef:
              name: <SecretCreatedByServiceConnector>
      restartPolicy: OnFailure

O código do aplicativo pode consumir a cadeia de conexão no segredo de uma variável de ambiente. Verifique o código de exemplo a seguir para saber mais sobre os nomes das variáveis de ambiente e como usá-los em seu código de aplicativo para autenticar em diferentes serviços de destino.

Conta de Serviço do Kubernetes

Uma conta de serviço do Kubernetes e um segredo são criados quando o tipo de autenticação é definido como Workload Identity. A definição da carga de trabalho do cluster pode referenciar a conta de serviço e o segredo para autenticar por meio da identidade da carga de trabalho. O snippet a seguir fornece um exemplo.

apiVersion: batch/v1
kind: Job
metadata:
  namespace: default
  name: sc-sample-job
  labels:
    azure.workload.identity/use: "true"
spec:
  template:
    spec:
      serviceAccountName: <ServiceAccountCreatedByServiceConnector>
      containers:
      - name: raw-linux
        image: alpine
        command: ['printenv']
        envFrom:
          - secretRef:
              name: <SecretCreatedByServiceConnector>
      restartPolicy: OnFailure

Verifique o tutorial a seguir para saber como se conectar ao Armazenamento do Microsoft Azure usando a identidade da carga de trabalho.

Solucionar problemas e exibir logs

Se ocorrer um erro e não puder ser resolvido ao tentar novamente ao criar uma conexão de serviço, os métodos a seguir ajudam a coletar mais informações para solução de problemas.

Verificar a extensão do Kubernetes do Conector de Serviço

A extensão de Kubernetes do Conector de Serviço é criada com base nas extensões de cluster do Kubernetes habilitadas para Azure Arc. Use os comandos a seguir para verificar se ocorreram erros durante o processo de instalação ou atualização da extensão.

  1. Instale a extensão k8s-extension da CLI do Azure.

    az extension add --name k8s-extension

  2. Recupere o status da extensão do Conector de Serviço. Verifique a propriedade statuses na saída do comando para identificar erros.

    az k8s-extension show \
    --resource-group MyClusterResourceGroup \
    --cluster-name MyCluster \
    --cluster-type managedClusters \
    --name sc-extension

Verificar logs de cluster do Kubernetes

Se ocorrer um erro durante a instalação da extensão e a mensagem de erro na propriedade statuses não fornecer informações suficientes, você poderá investigar ainda mais verificando os logs do Kubernetes com as etapas a seguir.

  1. Conectar-se ao cluster do AKS.

    az aks get-credentials \
    --resource-group MyClusterResourceGroup \
    --name MyCluster

  2. A extensão do Conector de Serviço é instalada no namespace sc-system usando um gráfico do Helm. Verifique o namespace e a versão do Helm usando os comandos a seguir.

    • Verifique se o namespace existe.

      kubectl get ns

    • Verifique o status da versão do helm.

      helm list -n sc-system

  3. Durante a instalação ou atualização da extensão, um trabalho do Kubernetes chamado sc-job cria os recursos do Kubernetes para a conexão de serviço. Uma falha de execução de trabalho normalmente faz com que a extensão falhe. Verifique o status do trabalho executando os comandos a seguir. Se sc-job não existir no namespace sc-system, ele deverá ter sido executado com êxito. Esse trabalho foi projetado para ser excluído automaticamente após a execução bem-sucedida.

    • Verifique se o trabalho existe.

      kubectl get job -n sc-system

    • Obtenha o status do trabalho.

      kubectl describe job/sc-job -n sc-system

    • Exiba os logs de trabalho.

      kubectl logs job/sc-job -n sc-system

Erros e mitigações comuns

Erro de criação de extensão

Mensagem de erro:

Unable to get a response from the agent in time.

Atenuação:

Consulte erros de criação de extensão

Erros do Helm

Mensagens de erro:

  • Timed out waiting for resource readiness
  • Unable to download the Helm chart from the repo URL
  • Helm chart rendering failed with given values
  • Resource already exists in your cluster
  • Operation is already in progress for Helm

Atenuação:

Consulte Erros do Helm

Conflito

Mensagem de erro:

Operation returned an invalid status code: Conflict.

Motivo:

Esse erro geralmente ocorre ao tentar criar uma conexão de serviço enquanto o cluster do AKS (Serviço de Kubernetes do Azure) está em um estado de atualização. A atualização de conexão de serviço entra em conflito com a atualização em andamento. Esse erro também ocorre quando sua assinatura não está registrada no provedor de recursos Microsoft.KubernetesConfiguration.

Atenuação:

  1. Verifique se o cluster está em um estado "Bem-sucedido" e tente novamente a criação.

  2. Execute o comando a seguir para verificar se sua assinatura está registrada no provedor de recursos Microsoft.KubernetesConfiguration.

    az provider register -n Microsoft.KubernetesConfiguration

Acesso a recursos não autorizados

Mensagem de erro:

You do not have permission to perform ... If access was recently granted, please refresh your credentials.

Motivo:

O Conector de Serviço requer permissões para operar os recursos do Azure aos quais você deseja se conectar, a fim de executar operações de conexão em seu nome. Esse erro indica a falta de permissões necessárias em alguns recursos do Azure.

Atenuação:

Verifique as permissões nos recursos do Azure especificados na mensagem de erro. Obtenha as permissões necessárias e repita a criação.

Registro de assinatura ausente

Mensagem de erro:

The subscription is not registered to use namespace 'Microsoft.KubernetesConfiguration'

Motivo:

O conector de serviço exige que a assinatura seja registrada com Microsoft.KubernetesConfiguration, que é o provedor de recursos para Extensões de cluster do Kubernetes habilitado para Azure Arc.

Atenuação:

Registre o provedor de recursos Microsoft.KubernetesConfiguration executando o comando a seguir. Para obter mais informações sobre erros de registro do provedor de recursos, consulte Resolver erros para registro do provedor de recursos.

az provider register -n Microsoft.KubernetesConfiguration

Próxima etapa

Saiba como integrar diferentes serviços de destino e ler sobre suas configurações e métodos de autenticação.

Saiba mais sobre como integrar o blob de armazenamento