Compartilhar via

Como usar o Service Connector 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 que o Service Connector cria.
  • Como solucionar problemas e exibir logs do Service Connector em um cluster do AKS.

Pré-requisitos

Quais operações o Service Connector faz no cluster

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.

Adicionar a extensão kubernetes as Service Connector

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 Service Connector. 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.

Criar recursos do kubernetes

O Service Connector 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 Service Connector para cada conexão de serviço no portal do Azure no recurso kubernetes, no menu do Service Connector.

Captura de tela do portal do Azure, exibir os recursos do Kubernetes criados pelo Service Connector.

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.

Habilitar o 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.

Habilitar 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.

Como usar os recursos do kubernetes criados pelo Service Connector

Recursos diferentes do kubernetes são criados quando o tipo de serviço de destino e o tipo de autenticação são diferentes. As seções a seguir mostram como usar os recursos do kubernetes criados pelo Service Connector em sua definição de cargas de trabalho de cluster e códigos 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 é 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

Em seguida, os códigos do aplicativo podem consumir a cadeia de conexão no segredo da variável de ambiente. Você pode verificar o código de exemplo para saber mais sobre os nomes das variáveis de ambiente e como usá-los em seus códigos 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 é 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

Você pode verificar o tutorial para saber como se conectar ao Armazenamento do Microsoft Azure usando a identidade da carga de trabalho.

Como solucionar problemas e exibir logs

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

Verificar a extensão do kubernetes do Service Connector

A extensão de kubernetes do Service Connector é criada com base nas extensões de cluster do Kubernetes habilitadas para Azure Arc. Use os comandos a seguir para investigar se há erros durante a 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
  1. Obtenha o status da extensão do Service Connector. Verifique a propriedade statuses na saída do comando para ver se há erros.
az k8s-extension show \
    --resource-group MyClusterResourceGroup \
    --cluster-name MyCluster \
    --cluster-type managedClusters \
    --name sc-extension

Verificar logs de cluster do kubernetes

Se houver um erro durante a instalação da extensão e a mensagem de erro na propriedade statuses não fornecer informações suficientes sobre o que aconteceu, você poderá verificar ainda mais 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 Service Connector é instalada no namespace sc-system por meio do gráfico helm, verifique o namespace e a versão do helm seguindo comandos.

    • 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. A falha de execução do trabalho geralmente causa a falha de extensão. 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

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. Isso também pode acontecer quando sua assinatura não é registrada para o provedor de recursos Microsoft.KubernetesConfiguration.

Atenuação:

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

    az provider register -n Microsoft.KubernetesConfiguration

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

Timeout

Mensagem de erro:

  • Long running operation failed with status 'Failed'. Unable to get a response from the Agent in time.
  • Timed out waiting for the resource to come to a ready/completed state

Motivo: esse erro geralmente ocorre quando o trabalho do Kubernetes usado para criar ou atualizar a extensão de cluster do Service Connector não é agendado devido a limitações de recursos ou outros problemas.

Mitigação: consulte Verificar logs de cluster do Kubernetes para identificar e resolver os motivos detalhados. Um problema comum é que nenhum nó está disponível devido à preempção. Nesse caso, considere adicionar mais nós ou habilitar o dimensionamento automático para seus nós.

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 Service Connector 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.

Mitigaçã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 para Microsoft.KubernetesConfiguration, que é o provedor de recursos para Extensões de cluster do Kubernetes habilitado para Azure Arc.

Mitigaçã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 este tutorial.

az provider register -n Microsoft.KubernetesConfiguration

Outros problemas

Se as mitigações acima não resolverem o problema, tente redefinir a extensão do cluster do conector de serviço removendo-a e repetindo a criação. Espera-se que esse método resolva a maioria dos problemas relacionados à extensão de cluster do Conector do Serviço.

Use os seguintes comandos da CLI para redefinir a extensão:

az extension add --name k8s-extension

az k8s-extension delete \
    --resource-group <MyClusterResourceGroup> \
    --cluster-name <MyCluster> \
    --cluster-type managedClusters \
    --name sc-extension

Próximas etapas

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