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

2025-09-02

No Kubernetes, você pode configurar pods para consumir dados de configuração do ConfigMaps. Essa prática melhora a portabilidade de seus aplicativos, pois você pode desacoplar dados de configuração de suas imagens de contêiner.

O Provedor de Kubernetes de Configuração de Aplicativo do Azure oferece uma maneira de construir o Kubernetes ConfigMaps e segredos com base em valores-chave e referências do Azure Key Vault armazenadas na Configuração de Aplicativos. Ao usar esse provedor, você pode usar a Configuração de Aplicativos para armazenar e gerenciar centralmente seus dados de configuração sem fazer 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ê incorporará o Provedor de Kubernetes de Configuração de Aplicativos do Azure em sua carga de trabalho do AKS. O provedor cria um ConfigMap com base em dados no repositório de Configuração de Aplicativos. Na carga de trabalho, você executa um aplicativo básico ASP.NET Core em um pod que consome o ConfigMap como um arquivo JSON montado em um volume de dados.

Dica

Para obter outras maneiras de acessar a Configuração de Aplicativos de uma carga de trabalho hospedada no Kubernetes, consulte o acesso do Serviço de Kubernetes do Azure à Configuração de Aplicativos.

Observação

Este guia de início rápido orienta você pela configuração do Provedor de Kubernetes de Configuração de Aplicativos do Azure. Opcionalmente, você pode usar os seguintes comandos da CLI do Desenvolvedor do Azure para provisionar recursos do Azure e implantar o aplicativo de exemplo que este início rápido usa. Esses comandos usam o azure-appconfig-aks modelo para essa finalidade. Para obter mais informações sobre esse modelo, consulte o repositório GitHub azure-appconfig-aks .

azd init -t azure-appconfig-aks
azd up

Pré-requisitos

Um repositório de Configuração de Aplicativos. Criar um repositório.
Uma instância do Registro de Contêiner do Azure. Criar um registro.
Um cluster do AKS que tem permissão para efetuar pull de imagens do registro de contêiner. Criar um cluster do AKS.
SDK do .NET 8.0 ou posterior.
A CLI do Azure.
Área de Trabalho do Docker.
Helm.
kubectl.

Criar um aplicativo executado no AKS

Nesta seção, você criará um aplicativo Web básico do ASP.NET Core que é executado no AKS. O aplicativo lê dados de configuração de um arquivo JSON local. Na próxima seção, você permite que o aplicativo consuma dados de configuração da Configuração de Aplicativos sem alterar o código do aplicativo.

Se você já tiver um aplicativo AKS que lê a configuração de um arquivo, ignore esta seção e vá para Usar o Provedor de Kubernetes de Configuração de Aplicativo do Azure. Se você ignorar esta seção, verifique se o arquivo de configuração gerado pelo provedor corresponde ao caminho do arquivo que seu aplicativo usa.

Criar um aplicativo

Use a CLI (interface de linha de comando) do .NET para executar o comando a seguir. Ele cria um projeto de aplicativo Web ASP.NET Core em um novo diretório MyWebApp .
```
dotnet new webapp --output MyWebApp --framework net8.0
```

No diretório MyWebApp , vá para o diretório Páginas e abra Index.cshtml. Substitua o conteúdo pelo seguinte código:

@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 de configuração na raiz do projeto. No diretório de configuração , adicione um arquivo mysettings.json que contém o seguinte conteúdo:
```
{
  "Settings": {
    "FontColor": "Black",
    "Message": "Message from the local configuration"
  }
}
```

No diretório raiz do projeto, abra Program.cs e adicione o arquivo JSON à fonte de configuração chamando o AddJsonFile método.

// 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 the existing code in Program.cs
// ... ...

Colocar o aplicativo em um contêiner

Para criar o aplicativo no modo de versão e criar os ativos no diretório publicado , execute o comando de publicação do dotnet .
```
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. Você a usa para criar uma imagem de contêiner.
```
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app
COPY published/ ./
ENTRYPOINT ["dotnet", "MyWebApp.dll"]
```
Crie uma imagem de contêiner nomeada aspnetapp executando o seguinte comando:
```
docker build --tag aspnetapp .
```

Enviar a imagem por push para o Registro de Contêiner

Para entrar no registro de contêiner, execute o comando az acr login . O código a seguir entra em um registro chamado myregistry. Substitua esse nome do registro pelo nome do registro.
```
az acr login --name myregistry
```
O comando retornará Login Succeeded se você entrar com êxito.
Para criar uma marca chamada myregistry.azurecr.io/aspnetapp:v1 para a aspnetapp imagem, use o comando de marca do docker . Substitua myregistry pelo nome do registro.
```
docker tag aspnetapp myregistry.azurecr.io/aspnetapp:v1
```
Dica

Para examinar a lista de imagens e marcas existentes do Docker, execute docker image ls. Nesse cenário, a saída deve listar pelo menos duas imagens: aspnetapp e myregistry.azurecr.io/aspnetapp.
Para carregar a imagem no registro de contêiner, use o comando docker push . Por exemplo, o comando a seguir envia a imagem por push para um repositório nomeado aspnetapp com 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.

Para definir uma implantação, adicione um arquivo deployment.yaml com o seguinte conteúdo ao diretório de implantação . Substitua o valor da template.spec.containers.image marca que você criou na seção 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

Para definir um LoadBalancer serviço, adicione um arquivo service.yaml com o seguinte conteúdo ao diretório de implantação :

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

Para permitir que o kubectl se conecte ao cluster do AKS, execute o comando a seguir. Ele baixa as credenciais do cluster do AKS e as mescla no contexto do cluster.
```
az aks get-credentials --name <your-AKS-instance-name> --resource-group <your-AKS-resource-group>
```
Para implantar o aplicativo no cluster do AKS e criar os recursos, execute os seguintes comandos:
```
kubectl create namespace appconfig-demo
kubectl apply -f ./Deployment -n appconfig-demo
```
Para obter o endereço IP externo exposto pelo LoadBalancer serviço, execute o seguinte comando:
```
kubectl get service aspnetapp-demo-service -n appconfig-demo
```
Em uma janela do navegador, vá para o endereço IP obtido na etapa anterior. A página da Web deve ser semelhante à seguinte captura de tela:

Usar o Provedor de Kubernetes de Configuração de Aplicativo do Azure

Agora que você tem um aplicativo em execução no AKS, a próxima etapa é implantar o Provedor de Kubernetes de Configuração de Aplicativo do Azure no cluster do AKS para ser executado como um controlador do 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

Adicione as seguintes chaves e valores ao repositório de Configuração de Aplicativos. Para cada um deles, use valores padrão para Rótulo e Tipo de Conteúdo. Para obter mais informações sobre como adicionar chave-valor a um repositório usando o portal do Azure ou a CLI do Azure, consulte Criar um valor-chave.

Chave	Valor
Configurações:FontColor	Verde
Configurações:Mensagem	Olá da Configuração de Aplicativos do Azure

Configurar o Provedor de Kubernetes de Configuração de Aplicativo do Azure

Instale o Provedor de Kubernetes de Configuração de Aplicativo do Azure no cluster do AKS. Você pode instalar o provedor como uma extensão do AKS ou usando um gráfico do Helm. A extensão do AKS fornece instalação e gerenciamento contínuos por meio da CLI do Azure, modelos do ARM (modelos do Azure Resource Manager) ou arquivos Bicep. Além disso, o uso da extensão do AKS facilita atualizações automáticas de versão secundária e de patch, ajudando a garantir que seu sistema permaneça atualizado.
- Extensão do AKS
- Pacote do Helm
Adicione as k8s-extension extensões da CLI do Azure.
```
az extension add --name k8s-extension
```
Registre o provedor de KubernetesConfiguration recursos.
```
az provider register --namespace Microsoft.KubernetesConfiguration
```
Instale a extensão do AKS para a Configuração de Aplicativos. Substitua os valores e resource-group os cluster-name valores de parâmetro pelos valores correspondentes da instância do AKS. Por padrão, o provedor é instalado no azappconfig-system namespace.
```
az k8s-extension create --cluster-type managedClusters \
    --cluster-name <your-AKS-instance-name> \
    --resource-group <your-AKS-resource-group> \
    --name appconfigurationkubernetesprovider \
    --extension-type Microsoft.AppConfiguration
```
Para obter mais informações, consulte Instalar a extensão AKS da Configuração de Aplicativos do Azure.
Execute o seguinte comando para obter credenciais de acesso para seu cluster do AKS. Substitua os valores e resource-group os name valores de parâmetro pelos valores correspondentes da instância do AKS.
```
az aks get-credentials --name <your-AKS-instance-name> --resource-group <your-AKS-resource-group>
```
Instale o gráfico do Helm.
```
helm install azureappconfiguration.kubernetesprovider \
    oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
    --namespace azappconfig-system \
    --create-namespace
```
Para definir um AzureAppConfigurationProvider recurso, adicione um arquivo appConfigurationProvider.yaml com o seguinte conteúdo ao diretório de implantação . AzureAppConfigurationProvider é um recurso personalizado. Ele define os dados a serem baixados de um repositório de Configuração de Aplicativos. Ele também 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. Ele define o estado desejado do ConfigMap criado a partir dos dados no repositório de Configuração de Aplicativos. A definição do estado desejado especifica o seguinte comportamento:
- A criação do ConfigMap falhará se um ConfigMap com o mesmo nome já existir no mesmo namespace.
- O ConfigMap é redefinido com base nos dados presentes no 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 de Kubernetes de Configuração de Aplicativo do Azure estiver desinstalado.
Para autenticar com o repositório de Configuração de Aplicativos, siga as instruções para usar a identidade da carga de trabalho. Atualize o arquivo appConfigurationProvider.yaml substituindo o serviceAccountName campo pelo nome da conta de serviço que você cria ao seguir as instruções. Para obter mais informações sobre outros métodos de autenticação, consulte os exemplos na Autenticação.

Conforme mostrado no código a seguir, 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 que o volumeMounts.mountPath valor corresponda ao WORKDIR valor especificado em seu Dockerfile e ao diretório de configuração que você criou anteriormente. Além disso, verifique se o valor corresponde template.spec.containers.image ao nome da imagem que você criou anteriormente.

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

Para implantar as alterações, execute o comando a seguir. Atualize o namespace se você estiver usando seu aplicativo 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 o aplicativo não ler os dados do repositório de Configuração de Aplicativos, execute o seguinte comando para verificar 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 seguinte comando para obter o status de recuperação de dados:

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

Se o Provedor de Kubernetes de Configuração de Aplicativo do Azure recuperar dados do repositório de Configuração de Aplicativos com êxito, a phase propriedade na status seção 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: "2025-08-04T13:58:02Z"
  lastSyncTime: "2025-08-04T13:58:02Z"
  message: Complete sync key-values from App Configuration to target ConfigMap or
    Secret.
  phase: Complete

Se a propriedade de fase não COMPLETEestiver, os dados não serão baixados do repositório de Configuração de Aplicativos corretamente. Para acessar os logs do Provedor de Kubernetes de Configuração de Aplicativo do Azure, execute o seguinte comando:

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

Use os logs para solucionar problemas adicionais. Para obter soluções para problemas comuns, consulte perguntas frequentes.

perguntas frequentes

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

Para coletar logs que contêm informações detalhadas de erro, siga as etapas na solução de problemas. Aqui estão algumas causas comuns deste problema:

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. Para obter exemplos que correspondam à identidade que você está usando, consulte Autenticação.
Uma referência do Key Vault é encontrada na Configuração de Aplicativos, mas 'spec.secret' não foi configurado: uma ou mais referências do Key Vault são incluídas nos valores de chave selecionados, mas as informações de autenticação do Key Vault 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 as referências do Key Vault .

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

Verifique se os seletores chave-valor que você especificar correspondem aos dados esperados. Se você não especificar nenhum seletor, 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 seleção chave-valor.

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

Você pode personalizar a instalação fornecendo valores adicionais do Helm ao instalar o Provedor de Kubernetes de Configuração de Aplicativo 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. Para obter mais informações, consulte Instalação.

Como posso disparar uma atualização sob demanda do ConfigMap e do Segredo?

Você pode configurar os dados para atualizar automaticamente. Mas há momentos em que talvez você queira disparar uma atualização sob demanda para obter os dados mais recentes da Configuração de Aplicativos e do Key Vault. Para disparar uma atualização, você pode modificar a metadata.annotations seção de AzureAppConfigurationProvider. Em seguida, o provedor do Kubernetes atualiza o ConfigMap e o Segredo com os dados mais recentes do repositório de Configuração de Aplicativos e do Key Vault. Para obter um exemplo, consulte a atualização sob demanda.

Não recomendamos excluir ou modificar o ConfigMap e o Segredo gerados pelo provedor do Kubernetes. Novos são gerados com base nos dados mais recentes, mas essa situação pode causar tempo de inatividade para seus aplicativos durante falhas.

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

A partir da versão 2.0.0, uma conta de serviço fornecida pelo usuário é necessária para autenticação com a Configuração de Aplicativo usando a identidade da carga de trabalho. Essa mudança aumenta a segurança ao isolar os namespaces. Anteriormente, a conta de serviço de um provedor do 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 você precisar de tempo para migrar ao atualizar para a versão 2.0.0, poderá usar temporariamente a configuração durante a workloadIdentity.globalServiceAccountEnabled=true instalação do provedor. Observe que o suporte para usar a conta de serviço do provedor está agendado para substituição em uma versão futura.

Limpar os recursos

Se você quiser desinstalar o Provedor de Kubernetes de Configuração de Aplicativo do Azure, mas manter o cluster do AKS, use o seguinte comando para desinstalar o provedor:

Extensão do AKS
Pacote do Helm

az k8s-extension delete --cluster-type managedClusters \
    --cluster-name <your-AKS-instance-name> \
    --resource-group <your-AKS-resource-group> \
    --name appconfigurationkubernetesprovider

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 AKS.
Conectou o cluster do AKS ao repositório de Configuração de Aplicativos usando o Provedor de Kubernetes de Configuração de Aplicativo do Azure.
Criou um ConfigMap com os dados do seu repositório de Configuração de Aplicativos.
Executou o aplicativo com dados de configuração do repositório de Configuração de Aplicativos sem alterar o código do aplicativo.

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

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

Para obter mais informações sobre o Provedor de Kubernetes de Configuração de Aplicativo do Azure, consulte a referência do Provedor de Kubernetes de Configuração de Aplicativo do Azure.

Comentários

Esta página foi útil?