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

Artigo
08/08/2024

No Kubernetes, você configura pods para consumir a configuração do ConfigMaps. Ele permite que você desacople a configuração de suas imagens de contêiner, tornando seus aplicativos facilmente portáteis. O Provedor Kubernetes de Configuração de Aplicativo do Azure pode construir ConfigMaps e Segredos a partir de seus valores-chave e referências do Cofre de Chaves na Configuração de Aplicativo do Azure. Ele permite que você aproveite a Configuração do Aplicativo do Azure para o armazenamento centralizado e o gerenciamento de sua configuração sem nenhuma alteração 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 uma carga de trabalho do Serviço Kubernetes do Azure onde executa uma configuração simples de consumo de aplicativo ASP.NET Core a partir de um arquivo JSON.

Gorjeta

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

Nota

Este guia de início rápido orientará você na configuração do Provedor Kubernetes de Configuração do Aplicativo Azure. Opcionalmente, você pode usar os seguintes comandos da CLI do Desenvolvedor do Azure com o azure-appconfig-aks modelo 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, visite o repositório azure-appconfig-aks no GitHub.

azd init -t azure-appconfig-aks
azd up

Pré-requisitos

Uma loja de configuração de aplicativos. Crie uma loja.
Um Registro de Contêiner do Azure. Crie um registro.
Um cluster do Serviço Kubernetes do Azure (AKS) que recebe permissão para extrair imagens do seu Registro de Contêiner do Azure. Crie um cluster AKS.
.NET SDK 6.0 ou posterior
CLI do Azure
Área de trabalho do Docker
leme
Kubectl

Criar uma aplicação em execução no AKS

Nesta seção, você criará um aplicativo Web ASP.NET Core simples em execução no Serviço 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 do Aplicativo do Azure 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 Kubernetes de configuração do aplicativo. Você só precisa garantir que o arquivo de configuração gerado pelo provedor corresponda ao caminho do arquivo usado pelo seu aplicativo.

Criar uma aplicação

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 Pages 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 de configuração na raiz do seu projeto e adicione um arquivo de mysettings.json a ele com o seguinte conteúdo.
```
{
  "Settings": {
    "FontColor": "Black",
    "Message": "Message from the local configuration"
  }
}
```

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

Colocar a aplicação num contentor

Execute o comando dotnet publish para criar o aplicativo no modo de liberaçã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 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 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 para o Registro de Contêiner do Azure

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

Para revisar a lista de suas imagens e tags docker existentes, execute docker image ls. Nesse cenário, você deve 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 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.

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 Deployment 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 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 Web tem o seguinte aspeto:

Usar o provedor Kubernetes de configuração de aplicativo

Agora que você tem um aplicativo em execução no AKS, implantará o Provedor Kubernetes de Configuração de Aplicativo no cluster AKS em execução 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 loja de Configuração de Aplicações do Azure

Adicione os seguintes valores-chave à App Configuration Store e deixe Label e Content Type com seus valores padrão. Para obter mais informações sobre como adicionar valores-chave a uma loja usando o portal do Azure ou a CLI, vá para 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 do aplicativo

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

O App Configuration Kubernetes Provider também está disponível como uma extensão AKS. Essa integração permite a instalação e o gerenciamento contínuos por meio da CLI do Azure, modelos ARM ou modelos Bicep. A utilização da extensão AKS facilita as atualizações automáticas da versão secundária/patch, garantindo que seu sistema esteja sempre atualizado. Para obter instruções detalhadas de instalação, consulte a extensão de Configuração de Aplicativo do Azure para o Serviço Kubernetes do Azure.
Adicione um arquivo appConfigurationProvider.yaml ao diretório Deployment com o seguinte conteúdo para criar um AzureAppConfigurationProvider recurso. AzureAppConfigurationProvider é um recurso personalizado que define quais dados baixar de um repositório de Configuração de Aplicativo 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 endpoint valor do campo pelo ponto de extremidade 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 criado a partir dos dados em sua loja de configuração de aplicativos com o seguinte comportamento:
- O ConfigMap não poderá ser criado se já existir um ConfigMap com o mesmo nome no mesmo namespace.
- O ConfigMap será 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 for desinstalado.
Siga as instruções para usar a identidade da carga de trabalho para autenticar com sua loja de configuração de aplicativos. Atualize o arquivo appConfigurationProvider.yaml substituindo o serviceAccountName campo pelo nome da conta de serviço que você criou. Para obter mais informações sobre outros métodos de autenticação, consulte os exemplos na seção Autenticação .

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 garantir que o volumeMounts.mountPath corresponda ao WORKDIR especificado no seu Dockerfile e ao diretório config criado 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

Execute o seguinte comando para implantar as alterações. Substitua 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 você não vir seu aplicativo pegando os dados da sua loja de configuração de aplicativos, execute o seguinte comando 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 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 do Aplicativo do Azure tiver recuperado dados do seu repositório de Configuração de Aplicativo com êxito, a phase propriedade na seção 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 COMPLETEfor , os dados não serão baixados da sua App Configuration Store corretamente. Execute o seguinte comando para mostrar os logs do Provedor Kubernetes de Configuração do Aplicativo Azure.

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

Use os logs para solucionar problemas adicionais. Consulte a secção FAQ para problemas comuns.

FAQ

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

Você pode seguir as etapas no Guia de solução de problemas para coletar logs para obter informações detalhadas sobre erros. Aqui estão algumas causas comuns.

RESPOSTA 403: 403 Proibido: A identidade configurada não tem as permissões necessárias para acessar a App Configuration Store. Consulte a seção Autenticação para obter exemplos que correspondam à identidade que você está usando.
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-chave selecionados, mas as informações de autenticação dos Cofres 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ência do Cofre da Chave .

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

Certifique-se de especificar os seletores de chave-valor corretos para corresponder aos dados esperados. Se nenhum seletor for especificado, 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 seus valores-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 a documentação de 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 adicionais de Helm 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. Consulte o guia de instalação para obter mais informações.

Por que não consigo me autenticar com a Configuração do Aplicativo do Azure 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 do Azure 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 você precisar de tempo para migrar ao atualizar para a versão 2.0.0, poderá definir workloadIdentity.globalServiceAccountEnabled=true temporariamente durante a instalação do provedor. Observe que o suporte para usar a conta de serviço do provedor será preterido em uma versão futura.

Clean up resources (Limpar recursos)

Desinstale o App Configuration Kubernetes Provider do seu cluster AKS se quiser manter o cluster AKS.

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 um aplicativo em execução no Serviço Kubernetes do Azure (AKS).
Conectou seu cluster AKS à sua loja de configuração de aplicativos usando o provedor Kubernetes de configuração de aplicativos.
Criou um ConfigMap com dados da sua loja de configuração de aplicativos.
Executou o aplicativo com a 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 a configuração, continue para o próximo tutorial.

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

Para saber mais sobre o Provedor Kubernetes de Configuração de Aplicativo do Azure, consulte Referência do Provedor Kubernetes de Configuração de Aplicativo do Azure.

Partilhar via