Краткое руководство. Использование Конфигурация приложений Azure в Служба Azure Kubernetes

В Kubernetes можно настроить модули pod для использования данных конфигурации из ConfigMaps. Эта практика повышает переносимость приложений, так как можно отделить данные конфигурации от образов контейнеров.

Поставщик Kubernetes конфигурации приложений Azure предлагает способ создания конфигураций Kubernetes ConfigMaps и секретов из ключевых значений и ссылок Azure Key Vault, которые хранятся в конфигурации приложений. При использовании этого поставщика вы можете использовать конфигурацию приложений для централизованного хранения данных конфигурации и управления ими без внесения изменений в код приложения.

ConfigMap можно использовать в качестве переменных среды или подключенного файла. В этом кратком руководстве описано, как включить поставщик Kubernetes конфигурации приложений Azure в рабочую нагрузку AKS. Поставщик создает ConfigMap из данных в хранилище конфигурации приложений. В рабочей нагрузке вы запускаете базовое приложение ASP.NET Core в модуле pod, использующее ConfigMap в виде JSON-файла, подключенного в томе данных.

Совет

Другие способы доступа к конфигурации приложений из рабочей нагрузки, размещенной в Kubernetes, см. в статье о доступе к службе Azure Kubernetes к конфигурации приложений.

Примечание.

В этом кратком руководстве описана настройка поставщика Kubernetes конфигурации приложений Azure. При необходимости можно использовать следующие команды интерфейса командной строки разработчика Azure для подготовки ресурсов Azure и развертывания примера приложения, используемого в этом кратком руководстве. Эти команды используют azure-appconfig-aks шаблон для этой цели. Дополнительные сведения об этом шаблоне см. в репозитории GitHub azure-appconfig-aks .

azd init -t azure-appconfig-aks
azd up

Необходимые компоненты

Хранилище Конфигурация приложений. Создайте хранилище.
Экземпляр реестра контейнеров Azure. Создайте реестр.
Кластер AKS, имеющий разрешение на извлечение образов из реестра контейнеров. Создание кластера AKS.
Пакет SDK для .NET версии 8.0 или более поздней версии.
Azure CLI.
Docker Desktop.
Хелм.
kubectl.

Создание приложения, работающего в AKS

В этом разделе описано, как создать базовое веб-приложение ASP.NET Core, которое выполняется в AKS. Приложение считывает данные конфигурации из локального JSON-файла. В следующем разделе описано, как разрешить приложению использовать данные конфигурации из конфигурации приложений без изменения кода приложения.

Если у вас уже есть приложение AKS, которое считывает конфигурацию из файла, можно пропустить этот раздел и перейти к использованию поставщика Kubernetes конфигурации приложений Azure. Если пропустить этот раздел, убедитесь, что файл конфигурации, создаваемый поставщиком, соответствует пути к файлу, используемому приложением.

Создание приложения

Используйте интерфейс командной строки .NET (CLI), чтобы выполнить следующую команду. Он создает проект веб-приложения ASP.NET Core в новом каталоге MyWebApp .
```
dotnet new webapp --output MyWebApp --framework net8.0
```

В каталоге MyWebApp перейдите в каталог Pages , а затем откройте Index.cshtml. Замените содержимое следующим кодом:

@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>

Создайте каталог конфигурации в корне проекта. В каталоге конфигурации добавьте файлmysettings.json , содержащий следующее содержимое:
```
{
  "Settings": {
    "FontColor": "Black",
    "Message": "Message from the local configuration"
  }
}
```

В корневом каталоге проекта откройте Program.cs, а затем добавьте JSON-файл в источник конфигурации, вызвав 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 the existing code in Program.cs
// ... ...

Помещение приложения в контейнер

Чтобы создать приложение в режиме выпуска и создать ресурсы в опубликованном каталоге, выполните команду dotnet publish .
```
dotnet publish -c Release -o published
```
Создайте файл с именем Dockerfile в корне каталога проекта, откройте его в текстовом редакторе и введите следующее содержимое. Dockerfile — это текстовый файл, который не имеет расширения. Он используется для создания образа контейнера.
```
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app
COPY published/ ./
ENTRYPOINT ["dotnet", "MyWebApp.dll"]
```
Создайте образ контейнера с именем aspnetapp , выполнив следующую команду:
```
docker build --tag aspnetapp .
```

Отправка образа в реестр контейнеров

Чтобы войти в реестр контейнеров, выполните команду az acr login . Следующий код входит в реестр с именем myregistry. Замените это имя реестра именем реестра.
```
az acr login --name myregistry
```
Команда возвращается Login Succeeded при успешном входе.
Чтобы создать тег, вызываемого myregistry.azurecr.io/aspnetapp:v1 для aspnetapp образа, используйте команду тега Docker . Замените myregistry именем реестра.
```
docker tag aspnetapp myregistry.azurecr.io/aspnetapp:v1
```
Совет

Чтобы просмотреть список существующих образов и тегов Docker, выполните команду docker image ls. В этом сценарии выходные данные должны содержать по крайней мере два изображения: aspnetapp и myregistry.azurecr.io/aspnetapp.
Чтобы отправить образ в реестр контейнеров, используйте команду docker push . Например, следующая команда отправляет изображение в репозиторий aspnetapp с тегом v1 в реестре myregistry:
```
docker push myregistry.azurecr.io/aspnetapp:v1
```

Развертывание приложения

Создайте каталог развертывания в корневом каталоге проекта.

Чтобы определить развертывание, добавьте файл deployment.yaml со следующим содержимым в каталог развертывания . Замените значение template.spec.containers.image тега, созданного в предыдущем разделе.

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

Чтобы определить LoadBalancer службу, добавьте файл service.yaml со следующим содержимым в каталог развертывания :
```
apiVersion: v1
kind: Service
metadata:
  name: aspnetapp-demo-service
spec:
  type: LoadBalancer
  ports:
  - port: 80
  selector:
    app: aspnetapp-demo
```
Чтобы обеспечить подключение kubectl к кластеру AKS, выполните следующую команду. Он скачивает учетные данные для кластера AKS и объединяет их в контекст для кластера.
```
az aks get-credentials --name <your-AKS-instance-name> --resource-group <your-AKS-resource-group>
```
Чтобы развернуть приложение в кластере AKS и создать ресурсы, выполните следующие команды:
```
kubectl create namespace appconfig-demo
kubectl apply -f ./Deployment -n appconfig-demo
```
Чтобы получить внешний IP-адрес, предоставляемый службой LoadBalancer , выполните следующую команду:
```
kubectl get service aspnetapp-demo-service -n appconfig-demo
```
В окне браузера перейдите к IP-адресу, полученному на предыдущем шаге. Веб-страница должна выглядеть следующим образом:

Использование поставщика Kubernetes конфигурации приложений Azure

Теперь, когда у вас есть приложение, работающее в AKS, необходимо развернуть поставщик Kubernetes конфигурации приложений Azure в кластере AKS для запуска в качестве контроллера Kubernetes. Поставщик извлекает данные из хранилища Конфигурация приложений и создает ConfigMap, который используется в виде JSON-файла, подключенного в томе данных.

Настройка хранилища конфигураций приложений

Добавьте следующие ключи и значения в хранилище конфигурации приложений. Для каждого из них используйте значения по умолчанию для метки и типа контента. Дополнительные сведения о добавлении значений ключей в хранилище с помощью портала Azure или Azure CLI см. в статье "Создание значения ключа".

Ключ	Ценность
Параметры:FontColor	Зеленый
Параметры:Сообщение	Привет от Конфигурация приложений Azure

Настройка поставщика Kubernetes конфигурации приложений Azure

Установите поставщик Kubernetes конфигурации приложений Azure в кластере AKS. Поставщик можно установить как расширение AKS, так и с помощью диаграммы Helm. Расширение AKS обеспечивает простую установку и управление с помощью Azure CLI, шаблонов Azure Resource Manager (шаблонов ARM) или Bicep-файлов. Кроме того, использование расширения AKS упрощает автоматическое обновление дополнительных и исправлений, помогая обеспечить актуальность системы.
- Расширение AKS
- Диаграмма Helm
Добавьте его k8s-extension в расширения Azure CLI.
```
az extension add --name k8s-extension
```
KubernetesConfiguration Зарегистрируйте поставщика ресурсов.
```
az provider register --namespace Microsoft.KubernetesConfiguration
```
Установите расширение AKS для Конфигурация приложений. Замените cluster-name значения и resource-group значения параметров соответствующими значениями из экземпляра AKS. По умолчанию поставщик устанавливается в azappconfig-system пространстве имен.
```
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
```
Дополнительные сведения см. в разделе "Установка расширения AKS конфигурации приложений Azure".
Выполните следующую команду, чтобы получить учетные данные доступа для кластера AKS. Замените name значения и resource-group значения параметров соответствующими значениями из экземпляра AKS.
```
az aks get-credentials --name <your-AKS-instance-name> --resource-group <your-AKS-resource-group>
```
Установите диаграмму Helm.
```
helm install azureappconfiguration.kubernetesprovider \
    oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
    --namespace azappconfig-system \
    --create-namespace
```
Чтобы определить AzureAppConfigurationProvider ресурс, добавьте файл appConfigurationProvider.yaml со следующим содержимым в каталог развертывания . AzureAppConfigurationProvider — это пользовательский ресурс. Он определяет данные для скачивания из хранилища конфигурации приложений. Он также создает 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>
```
Замените значение endpoint поля конечной точкой хранилища Конфигурация приложений Azure. Перейдите к следующему шагу, чтобы обновить auth раздел с информацией о проверке подлинности.
Примечание.

AzureAppConfigurationProvider является декларативным объектом API. Он определяет требуемое состояние конфигурации конфигурации, созданного из данных в хранилище конфигурации приложений. Определение требуемого состояния указывает следующее поведение:
- Создание ConfigMap завершается ошибкой, если ConfigMap с тем же именем уже существует в том же пространстве имен.
- ConfigMap сбрасывается на основе представленных данных в хранилище конфигурации приложений, если он удален или изменен другими средствами.
- ConfigMap удаляется, если поставщик Kubernetes конфигурации приложений Azure удаляется.
Чтобы пройти проверку подлинности в хранилище конфигурации приложений, следуйте инструкциям по использованию удостоверения рабочей нагрузки. Обновите файл appConfigurationProvider.yaml , заменив serviceAccountName поле именем учетной записи службы, созданной при выполнении инструкций. Дополнительные сведения о других методах проверки подлинности см. в примерах проверки подлинности.
Как показано в следующем коде, обновите файл deployment.yaml в каталоге развертывания , чтобы использовать ConfigMap configmap-created-by-appconfig-provider в качестве подключенного тома данных. Важно, чтобы volumeMounts.mountPath значение соответствовало значению, указанному WORKDIR в Dockerfile, и созданному ранее каталогу конфигурации . Кроме того, убедитесь, что значение template.spec.containers.image соответствует имени созданного ранее образа.
```
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
```
Чтобы развернуть изменения, выполните следующую команду. Обновите пространство имен, если вы используете существующее приложение AKS.
```
kubectl apply -f ./Deployment -n appconfig-demo
```
Обновите окно браузера. На странице отображается обновленное содержимое.

Устранение неполадок

Если приложение не считывает данные из хранилища конфигурации приложений, выполните следующую команду, чтобы убедиться, что ConfigMap создан правильно:

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

Если ConfigMap не создан, выполните следующую команду, чтобы получить состояние извлечения данных:

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

Если поставщик Kubernetes конфигурации приложений Azure успешно извлекает данные из хранилища конфигурации приложений, phase свойство в status разделе выходных данных должно быть Complete, как показано в следующем примере:

$ 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

Если свойство этапа не COMPLETEявляется, данные не скачиваются из хранилища конфигурации приложений должным образом. Чтобы получить доступ к журналам поставщика Kubernetes конфигурации приложений Azure, выполните следующую команду:

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

Используйте журналы для дальнейшего устранения неполадок. Сведения о решениях распространенных проблем см. в разделе часто задаваемых вопросов.

Вопросы и ответы

Почему не создается ConfigMap или Secret?

Чтобы собрать журналы, содержащие подробные сведения об ошибках, выполните действия, описанные в разделе "Устранение неполадок". Ниже приведены некоторые распространенные причины этой проблемы:

ОТВЕТ 403: 403 Запрещено: настроенное удостоверение не имеет необходимых разрешений для доступа к хранилищу Конфигурация приложений. Примеры, соответствующие используемому удостоверению, см. в разделе "Проверка подлинности".
Ссылка на Key Vault найдена в конфигурации приложений, но "spec.secret" не настроена: одна или несколько ссылок Key Vault включены в выбранные значения ключей, но сведения проверки подлинности для Key Vault не указаны. Чтобы обеспечить целостность конфигурации, вся конфигурация не загружается. spec.secret Настройте раздел для предоставления необходимых сведений о проверке подлинности. Примеры и дополнительные сведения см. в справочниках по Key Vault .

Почему созданный ConfigMap не содержит ожидаемые данные?

Убедитесь, что селекторы "ключ-значение" соответствуют ожидаемым данным. Если вы не задаете селекторы, все значения ключей без метки скачиваются из хранилища конфигурации приложений. При использовании фильтра ключей убедитесь, что он соответствует префиксу ожидаемых значений ключей. Если значения ключей имеют метки, обязательно укажите фильтр меток в селекторах. Дополнительные примеры см. в разделе "Выбор "Ключ-значение".

Как настроить установку поставщика Kubernetes конфигурации приложений Azure?

Вы можете настроить установку, указав дополнительные значения Helm при установке поставщика Kubernetes конфигурации приложений Azure. Например, можно задать уровень журнала, настроить поставщика для запуска на определенном узле или отключить удостоверение рабочей нагрузки. Дополнительные сведения см. в разделе "Установка".

Как активировать обновление конфигурации и секрета по запросу?

Вы можете настроить данные для автоматического обновления. Но иногда может потребоваться активировать обновление по запросу, чтобы получить последние данные из Конфигурации приложений и Key Vault. Чтобы активировать обновление, можно изменить metadata.annotations раздел AzureAppConfigurationProvider. Затем поставщик Kubernetes обновляет ConfigMap и Secret с последними данными из хранилища конфигурации приложений и Key Vault. Пример см. в статье об обновлении по запросу.

Не рекомендуется удалять или изменять конфигурацию и секрет, созданные поставщиком Kubernetes. Новые создаются из последних данных, но эта ситуация может привести к простою приложений во время сбоев.

Почему не удается выполнить проверку подлинности с помощью удостоверения рабочей нагрузки после обновления поставщика до версии 2.0.0?

Начиная с версии 2.0.0, для проверки подлинности с помощью удостоверения рабочей нагрузки требуется учетная запись службы, предоставляемая пользователем. Это изменение повышает безопасность с помощью изоляции пространства имен. Ранее учетная запись службы поставщика Kubernetes использовалась для всех пространств имен. Обновленные инструкции см. в документации по использованию удостоверения рабочей нагрузки. Если вам нужно время перенести при обновлении до версии 2.0.0,0, можно временно использовать workloadIdentity.globalServiceAccountEnabled=true параметр во время установки поставщика. Обратите внимание, что поддержка использования учетной записи службы поставщика запланирована на отмену в будущем выпуске.

Очистка ресурсов

Если вы хотите удалить поставщика Kubernetes конфигурации приложений Azure, но сохранить кластер AKS, используйте следующую команду, чтобы удалить поставщика:

Расширение AKS
Диаграмма 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

Если вы не планируете в дальнейшем использовать ресурсы, созданные при работе с этой статьей, удалите созданную группу ресурсов, чтобы избежать расходов.

Внимание

Удаление группы ресурсов — процесс необратимый. Группа ресурсов и все содержащиеся в ней ресурсы удаляются без возможности восстановления. Будьте внимательны, чтобы случайно не удалить не те ресурсы или группу ресурсов. Если ресурсы для работы с этой статьей созданы в группе ресурсов, которая содержит другие нужные ресурсы, удалите каждый ресурс отдельно в соответствующей области ресурса, чтобы не удалять группу ресурсов.

Войдите на портал Azure и выберитеГруппы ресурсов.
Введите имя группы ресурсов в поле Фильтровать по имени.
В списке результатов выберите имя группы ресурсов, чтобы просмотреть общие сведения.
Выберите команду Удалить группу ресурсов.
Подтвердите операцию удаления группы ресурсов. Введите имя группы ресурсов, которую необходимо удалить, и нажмите Удалить.

Через некоторое время группа ресурсов и все ее ресурсы будут удалены.

Примечание.

Если вы используете интерфейс командной строки разработчика Azure для настройки ресурсов, можно выполнить azd down команду, чтобы удалить все ресурсы, созданные шаблоном azure-appconfig-aks .

Следующие шаги

В этом кратком руководстве вы:

Создано приложение, работающее в AKS.
Подключите кластер AKS к хранилищу конфигурации приложений с помощью поставщика Kubernetes конфигурации приложений Azure.
Создайте ConfigMap с данными из хранилища Конфигурация приложений.
Запустите приложение с данными конфигурации из хранилища конфигурации приложений, не изменяя код приложения.

Чтобы узнать, как обновить рабочие нагрузки AKS для динамического обновления данных конфигурации, перейдите к следующему руководству.

Использование динамической конфигурации в Служба Azure Kubernetes

Дополнительные сведения о поставщике Kubernetes конфигурации приложений Azure см. в справочнике по поставщику Kubernetes конфигурации приложений Azure.

Обратная связь

Была ли эта страница полезна?

Last updated on 2025-09-02