クイックスタート: Azure Kubernetes Service で Azure App Configuration を使用する

Kubernetes では、ConfigMaps から構成データを使用するようにポッドを設定できます。この方法では、コンテナーイメージから構成データを切り離すことができるため、アプリケーションの移植性が向上します。

Azure App Configuration Kubernetes Provider には、App Configuration に格納されているキー値と Azure Key Vault 参照から Kubernetes ConfigMaps とシークレットを構築する方法が用意されています。このプロバイダーを使用すると、App Configuration を使用して、アプリケーションコードを変更することなく、構成データを一元的に格納および管理できます。

ConfigMap は、環境変数またはマウントされたファイルとして使用できます。このクイックスタートでは、Azure App Configuration Kubernetes Provider を AKS ワークロードに組み込みます。プロバイダーは、App Configuration ストア内のデータから ConfigMap を作成します。ワークロードでは、ConfigMap をデータボリュームにマウントされた JSON ファイルとして使用するポッドで、基本的な ASP.NET Core アプリを実行します。

ヒント

Kubernetes でホストされているワークロードから App Configuration にアクセスするその他の方法については、 App Configuration への Azure Kubernetes Service アクセスに関するページを参照してください。

注

このクイックスタートでは、Azure App Configuration Kubernetes Provider を設定する手順について説明します。必要に応じて、次の Azure Developer CLI コマンドを使用して Azure リソースをプロビジョニングし、このクイックスタートで使用するサンプルアプリケーションをデプロイできます。これらのコマンドでは、この目的に azure-appconfig-aks テンプレートを使用します。このテンプレートの詳細については、 azure-appconfig-aks GitHub リポジトリを参照してください。

azd init -t azure-appconfig-aks
azd up

前提条件

App Configuration ストア。ストアを作成する。
Azure Container Registry のインスタンス。レジストリを作成します。
コンテナーレジストリからイメージをプルするアクセス許可を持つ AKS クラスター。 AKS クラスターを作成する。
.NET SDK 8.0 以降。
Azure CLI。
Docker Desktop。
Helm。
kubectl。

AKS で実行されるアプリケーションを作成する

このセクションでは、AKS で実行される基本的な ASP.NET Core Web アプリケーションを作成します。アプリケーションは、ローカル JSON ファイルから構成データを読み取ります。次のセクションでは、アプリケーションコードを変更せずに、アプリケーションが App Configuration から構成データを使用できるようにします。

ファイルから構成を読み取る AKS アプリケーションが既にある場合は、このセクションをスキップして、 Azure App Configuration Kubernetes プロバイダーの使用に進むことができます。このセクションをスキップする場合は、プロバイダーによって生成される構成ファイルが、アプリケーションで使用されるファイルパスと一致していることを確認します。

アプリケーションの作成

.NET コマンドラインインターフェイス (CLI) を使用して、次のコマンドを実行します。新しい MyWebApp ディレクトリに ASP.NET Core Web アプリプロジェクトを作成します。
```
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>

プロジェクトのルートに構成ディレクトリを作成します。 config ディレクトリに、次の内容を含む mysettings.json ファイルを追加します。
```
{
  "Settings": {
    "FontColor": "Black",
    "Message": "Message from the local configuration"
  }
}
```

プロジェクトのルートディレクトリ でProgram.csを開き、 AddJsonFile メソッドを呼び出して JSON ファイルを構成ソースに追加します。

// 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 を返します。
aspnetapp イメージのmyregistry.azurecr.io/aspnetapp:v1という名前のタグを作成するには、docker tag コマンドを使用します。 myregistryをレジストリの名前に置き換えます。
```
docker tag aspnetapp myregistry.azurecr.io/aspnetapp:v1
```
ヒント

既存の Docker イメージとタグの一覧を確認するには、 docker image ls実行します。このシナリオでは、出力に少なくとも 2 つの画像 ( aspnetapp と myregistry.azurecr.io/aspnetapp) が一覧表示されます。
イメージをコンテナーレジストリにアップロードするには、 docker push コマンドを使用します。たとえば、次のコマンドは、レジストリ myregistryの下にタグ v1を持つ aspnetapp という名前のリポジトリにイメージをプッシュします。
```
docker push myregistry.azurecr.io/aspnetapp:v1
```

アプリケーションの配置

ご自分のプロジェクトのルートディレクトリに、Deployment ディレクトリを作成します。

デプロイを定義するには、次の内容を含む deployment.yaml ファイルを Deployment ディレクトリに追加します。 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
```
LoadBalancer サービスによって公開されている外部 IP アドレスを取得するには、次のコマンドを実行します。
```
kubectl get service aspnetapp-demo-service -n appconfig-demo
```
ブラウザーウィンドウで、前の手順で取得した IP アドレスに移動します。 Web ページは次のスクリーンショットのようになります。

Azure App Configuration Kubernetes プロバイダーを使用する

これで AKS でアプリケーションが実行されたので、次の手順は、Kubernetes コントローラーとして実行するために Azure App Configuration Kubernetes Provider を AKS クラスターにデプロイすることです。プロバイダーは App Configuration ストアからデータを取得し、データボリュームにマウントされた JSON ファイルとして使用可能な ConfigMap を作成します。

App Configuration ストアを設定する

App Configuration ストアに次のキーと値を追加します。それぞれに、 ラベル と コンテンツタイプの既定値を使用します。 Azure portal または Azure CLI を使用してストアにキー値を追加する方法の詳細については、「キー値の作成」を参照してください。

キー	価値
設定:フォントカラー	緑
設定:メッセージ	"Azure App Configuration からの挨拶"

Azure App Configuration Kubernetes プロバイダーを設定する

AKS クラスターに Azure App Configuration Kubernetes プロバイダーをインストールします。プロバイダーは、AKS 拡張機能として、または Helm チャートを使用してインストールできます。 AKS 拡張機能は、Azure CLI、Azure Resource Manager テンプレート (ARM テンプレート)、または Bicep ファイルを使用して、シームレスなインストールと管理を提供します。また、AKS 拡張機能を使用すると、マイナーバージョンとパッチバージョンの自動更新が容易になり、システムを最新の状態に保つことができます。
- AKS 拡張機能
- Helm チャート
Azure CLI 拡張機能に k8s-extension を追加します。
```
az extension add --name k8s-extension
```
KubernetesConfiguration リソースプロバイダーを登録します。
```
az provider register --namespace Microsoft.KubernetesConfiguration
```
App Configuration の 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
```
詳細については、「 Azure App Configuration AKS 拡張機能のインストール」を参照してください。
次のコマンドを実行して、ご自分の 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 はカスタムリソースです。 App Configuration ストアからダウンロードするデータを定義します。また、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 App Configuration ストアのエンドポイントに置き換えます。次の手順に進み、自分の認証情報で auth セクションを更新します。
注

AzureAppConfigurationProvider は宣言型 API オブジェクトです。 App Configuration ストア内のデータから作成される ConfigMap の目的の状態を定義します。目的の状態の定義は、次の動作を指定します。
- 同じ名前の ConfigMap が同じ名前空間に既に存在する場合、ConfigMap の作成は失敗します。
- ConfigMap が他の方法で削除または変更された場合、App Configuration ストア内の現在のデータに基づいてリセットされます。
- Azure App Configuration Kubernetes Provider がアンインストールされると、ConfigMap が削除されます。
App Configuration ストアで認証するには、ワークロード ID を使用する手順に従います。 serviceAccountName フィールドを、指示に従って作成したサービスアカウントの名前に置き換えて、appConfigurationProvider.yaml ファイルを更新します。その他の認証方法の詳細については、「認証」の例を参照してください。

次のコードに示すように、ConfigMap configmap-created-by-appconfig-providerをマウントされたデータボリュームとして使用するように、Deployment ディレクトリの deployment.yaml ファイルを更新します。 volumeMounts.mountPath値は、Dockerfile で指定したWORKDIR値と、前に作成した config ディレクトリと一致することが重要です。また、 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
```
ブラウザーを更新します。更新されたコンテンツがページに表示されます。

トラブルシューティング

アプリケーションが App Configuration ストアからデータを読み取らない場合は、次のコマンドを実行して、ConfigMap が正しく作成されていることを確認します。

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

ConfigMap が作成されていない場合は、次のコマンドを実行してデータ取得の状態を取得します。

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

Azure App Configuration Kubernetes Provider が App Configuration ストアからデータを正常に取得した場合、次の例に示すように、出力のstatus セクションのphase プロパティが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

phase プロパティが COMPLETEされていない場合、データは App Configuration ストアから正しくダウンロードされません。 Azure App Configuration Kubernetes Provider のログにアクセスするには、次のコマンドを実行します。

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

このログを使用して、詳細なトラブルシューティングを行います。一般的な問題の解決策については、 FAQ を参照してください。

FAQ

ConfigMap またはシークレットが生成されないのはなぜですか?

詳細なエラー情報を含むログを収集するには、「トラブルシューティング」の手順に従います。この問題の一般的な原因を次に示します。

RESPONSE 403: 403 Forbidden: 構成された ID には、App Configuration ストアにアクセスするのに必要なアクセス許可がありません。使用している ID に一致する例については、「認証」を参照してください。
Key Vault 参照は App Configuration で見つかりましたが、'spec.secret' は構成されていません。選択したキー値には 1 つ以上の Key Vault 参照が含まれていますが、Key Vault の認証情報は提供されていません。構成の整合性を維持するために、構成全体の読み込みに失敗します。 spec.secret セクションを構成して、必要な認証情報を指定します。例と詳細については、「 Key Vault の参照」を参照してください。

生成された ConfigMap に予期されるデータが含まれないのはなぜですか?

指定するキーと値のセレクターが予想されるデータと一致していることを確認します。セレクターを指定しない場合は、ラベルのないすべてのキー値が App Configuration ストアからダウンロードされます。キーフィルターを使用する場合は、予想されるキー値のプレフィックスと一致することを確認します。キー値にラベルがある場合は、セレクターでラベルフィルターを指定していることを確認してください。その他の例については、「キーと値の選択」を参照してください。

Azure App Configuration Kubernetes Provider のインストールをカスタマイズするにはどうすればよいですか?

Azure App Configuration Kubernetes Provider をインストールするときに追加の Helm 値を指定することで、インストールをカスタマイズできます。たとえば、ログレベルを設定したり、特定のノードで実行するようにプロバイダーを構成したり、ワークロード ID を無効にしたりできます。詳細については、「インストール」を参照してください。

ConfigMap とシークレットのオンデマンド更新をトリガーするにはどうすればよいですか?

自動的に更新されるようにデータを構成できます。ただし、オンデマンドの更新をトリガーして、App Configuration と Key Vault から最新のデータを取得したい場合があります。更新をトリガーするには、AzureAppConfigurationProviderの metadata.annotations セクションを変更します。その後、Kubernetes プロバイダーは、App Configuration ストアと Key Vault の最新データで ConfigMap とシークレットを更新します。例については、「オンデマンド更新」を参照してください。

Kubernetes プロバイダーによって生成された ConfigMap とシークレットを削除または変更することはお勧めしません。最新のデータから新しいデータが生成されますが、この状況により、障害発生時にアプリケーションのダウンタイムが発生する可能性があります。

プロバイダーをバージョン 2.0.0 にアップグレードした後、ワークロード ID を使用して App Configuration で認証できないのはなぜですか?

バージョン 2.0.0 以降では、ワークロード ID を使用して App Configuration で認証するために、ユーザー指定のサービスアカウントが必要です。この変更により、名前空間の分離によってセキュリティが強化されます。以前は、Kubernetes プロバイダーのサービスアカウントがすべての名前空間に使用されていました。更新された手順については、ワークロード ID の使用に関するドキュメントを参照してください。バージョン 2.0.0 にアップグレードするときに移行する時間が必要な場合は、プロバイダーのインストール時に workloadIdentity.globalServiceAccountEnabled=true 設定を一時的に使用できます。プロバイダーのサービスアカウントの使用のサポートは、今後のリリースで非推奨となる予定であることに注意してください。

リソースをクリーンアップする

Azure App Configuration Kubernetes Provider をアンインストールし、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 portal にサインインし、 [リソースグループ] を選択します。
[名前でフィルター] ボックスにリソースグループの名前を入力します。
結果一覧でリソースグループ名を選択し、概要を表示します。
[リソースグループの削除] を選択します。
リソースグループの削除の確認を求めるメッセージが表示されます。確認のためにリソースグループの名前を入力し、 [削除] を選択します。

しばらくすると、リソースグループとそのすべてのリソースが削除されます。

注

Azure Developer CLI を使用してリソースを設定する場合は、azd down コマンドを実行して、azure-appconfig-aks テンプレートによって作成されたすべてのリソースを削除できます。

次のステップ

このクイックスタートでは次の作業を行います。

AKS で実行されているアプリケーションを作成しました。
Azure App Configuration Kubernetes プロバイダーを使用して、AKS クラスターを App Configuration ストアに接続しました。
App Configuration ストアのデータを含む ConfigMap を作成しました。
アプリケーションコードを変更せずに、App Configuration ストアの構成データを使用してアプリケーションを実行しました。

AKS ワークロードを更新して構成データを動的に更新する方法については、次のチュートリアルに進んでください。

Azure Kubernetes Service で動的構成を使用する

Azure App Configuration Kubernetes プロバイダーの詳細については、 Azure App Configuration Kubernetes プロバイダーリファレンスを参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-09-02