Guia de início rápido: usar a Configuração do Aplicativo do Azure no Serviço Kubernetes do Azure

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

O Provedor Kubernetes de Configuração de Aplicativo do Azure oferece uma maneira de construir ConfigMaps e Segredos do Kubernetes a partir de valores-chave e referências do Cofre de Chaves do Azure armazenadas na Configuração do Aplicativo. Ao usar esse provedor, você pode usar a Configuração do Aplicativo 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ê incorpora o Provedor Kubernetes de Configuração de Aplicativo do Azure em sua carga de trabalho AKS. O provedor cria um ConfigMap a partir de dados em sua loja 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.

Gorjeta

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

Nota

Este guia de início rápido orienta você pela configuração do Provedor Kubernetes de Configuração do Aplicativo 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 usado por este início rápido. Esses comandos usam o azure-appconfig-aks modelo para essa finalidade. Para obter mais informações sobre esse modelo, consulte o repositório azure-appconfig-aks GitHub.

azd init -t azure-appconfig-aks
azd up

Pré-requisitos

Uma loja de configuração de aplicativos. Crie uma loja.
Uma instância do Registro de Contêiner do Azure. Crie um registro.
Um cluster AKS que tem permissão para extrair imagens do seu registro de contêiner. Crie um cluster AKS.
.NET SDK 8.0 ou posterior.
A CLI do Azure.
Área de trabalho do Docker.
Leme.
Kubectl.

Criar um aplicativo que seja executado no AKS

Nesta seção, você cria 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ê habilita o aplicativo para consumir dados de configuração da Configuração do aplicativo sem alterar o código do aplicativo.

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

Criar uma aplicação

Use a interface de linha de comando (CLI) do .NET para executar o seguinte comando. 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 Pages 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 seu projeto. No diretório config , adicione um arquivo mysettings.json que contenha 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 a aplicação num contentor

Para criar o aplicativo no modo de liberação e criar os ativos no diretório publicado , execute o comando dotnet publishing .
```
dotnet publish -c Release -o published
```
Crie um arquivo chamado Dockerfile na raiz do diretório do projeto, abra-o em um editor de texto e insira o seguinte conteúdo. Um Dockerfile é um arquivo de texto que não tem uma extensão. Você o 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 .
```

Envie a imagem para o Registro de contêiner

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

Para revisar a lista de suas imagens e tags 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 do contêiner, use o comando docker push . Por exemplo, o comando a seguir envia a imagem para um repositório nomeado aspnetapp com tag v1 no registro myregistry:
```
docker push myregistry.azurecr.io/aspnetapp:v1
```

Implementar a aplicação

Crie um diretório de 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 Deployment . Substitua o valor de pela tag que template.spec.containers.image 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 possibilitar que o kubectl se conecte ao seu cluster AKS, execute o seguinte comando. Ele baixa as credenciais do cluster 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 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 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 Kubernetes de Configuração de Aplicativo do Azure em seu cluster AKS para ser executado como um controlador Kubernetes. O provedor recupera dados de sua loja de configuração de aplicativos e cria um ConfigMap, que é consumível como um arquivo JSON montado em um volume de dados.

Configurar a App Configuration Store

Adicione as seguintes chaves e valores à App Configuration store. Para cada um, use valores padrão para Rótulo e Tipo de conteúdo. Para obter mais informações sobre como adicionar valores-chave 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 do Aplicativo do Azure

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

Instale o Provedor Kubernetes de Configuração de Aplicativo do Azure em seu cluster AKS. Você pode instalar o provedor como uma extensão AKS ou usando um gráfico Helm. A extensão AKS fornece instalação e gerenciamento contínuos por meio da CLI do Azure, modelos do Azure Resource Manager (modelos ARM) ou arquivos Bicep. Além disso, o uso da extensão AKS facilita as atualizações automáticas de versões secundárias e patches, ajudando a garantir que seu sistema permaneça atualizado.
- Extensão AKS
- Gráfico de leme
Adicione o k8s-extension às suas 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 AKS para Configuração de Aplicativos. Substitua os valores e resource-group parâmetro cluster-name pelos valores correspondentes da sua instância 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 de Configuração de Aplicativo do Azure.
Execute o seguinte comando para obter credenciais de acesso para o cluster AKS. Substitua os valores e resource-group parâmetro name pelos valores correspondentes da sua instância AKS.
```
az aks get-credentials --name <your-AKS-instance-name> --resource-group <your-AKS-resource-group>
```
Instale o gráfico 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 Deployment . AzureAppConfigurationProvider é um recurso personalizado. Ele define os dados a serem baixados de uma loja 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 endpoint da sua loja de Configuração de Aplicativos do Azure. Prossiga para a próxima etapa para atualizar a auth seção com suas informações de autenticação.
Nota

AzureAppConfigurationProvider é um objeto de API declarativo. Ele define o estado desejado do ConfigMap que é criado a partir dos dados em sua loja de configuração de aplicativos. A definição do estado desejado especifica o seguinte comportamento:
- A criação do ConfigMap falhará se já existir um ConfigMap com o mesmo nome no mesmo namespace.
- O ConfigMap é redefinido com base nos dados presentes na sua App Configuration Store se for excluído ou modificado por qualquer outro meio.
- O ConfigMap será excluído se o Provedor Kubernetes de Configuração do Aplicativo do Azure for desinstalado.
Para autenticar com sua loja 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 criada ao seguir as instruções. Para obter mais informações sobre outros métodos de autenticação, consulte os exemplos em Autenticação.

Conforme mostrado no código a seguir, atualize o arquivo deployment.yaml no diretório Deployment 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 no Dockerfile e no diretório config criado anteriormente. Além disso, verifique se o valor de template.spec.containers.image corresponde ao nome da imagem criada 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 seguinte comando. Atualize o namespace se você estiver usando seu aplicativo AKS existente.
```
kubectl apply -f ./Deployment -n appconfig-demo
```
Atualize o browser. A página mostra conteúdo atualizado.

Resolução de Problemas

Se o seu aplicativo não ler os dados da sua loja 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 Kubernetes de Configuração de Aplicativo do Azure recuperar dados do seu repositório de Configuração de Aplicativo com êxito, a phasestatus propriedade na 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 phase não COMPLETEfor , os dados não serão baixados da sua App Configuration Store corretamente. Para acessar os logs do Provedor 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.

FAQ

Por que o ConfigMap ou o Secret não estão sendo gerados?

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

RESPOSTA 403: 403 Proibido: A identidade configurada não tem as permissões necessárias para acessar a App Configuration Store. Para obter exemplos que correspondam à identidade que você está usando, consulte Autenticação.
Uma referência do Cofre da Chave é encontrada na Configuração do Aplicativo, mas 'spec.secret' não foi configurado: uma ou mais referências do Cofre da Chave são incluídas nos valores de chave selecionados, mas as informações de autenticação do Cofre da Chave não são fornecidas. Para manter a integridade da configuração, toda a configuração falha ao carregar. Configure a spec.secret seção para fornecer as informações de autenticação necessárias. Para obter exemplos e mais informações, consulte Referências do Cofre de Chaves .

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

Certifique-se de que os seletores de chave-valor especificados correspondam aos dados esperados. Se você não especificar nenhum seletor, todos os valores-chave sem um rótulo serão baixados da sua loja 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, certifique-se de especificar o filtro de rótulos nos seletores. Para obter mais exemplos, consulte Seleção de chave-valor.

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

Você pode personalizar a instalação fornecendo valores Helm extras ao instalar o Provedor 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 acionar uma atualização sob demanda do ConfigMap e do Secret?

Você pode configurar os dados para atualizar automaticamente. Mas há momentos em que você pode querer acionar uma atualização sob demanda para obter os dados mais recentes da Configuração do Aplicativo e do Cofre de Chaves. Para acionar uma atualização, você pode modificar a metadata.annotations seção do AzureAppConfigurationProvider. Em seguida, o provedor do Kubernetes atualiza o ConfigMap e o Secret com os dados mais recentes da sua loja de Configuração de Aplicativos e do Cofre de Chaves. Para obter um exemplo, consulte Atualização sob demanda.

Não recomendamos excluir ou modificar o ConfigMap e o Secret gerados pelo provedor Kubernetes. Novos são gerados a partir dos dados mais recentes, mas essa situação pode causar tempo de inatividade para seus aplicativos durante falhas.

Por que não consigo me autenticar com a Configuração do Aplicativo 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 do Aplicativo usando a identidade da carga de trabalho. Essa alteração aumenta a segurança por meio do isolamento de namespace. Anteriormente, a conta de serviço de um provedor do Kubernetes era usada para todos os namespaces. Para obter instruções atualizadas, consulte a documentação sobre como usar a identidade da carga de trabalho. Se precisar de tempo para migrar ao atualizar para a versão 2.0.0, você pode usar temporariamente a configuração durante a instalação do workloadIdentity.globalServiceAccountEnabled=true provedor. Observe que o suporte para usar a conta de serviço do provedor está agendado para descontinuação em uma versão futura.

Limpar recursos

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

Extensão AKS
Gráfico de leme

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 quiser continuar a utilizar os recursos criados neste artigo, elimine o grupo de recursos que criou aqui para evitar cobranças.

Importante

A eliminação de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos nele contidos são excluídos permanentemente. Certifique-se de não excluir acidentalmente o grupo de recursos ou recursos errados. Se você criou os recursos para este artigo dentro de um grupo de recursos que contém outros recursos que deseja manter, exclua cada recurso individualmente de seu respetivo painel em vez de excluir o grupo de recursos.

Entre no portal do Azure e selecione Grupos de recursos.
Na caixa Filtrar por nome, introduza o nome do seu grupo de recursos.
Na lista de resultados, selecione o nome do grupo de recursos para ver uma visão geral.
Selecione Eliminar grupo de recursos.
É-lhe pedido que confirme a eliminação do grupo de recursos. Insira o nome do grupo de recursos a ser confirmado e selecione Excluir.

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

Nota

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

Próximos passos

Neste início rápido, irá:

Criou uma aplicação em execução no AKS.
Conectou seu cluster AKS à sua loja de Configuração de Aplicativos usando o Provedor Kubernetes de Configuração de Aplicativo do Azure.
Criou um ConfigMap com dados da sua loja de configuração de aplicativos.
Executou o aplicativo com dados de configuração da sua loja 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 os dados de configuração, continue para o próximo tutorial.

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

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

Feedback

Esta página foi útil?

Last updated on 2025-09-02