Início Rápido: Usar a Configuração de Aplicativos do Azure no Serviço de Kubernetes do Azure

Artigo
10/17/2024

No Kubernetes, você configura os pods para consumir a configuração do ConfigMaps. Ele permite que você desacoplar a configuração de suas imagens de contêiner, tornando seus aplicativos facilmente portáteis. O Provedor do Kubernetes de Configuração de Aplicativos do Azure pode criar ConfigMaps e Segredos a partir de seus valores-chave e referências de Cofre de Chaves na Configuração de Aplicativos do Azure. Ele permite que você aproveite a Configuração de Aplicativos do Azure para o armazenamento centralizado e o gerenciamento da sua configuração sem alterações no código do aplicativo.

Um ConfigMap pode ser consumido como variáveis de ambiente ou um arquivo montado. Neste início rápido, você incorpora o Provedor do Kubernetes de Configuração de Aplicativos do Azure em uma carga de trabalho do Serviço de Kubernetes do Azure, na qual você executa um aplicativo ASP.NET Core simples, consumindo a configuração de um arquivo JSON.

Dica

Confira as opções de cargas de trabalho hospedadas no Kubernetes para acessar a Configuração de Aplicativos do Azure.

Observação

Este guia de início rápido explicará a configuração do Provedor do Kubernetes de Configuração de Aplicativos do Azure. Como alternativa, você pode usar os seguintes comandos da CLI do Desenvolvedor do Azure com o modelo azure-appconfig-aks para provisionar recursos do Azure e implantar o aplicativo de exemplo usado por este início rápido. Para obter mais informações sobre esse modelo, acesso o repositório azure-appconfig-aks no GitHub.

azd init -t azure-appconfig-aks
azd up

Pré-requisitos

Um repositório de Configuração de Aplicativos. Criar um repositório.
Um Registro de Contêiner do Azure. Criar um registro.
Um cluster do Serviço de Kubernetes do Azure (AKS) que recebe permissão para extrair imagens do Registro de Contêiner do Azure. Criar um cluster do AKS.
SDK do .NET 6.0 ou posterior
CLI do Azure
Docker Desktop
helm
kubectl

Crie um aplicativo em execução no AKS

Nesta seção, você criará um aplicativo Web ASP.NET Core simples em execução no Serviço de Kubernetes do Azure (AKS). O aplicativo lê a configuração de um arquivo JSON local. Na próxima seção, você permitirá que ele consuma a configuração da Configuração de Aplicativos do Azure sem alterar o código do aplicativo. Se você já tem um aplicativo AKS que lê a configuração de um arquivo, pule esta seção e vá para Usar o Provedor do Kubernetes de Configuração de Aplicativos. Você só precisa garantir que o arquivo de configuração gerado pelo provedor corresponda ao caminho do arquivo usado pelo aplicativo.

Criar um aplicativo

Use a interface de linha de comando (CLI) do .NET e execute o seguinte comando para criar um novo projeto de aplicativo Web ASP.NET Core em um novo diretório MyWebApp:
```
dotnet new webapp --output MyWebApp --framework net6.0
```

Abra Index.cshtml no diretório Páginas e atualize o conteúdo com o código a seguir.

@page
@model IndexModel
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
@{
    ViewData["Title"] = "Home page";
}

<style>
    h1 {
        color: @Configuration["Settings:FontColor"];
    }
</style>

<div class="text-center">
    <h1>@Configuration["Settings:Message"]</h1>
</div>

Crie um diretório config na raiz do projeto e adicione um arquivo mysettings.json a ele com o conteúdo a seguir.
```
{
  "Settings": {
    "FontColor": "Black",
    "Message": "Message from the local configuration"
  }
}
```

Abra program.cs e adicione o arquivo JSON à fonte de configuração chamando o método AddJsonFile.

// Existing code in Program.cs
// ... ...

// Add a JSON configuration source 
builder.Configuration.AddJsonFile("config/mysettings.json", reloadOnChange: true, optional: false);

var app = builder.Build();

// The rest of existing code in program.cs
// ... ...

Colocar o aplicativo em um contêiner

Execute o comando dotnet publish para compilar o aplicativo no modo de versão e criar os ativos no diretório publicado.
```
dotnet publish -c Release -o published
```
Crie um arquivo chamado Dockerfile na raiz do diretório do seu projeto, abra-o em um editor de texto e insira o conteúdo a seguir. Um Dockerfile é um arquivo de texto que não tem uma extensão e que é usado para criar uma imagem de contêiner.
```
FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS runtime
WORKDIR /app
COPY published/ ./
ENTRYPOINT ["dotnet", "MyWebApp.dll"]
```
Crie uma imagem de contêiner chamada aspnetapp executando o seguinte comando.
```
docker build --tag aspnetapp .
```

Enviar a imagem por push ao Registro de Contêiner do Azure

Execute o comando az acr login para fazer logon no registro de contêiner. O exemplo a seguir faz logon em um registro chamado myregistry. Substitua o nome do registro pelo seu.
```
az acr login --name myregistry
```
O comando retorna Login Succeeded quando o logon for bem-sucedido.
Use a marca docker para criar uma marca myregistry.azurecr.io/aspnetapp:v1 para a imagem aspnetapp.
```
docker tag aspnetapp myregistry.azurecr.io/aspnetapp:v1
```
Dica

Para examinar a lista de imagens e tags existentes do Docker, execute docker image ls. Neste cenário, você deverá ver pelo menos duas imagens: aspnetapp e myregistry.azurecr.io/aspnetapp.
Use o docker push para carregar a imagem no registro do contêiner. Por exemplo, o comando a seguir envia a imagem para um repositório chamado aspnetapp com a marca v1 no registro myregistry.
```
docker push myregistry.azurecr.io/aspnetapp:v1
```

Implantar o aplicativo

Crie um diretório Implantação no diretório raiz do seu projeto.

Adicione um arquivo deployment.yaml ao diretório Deployment com o seguinte conteúdo para criar uma implantação. Substitua o valor de template.spec.containers.image pela imagem que você criou na etapa anterior.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aspnetapp-demo
  labels:
    app: aspnetapp-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: aspnetapp-demo
  template:
    metadata:
      labels:
        app: aspnetapp-demo
    spec:
      containers:
      - name: aspnetapp
        image: myregistry.azurecr.io/aspnetapp:v1
        ports:
        - containerPort: 80

Adicione um arquivo service.yaml ao diretório Implantação com o seguinte conteúdo para criar um serviço LoadBalancer.

apiVersion: v1
kind: Service
metadata:
  name: aspnetapp-demo-service
spec:
  type: LoadBalancer
  ports:
  - port: 80
  selector:
    app: aspnetapp-demo

Execute o seguinte comando para implantar o aplicativo no cluster do AKS.

kubectl create namespace appconfig-demo
kubectl apply -f ./Deployment -n appconfig-demo

Execute o seguinte comando e obtenha o endereço IP externo exposto pelo serviço LoadBalancer.
```
kubectl get service aspnetapp-demo-service -n appconfig-demo
```
Abra uma janela do navegador e navegue até o endereço IP obtido na etapa anterior. A página da Web tem esta aparência:

Use o Provedor do Kubernetes de Configuração de Aplicativos

Agora que você tem um aplicativo em execução no AKS, você implantará o Provedor do Kubernetes de Configuração de Aplicativos no cluster do AKS em execução como um controlador de Kubernetes. O provedor recupera dados do seu repositório da Configuração de Aplicativos e cria um ConfigMap, que pode ser consumido como um arquivo JSON montado em um volume de dados.

Configurar o repositório de Configuração de Aplicativos do Azure

Adicione os seguintes valores-chave ao repositório de Configuração de Aplicativos e deixe o Rótulo e o Tipo de Conteúdo com seus valores padrão. Para mais informações sobre como adicionar valores-chave a um repositório usando o portal do Azure ou a CLI, acesse Criar um valor-chave.

Chave	Valor
Settings:FontColor	Verde
Settings:Message	Olá da Configuração de Aplicativos do Azure

Configurar o Provedor do Kubernetes de Configuração de Aplicativos

Execute o seguinte comando para obter credenciais de acesso para seu cluster do AKS. Substitua o valor dos parâmetros name e resource-group pela sua instância do AKS:
```
az aks get-credentials --name <your-aks-instance-name> --resource-group <your-aks-resource-group>
```
Instale o Provedor do Kubernetes da Configuração de Aplicativos do Azure no seu cluster do AKS usando helm:
```
helm install azureappconfiguration.kubernetesprovider \
     oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
     --namespace azappconfig-system \
     --create-namespace
```
Dica

O Provedor de Kubernetes de Configuração de Aplicativo também está disponível como uma extensão do AKS. Esta integração permite a instalação e o gerenciamento contínuos por meio da CLI do Azure, modelos do ARM ou modelos Bicep. Utilizar a extensão do AKS facilita atualizações automáticas de versão secundária/patch, garantindo que o seu sistema esteja sempre atualizado. Para obter instruções detalhadas de instalação, confira a extensão de Configuração de Aplicativo do Azure para o Serviço de Kubernetes do Azure.
Adicione um arquivo appConfigurationProvider.yaml ao diretório Implantação com o seguinte conteúdo para criar um recursoAzureAppConfigurationProvider. AzureAppConfigurationProvider é um recurso personalizado que define quais dados serão baixados de um repositório de Configuração de Aplicativos do Azure e cria um ConfigMap.
```
apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
    configMapData: 
      type: json
      key: mysettings.json
  auth:
    workloadIdentity:
      serviceAccountName: <your-service-account-name>
```
Substitua o valor do campo endpoint pelo ponto de extremidade do seu repositório de Configuração de Aplicativos do Azure. Prossiga para a próxima etapa e atualize a seção auth com suas informações de autenticação.
Observação

AzureAppConfigurationProvider é um objeto de API declarativa. Define o estado desejado do ConfigMap criado a partir dos dados no seu repositório de Configuração de Aplicativos com o seguinte comportamento:
- O ConfigMap não será criado se já existir um ConfigMap com o mesmo nome no mesmo namespace.
- O ConfigMap será redefinido com base nos dados presentes no seu repositório de Configuração de Aplicativos se ele for excluído ou modificado por qualquer outro meio.
- O ConfigMap será excluído se o Provedor do Kubernetes da Configuração de Aplicativos estiver desinstalado.
Siga as instruções para usar a identidade de carga de trabalho e se autenticar com seu repositório de Configuração de Aplicativos. Atualize o arquivo appConfigurationProvider.yaml trocando o campo serviceAccountName pelo nome da conta de serviço que você criou. Para saber mais sobre outros métodos de autenticação, dê uma olhada na seção Autenticação.

Atualize o arquivo deployment.yaml no diretório Implantação para usar o ConfigMap configmap-created-by-appconfig-provider como um volume de dados montado. É importante garantir que volumeMounts.mountPath corresponda ao WORKDIR especificado em seu Dockerfile e ao diretório config criado antes.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aspnetapp-demo
  labels:
    app: aspnetapp-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: aspnetapp-demo
  template:
    metadata:
      labels:
        app: aspnetapp-demo
    spec:
      containers:
      - name: aspnetapp
        image: myregistry.azurecr.io/aspnetapp:v1
        ports:
        - containerPort: 80
        volumeMounts:
        - name: config-volume
          mountPath: /app/config
      volumes:
      - name: config-volume 
        configMap: 
          name: configmap-created-by-appconfig-provider

Execute o comando a seguir para implantar as alterações. Substitua o namespace se estiver usando o aplicativo do AKS existente.
```
kubectl apply -f ./Deployment -n appconfig-demo
```
Atualize o navegador. A página mostra o conteúdo atualizado.

Solução de problemas

Se você não vir o aplicativo coletando os dados do repositório de Configuração de Aplicativos, execute o comando a seguir para validar se o ConfigMap foi criado corretamente.

kubectl get configmap configmap-created-by-appconfig-provider -n appconfig-demo

Se o ConfigMap não for criado, execute o comando a seguir para obter o status de recuperação dos dados.

kubectl get AzureAppConfigurationProvider appconfigurationprovider-sample -n appconfig-demo -o yaml

Se o Provedor do Kubernetes de Configuração de Aplicativos do Azure recuperou os dados do seu repositório de Configuração de Aplicativos com êxito, a propriedade phase na seção de status da saída deverá ser COMPLETE, conforme mostrado no exemplo a seguir.

$ kubectl get AzureAppConfigurationProvider appconfigurationprovider-sample -n appconfig-demo -o yaml

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
  ... ... ...
status:
  lastReconcileTime: "2023-04-06T06:17:06Z"
  lastSyncTime: "2023-04-06T06:17:06Z"
  message: Complete sync settings to ConfigMap or Secret
  phase: COMPLETE

Se a fase não for COMPLETE, os dados não serão baixados do seu repositório de Configuração de Aplicativos corretamente. Execute o seguinte comando para mostrar os logs do Provedor do Kubernetes da Configuração de Aplicativos do Azure.

kubectl logs deployment/az-appconfig-k8s-provider -n azappconfig-system

Use os logs para solucionar problemas adicionais. Consulte a seção perguntas frequentes sobre problemas comuns.

Perguntas frequentes

Por que o ConfigMap ou o Segredo não está sendo gerado?

Você pode seguir as etapas no guia de Solução de problemas para coletar logs para obter informações detalhadas de erro. Aqui estão algumas causas comuns.

RESPONSE 403: 403 Proibido: a identidade configurada não tem as permissões necessárias para acessar o repositório de Configuração de Aplicativos. Consulte a seção Autenticação para obter exemplos que correspondam à identidade que você está usando.
Uma referência do Key Vault é encontrada na Configuração de Aplicativos, mas 'spec.secret' não foi configurada: uma ou mais referências do Key Vault são incluídas nos valores de chave selecionados, mas as informações de autenticação para Key Vaults não são fornecidas. Para manter a integridade da configuração, toda a configuração não é carregada. Configure a seção spec.secret para fornecer as informações de autenticação necessárias. Para obter exemplos e mais informações, consulte referência do Key Vault.

Por que o ConfigMap gerado não contém os dados esperados?

Especifique os seletores de chave-valor corretos para corresponder aos dados esperados. Se nenhum seletor for especificado, todos os valores de chave sem um rótulo serão baixados do repositório de Configuração de Aplicativos. Ao usar um filtro de chave, verifique se ele corresponde ao prefixo dos valores de chave esperados. Se os valores-chave tiverem rótulos, especifique o filtro de rótulo nos seletores. Para obter mais exemplos, consulte a documentação de seleção chave-valor.

Como personalizar a instalação do Provedor de Kubernetes de Configuração de Aplicativos do Azure?

Você pode personalizar a instalação fornecendo valores adicionais do Helm ao instalar o Provedor de Kubernetes de Configuração de Aplicativos do Azure. Por exemplo, você pode definir o nível de log, configurar o provedor para ser executado em um nó específico ou desabilitar a identidade da carga de trabalho. Consulte o guia de instalação para obter mais informações.

Como disparar a atualização sob demanda de ConfigMap e Secret

Embora você possa configurar a atualização automática de dados, há momentos em que talvez queira disparar uma atualização sob demanda para obter os dados mais recentes da Configuração de Aplicativos e do Key Vault. Para fazer isso, você pode reiniciar a implantação do controlador do provedor do Kubernetes da Configuração de Aplicativos do Azure. O provedor do Kubernetes reconciliará e atualizará o ConfigMap e Secret com os dados mais recentes do repositório de Configuração de Aplicativos e do Key Vault.

Não é recomendável excluir ou modificar o ConfigMap e Secret gerados pelo provedor do Kubernetes. Embora novos sejam gerados com base nos dados mais recentes, isso pode causar tempo de inatividade para seus aplicativos em caso de falhas.

Por que não consigo me autenticar com a Configuração de Aplicativos do Azure usando a identidade de carga de trabalho depois de atualizar o provedor para a versão 2.0.0?

A partir da versão 2.0.0, você precisa usar uma conta de serviço fornecida pelo usuário para se autenticar com a Configuração de Aplicativos do Azure usando identidade de carga de trabalho. Essa mudança aumenta a segurança ao isolar os namespaces. Antes disso, a conta de serviço do provedor Kubernetes era usada para todos os namespaces. Para obter instruções atualizadas, confira a documentação sobre como usar a identidade da carga de trabalho. Se precisar de mais tempo para migrar ao atualizar para a versão 2.0.0, você pode definir temporariamente workloadIdentity.globalServiceAccountEnabled=true durante a instalação do provedor. Atenção: o suporte para o uso da conta de serviço do provedor será descontinuado em uma versão futura.

Limpar os recursos

Desinstale o Provedor do Kubernetes de Configuração de Aplicativos do seu cluster do AKS se quiser manter o cluster do AKS.

helm uninstall azureappconfiguration.kubernetesprovider --namespace azappconfig-system

Se não deseja continuar usando os recursos criados neste artigo, exclua o grupo de recursos que você criou aqui para evitar encargos.

Importante

A exclusão de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos contidos nele são excluídos permanentemente. Não exclua acidentalmente grupo de recursos ou recursos incorretos. Se tiver criado os recursos para este artigo dentro de um grupo de recursos que contém outros recursos que você deseja manter, exclua cada um individualmente do respectivo painel em vez de excluir o grupo de recursos.

Entre no portal do Azure e selecione Grupos de recursos.
Na caixa Filtrar por nome..., digite o nome do seu grupo de recursos.
Na lista de resultados, selecione o nome do grupo de recursos para conferir uma visão geral.
Selecione Excluir grupo de recursos.
Você receberá uma solicitação para confirmar a exclusão do grupo de recursos. Insira o nome do grupo de recursos para confirmar e selecione Excluir.

Após alguns instantes, o grupo de recursos e todos os recursos dele são excluídos.

Observação

Se você usar a CLI do Desenvolvedor do Azure para configurar os recursos, poderá executar o comando azd down para excluir todos os recursos criados pelo modelo azure-appconfig-aks.

Próximas etapas

Neste início rápido, você:

Criou um aplicativo em execução no Serviço de Kubernetes do Azure (AKS).
Conectou seu cluster do AKS ao seu repositório de Configuração de Aplicativos usando o Provedor do Kubernetes da Configuração de Aplicativos.
Criou um ConfigMap com os dados do seu repositório de Configuração de Aplicativos.
Execute o aplicativo com a configuração do seu repositório de Configuração de Aplicativos sem alterar o código do aplicativo.

Para saber como atualizar suas cargas de trabalho do AKS para atualizar dinamicamente a configuração, prossiga para o próximo tutorial.

Usar a configuração dinâmica no Serviço de Kubernetes do Azure

Para saber mais sobre o Provedor de Kubernetes da Configuração de Aplicativos do Azure, confira Referência do Provedor de Kubernetes da Configuração de Aplicativos do Azure.

Compartilhar via