Azure Kubernetes Configuration Extensions SDKs 1.0.0解説：JavaScript・Pythonで実装と移行が楽になるポイント

Azure Kubernetes Configuration Extensions SDKs は、Kubernetes クラスター拡張機能を JavaScript や Python から作成・更新・一覧取得・削除できる管理 SDK です。今回のポイントは、JavaScript と Python の両方で 1.0.0 が公開され、ベータ版前提だった実装を本番運用に近い形へ移しやすくなったことです。

特に、DevOps チームや platform engineer にとっては、クラスター拡張機能の展開を「手作業」から「コード化された運用」に寄せやすくなります。たとえば、Azure Monitor 系の拡張機能を複数クラスターへそろえて導入する、設定値を環境ごとに切り替える、既存拡張機能のアップグレード方針を一括で変更する、といった作業を SDK 経由で自動化できます。

2026年4月21日時点では、JavaScript 向け @azure/arm-kubernetesconfiguration-extensions_1.0.0 が GitHub Releases に公開され、Python 向け azure-mgmt-kubernetesconfiguration-extensions_1.0.0 も公開されています。Python パッケージは PyPI 上で 1.0.0 が最新バージョンとして扱われ、Production/Stable の分類も付いています。(GitHub)

Azure Kubernetes Configuration Extensions SDKs 1.0.0で何が変わるのか

Azure Kubernetes Configuration Extensions SDKs は、Azure Resource Manager、つまり ARM 経由で Kubernetes クラスター拡張機能リソースを扱うための SDK です。REST API では Microsoft.KubernetesConfiguration/extensions リソースに対して Create、Delete、Get、List、Update を実行できます。API バージョンは 2025-03-01 が公開されており、クラスター拡張機能の作成、削除、取得、一覧表示、パッチ更新に対応しています。(Microsoft Learn)

今回の 1.0.0 は「新しい便利機能が突然増えた」というより、ベータ版を前提にした試験実装から、本番コードへ組み込みやすくなる節目と見るのが実務的です。

観点	1.0.0で楽になること	実務での効果
SDK選定	JavaScript と Python の両方で安定版として扱いやすい	Node.js のデプロイツール、Python の運用スクリプトのどちらでも採用しやすい
操作の標準化	create / update / get / list / delete の形で拡張機能を操作できる	複数クラスターへの横展開、棚卸し、更新処理をコード化しやすい
移行判断	Python では 1.0.0b 系からの変更点が明示されている	ベータ版から移行するときに確認すべき差分を洗い出しやすい
自動化	LRO、認証、ページングなどを SDK の型とメソッドで扱える	REST API を手書きするより保守しやすい
監視・運用	extensionState、managementDetails、additionalDetails などの情報を参照しやすい	インストール後の状態確認やトラブルシュートを自動化しやすい

Python の 1.0.0 では、AKSIdentityType に WORKLOAD が追加され、ExtensionProperties に auto_upgrade_mode、management_details、additional_details、extension_state などが追加されています。また AutoUpgradeMode、ManagementDetails、AdditionalDetails といったモデルも追加されています。(PyPI)

そもそも何を管理するSDKなのか

この SDK が扱うのは、Kubernetes クラスターそのものではなく、Kubernetes クラスターに追加する拡張機能リソースです。

たとえば、監視、GitOps、セキュリティ、Marketplace 経由のアドオンなど、Azure 上の Kubernetes クラスターにインストールされる拡張機能を ARM リソースとして作成・更新します。REST API の Create 操作では、extensionType、autoUpgradeMode、autoUpgradeMinorVersion、releaseTrain、scope、configurationSettings、configurationProtectedSettings などを指定できます。(Microsoft Learn)

SDK化すると何がうれしいのか

手作業で拡張機能を入れるだけなら、ポータルや CLI でも足ります。しかし、次のようなケースでは SDK のほうが向いています。

利用シーン	SDKが向いている理由
複数クラスターへ同じ拡張機能を展開する	クラスター一覧を読み、同じ設定をループで適用できる
環境ごとに設定値を変える	dev / staging / prod の設定をコードで分岐できる
拡張機能の状態を定期チェックする	list や get で状態を取得し、異常時だけ通知できる
CI/CDに組み込む	アプリのデプロイ前に必要な拡張機能があるか検査できる
IaCだけでは扱いづらい運用変更をしたい	バージョン固定、アップグレード方針、設定変更を条件付きで実行できる

重要なのは、SDK を「一度だけ作成するための道具」としてではなく、クラスター拡張機能のライフサイクルを管理する道具として見ることです。

実装前に決めておくべき4つの値

Azure Kubernetes Configuration Extensions SDKs を使う前に、次の値を整理しておくと実装がスムーズです。

項目	例	間違えやすいポイント
resourceGroupName	rg-platform-prod	クラスターが存在するリソースグループを指定する
clusterRp	Microsoft.ContainerService / Microsoft.Kubernetes	AKS と Azure Arc-enabled Kubernetes で異なる
clusterResourceName	managedClusters / connectedClusters	clusterRp とセットで考える
clusterName	aks-prod-01	表示名ではなく Azure リソース名を使う
extensionName	ClusterMonitor	拡張機能リソースとしての名前
extensionType	azuremonitor-containers など	パブリッシャーが登録している拡張機能タイプである必要がある

REST API のパラメーター説明では、clusterRp の例として Microsoft.ContainerService、Microsoft.Kubernetes、Microsoft.HybridContainerService が示され、clusterResourceName の例として managedClusters、connectedClusters、provisionedClusters、appliances が挙げられています。(Microsoft Learn)

実務では、この組み合わせを環境変数や設定ファイルに逃がしておくのがおすすめです。コード内に直書きすると、AKS 用のスクリプトを Arc 対応 Kubernetes に流用したときに失敗しやすくなります。

自動アップグレード方針は最初に決める

1.0.0で特に見ておきたいのが autoUpgradeMode です。REST API の定義では、autoUpgradeMode の既定値は compatible で、値として none、patch、compatible が示されています。また、特定バージョンに固定する version を使う場合は、autoUpgradeMinorVersion を false にする必要があります。(Microsoft Learn)

方針	指定例	向いているケース	注意点
自動更新しない	autoUpgradeMode: "none"	厳格な検証後にだけ更新したい本番環境	セキュリティ修正や不具合修正の追随が遅れる
パッチ更新だけ許可	autoUpgradeMode: "patch"	同一マイナー内の修正を取り込みたい環境	拡張機能側の互換性情報を確認する
互換バージョンへ更新	autoUpgradeMode: "compatible"	運用負荷を下げたい標準構成	変更影響を監視で検知できる仕組みが必要
バージョン固定	version と autoUpgradeMinorVersion: false	監査要件が強い環境、段階リリース	固定したバージョンの更新計画を別途持つ

おすすめは、開発・検証環境では compatible、本番環境では patch または明示的なバージョン固定から始めることです。ただし、どれが正解かは拡張機能の種類、運用ポリシー、監査要件によって変わります。

JavaScriptでAzure Kubernetes Configuration Extensions SDKsを使う

JavaScript では @azure/arm-kubernetesconfiguration-extensions と @azure/identity を使います。Microsoft Learn の JavaScript 向けドキュメントでは、ExtensionsClient を作成し、DefaultAzureCredential などで認証する流れが示されています。対応環境として Node.js の LTS バージョンと主要ブラウザーの最新版が案内されています。(Microsoft Learn)

npm install @azure/arm-kubernetesconfiguration-extensions @azure/identity

クライアントを作成する

import { ExtensionsClient } from "@azure/arm-kubernetesconfiguration-extensions";
import { DefaultAzureCredential } from "@azure/identity";

const subscriptionId = process.env.AZURE_SUBSCRIPTION_ID;
if (!subscriptionId) {
  throw new Error("AZURE_SUBSCRIPTION_ID is required");
}

const credential = new DefaultAzureCredential();
const client = new ExtensionsClient(credential, subscriptionId);

DefaultAzureCredential を使うと、ローカル開発では Azure CLI や開発者アカウント、CI/CD ではサービスプリンシパルやマネージド ID に寄せやすくなります。グローバルチームで運用する場合も、認証方式をコードから分離しやすいのが利点です。

拡張機能を作成する

以下は、Azure Monitor Containers 系の拡張機能を作成するイメージです。実際の extensionType や設定キーは、対象の拡張機能のドキュメントに合わせてください。

const resourceGroupName = "rg-platform-prod";
const clusterRp = "Microsoft.Kubernetes";
const clusterResourceName = "connectedClusters";
const clusterName = "clusterName1";
const extensionName = "ClusterMonitor";

const extension = {
  extensionType: "azuremonitor-containers",
  autoUpgradeMode: "compatible",
  autoUpgradeMinorVersion: true,
  releaseTrain: "Preview",
  scope: {
    cluster: {
      releaseNamespace: "kube-system",
    },
  },
  configurationSettings: {
    "omsagent.env.clusterName": clusterName,
    "omsagent.secret.wsid": process.env.LOG_ANALYTICS_WORKSPACE_ID ?? "",
  },
  configurationProtectedSettings: {
    "omsagent.secret.key": process.env.LOG_ANALYTICS_KEY ?? "",
  },
};

const poller = client.extensions.create(
  resourceGroupName,
  clusterRp,
  clusterResourceName,
  clusterName,
  extensionName,
  extension
);

const result = await poller.pollUntilDone();
console.log(result.name, result.provisioningState, result.currentVersion);

JavaScript の 1.0.0 API では、create、update、delete が Poller を返す形になっています。一方、beginCreate、beginCreateAndWait、beginUpdate、beginUpdateAndWait、beginDelete、beginDeleteAndWait は API リファレンス上で非推奨とされ、代わりに create、update、delete を使うよう案内されています。(Microsoft Learn)

既存拡張機能を更新する

設定やアップグレード方針を変更する場合は update を使います。

const patch = {
  autoUpgradeMode: "patch",
  autoUpgradeMinorVersion: true,
  releaseTrain: "Preview",
  configurationSettings: {
    "omsagent.env.clusterName": clusterName,
    "custom.setting": "new-value",
  },
};

const updatePoller = client.extensions.update(
  resourceGroupName,
  clusterRp,
  clusterResourceName,
  clusterName,
  extensionName,
  patch
);

const updated = await updatePoller.pollUntilDone();
console.log(updated.name, updated.provisioningState, updated.autoUpgradeMode);

注意したいのは、更新処理が即時完了しないことです。Create や Update は長時間実行操作になるため、Poller の完了を待つ設計にします。CI/CD で使う場合は、タイムアウト、リトライ、失敗時のログ出力を必ず入れてください。

クラスター内の拡張機能を一覧化する

棚卸しやドリフト検知では list が便利です。

for await (const ext of client.extensions.list(
  resourceGroupName,
  clusterRp,
  clusterResourceName,
  clusterName
)) {
  console.log({
    name: ext.name,
    type: ext.extensionType,
    state: ext.extensionState,
    provisioningState: ext.provisioningState,
    version: ext.currentVersion,
    autoUpgradeMode: ext.autoUpgradeMode,
  });
}

たとえば、全クラスターを巡回して「本番環境なのに autoUpgradeMode が compatible になっている」「期待する拡張機能が入っていない」といった差分を検出できます。

PythonでAzure Kubernetes Configuration Extensions SDKsを使う

Python では azure-mgmt-kubernetesconfiguration-extensions と azure-identity を使います。PyPI では Python 3.9 以上が要件として記載され、認証には AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET、AZURE_SUBSCRIPTION_ID などの環境変数を使う例が示されています。(PyPI)

pip install azure-mgmt-kubernetesconfiguration-extensions azure-identity

クライアントを作成する

import os
from azure.identity import DefaultAzureCredential
from azure.mgmt.kubernetesconfiguration.extensions import (
    KubernetesConfigurationExtensionsMgmtClient,
)

subscription_id = os.environ["AZURE_SUBSCRIPTION_ID"]

client = KubernetesConfigurationExtensionsMgmtClient(
    credential=DefaultAzureCredential(),
    subscription_id=subscription_id,
)

Python 版では、操作は client.extensions から呼び出します。API リファレンスでも、ExtensionsOperations を直接インスタンス化せず、KubernetesConfigurationExtensionsMgmtClient の extensions 属性経由で使うよう案内されています。(Microsoft Learn)

拡張機能を作成する

import os

resource_group_name = "rg-platform-prod"
cluster_rp = "Microsoft.Kubernetes"
cluster_resource_name = "connectedClusters"
cluster_name = "clusterName1"
extension_name = "ClusterMonitor"

extension = {
    "properties": {
        "extensionType": "azuremonitor-containers",
        "autoUpgradeMode": "compatible",
        "autoUpgradeMinorVersion": True,
        "releaseTrain": "Preview",
        "scope": {
            "cluster": {
                "releaseNamespace": "kube-system",
            }
        },
        "configurationSettings": {
            "omsagent.env.clusterName": cluster_name,
            "omsagent.secret.wsid": os.getenv("LOG_ANALYTICS_WORKSPACE_ID", ""),
        },
        "configurationProtectedSettings": {
            "omsagent.secret.key": os.getenv("LOG_ANALYTICS_KEY", ""),
        },
    }
}

result = client.extensions.begin_create(
    resource_group_name=resource_group_name,
    cluster_rp=cluster_rp,
    cluster_resource_name=cluster_resource_name,
    cluster_name=cluster_name,
    extension_name=extension_name,
    extension=extension,
).result()

print(result.name)

Python では、begin_create が LROPoller を返します。処理完了まで待つ場合は .result() を呼びます。API リファレンスでは begin_create、begin_delete、begin_update、get、list がメソッドとして示されています。(Microsoft Learn)

既存拡張機能を更新する

patch_extension = {
    "properties": {
        "autoUpgradeMode": "patch",
        "autoUpgradeMinorVersion": True,
        "releaseTrain": "Preview",
        "configurationSettings": {
            "omsagent.env.clusterName": cluster_name,
            "custom.setting": "new-value",
        },
    }
}

updated = client.extensions.begin_update(
    resource_group_name=resource_group_name,
    cluster_rp=cluster_rp,
    cluster_resource_name=cluster_resource_name,
    cluster_name=cluster_name,
    extension_name=extension_name,
    patch_extension=patch_extension,
).result()

print(updated.name)

Python の 1.0.0b2 では、PatchExtension の auto_upgrade_minor_version、release_train、version、configuration_settings、configuration_protected_settings が properties 配下へ移動したことがリリース履歴に明記されています。ベータ版から移行する場合、更新処理のペイロード構造は必ず見直してください。(PyPI)

状態を取得して運用チェックに使う

ext = client.extensions.get(
    resource_group_name=resource_group_name,
    cluster_rp=cluster_rp,
    cluster_resource_name=cluster_resource_name,
    cluster_name=cluster_name,
    extension_name=extension_name,
)

props = ext.properties
print({
    "name": ext.name,
    "provisioning_state": getattr(props, "provisioning_state", None),
    "extension_state": getattr(props, "extension_state", None),
    "current_version": getattr(props, "current_version", None),
})

このような取得処理を定期実行すれば、拡張機能の状態監視やバージョン棚卸しに使えます。単に作成するだけでなく、作成後に期待どおり動いているか確認するところまで自動化するのが、SDK活用の実務的なポイントです。

ベータ版から1.0.0へ移行するときのチェックリスト

ベータ版のまま動いているコードがある場合、単にバージョン番号を上げるだけでは不十分です。特に JavaScript と Python で確認すべき点が異なります。

対象	確認すること	理由
JavaScript	beginCreateAndWait などを使っていないか	1.0.0 API リファレンスでは create / update / delete の利用が案内されている
JavaScript	Poller の完了待ちを実装しているか	Create / Update / Delete は非同期完了を前提にしたほうが安全
Python	Python 3.9 以上で実行しているか	PyPI で Python 3.9+ が要件として示されている
Python	PatchExtension の値を properties 配下に置いているか	1.0.0b2 の破壊的変更として、パッチ用の複数プロパティが properties 配下へ移動している
Python	begin_delete の force_delete をキーワード引数で渡しているか	1.0.0b2 の変更で force_delete が keyword-only になっている
共通	autoUpgradeMode と version の組み合わせを確認する	バージョン固定時は autoUpgradeMinorVersion を false にする必要がある
共通	clusterRp と clusterResourceName の組み合わせを確認する	AKS、Arc、ハイブリッドで値が異なる

移行作業では、まず「作成」「更新」「削除」「取得」「一覧」の5操作を小さな検証環境で動かし、次に本番相当の拡張機能タイプで確認します。最初から全クラスターに適用するのは避け、対象クラスターをタグや設定ファイルで段階的に絞り込むのが安全です。

自動化で特に楽になる運用パターン

Azure Kubernetes Configuration Extensions SDKs 1.0.0 が開発者向けに価値を持つのは、単体の API 呼び出しよりも、運用フローの中に組み込めるところです。

複数クラスターへの標準拡張機能展開

platform engineer がよく直面するのが、「全クラスターに同じ監視・セキュリティ・GitOps 系の拡張機能を入れたい」という要件です。

SDK を使えば、次のような流れを作れます。

手順	処理
対象クラスターを読み込む	JSON、YAML、タグ検索結果などから対象を決める
既存拡張機能を list で確認する	すでに入っている場合は作成をスキップする
足りない拡張機能だけ create する	環境ごとの設定値を注入する
完了後に get で状態確認する	provisioningState や extensionState を確認する
結果をログや通知へ出す	失敗クラスターだけ再実行できるようにする

この流れにすると、「誰かが手で入れ忘れた」「環境ごとに設定が微妙に違う」といった運用品質のばらつきを減らせます。

拡張機能のドリフト検知

ドリフト検知とは、実際の状態が期待する定義からズレていないか確認することです。

たとえば、期待値を次のように定義します。

{
  "extensionName": "ClusterMonitor",
  "extensionType": "azuremonitor-containers",
  "autoUpgradeMode": "patch",
  "releaseTrain": "Preview",
  "releaseNamespace": "kube-system"
}

そのうえで SDK の get や list から現在値を取得し、差分がある場合だけ通知または update します。重要なのは、いきなり自動修復するのではなく、最初は検知だけにすることです。拡張機能によっては設定変更がワークロードに影響する可能性があるため、本番環境では通知、承認、更新の順に段階化すると安全です。

CI/CDでの事前チェック

アプリケーションが特定の拡張機能に依存している場合、デプロイ前に SDK で状態を確認できます。

例として、次のようなチェックを入れます。

チェック項目	失敗時の対応
必須拡張機能が存在するか	デプロイを止める
provisioningState が成功状態か	デプロイを止め、platform チームへ通知する
期待バージョンまたは互換モードか	警告を出す、または承認フローへ回す
設定値が環境ルールに合っているか	自動修復する前に差分を記録する

このチェックを入れると、アプリケーション側の障害を「実はクラスター拡張機能が入っていなかった」という原因で起こしにくくなります。

SDKとIaCをどう使い分けるか

Microsoft.KubernetesConfiguration/extensions は Bicep、ARM template、Terraform AzAPI のリソース定義も公開されています。2025-03-01 のリソース形式では、managedBy、plan、additionalDetails、aksAssignedIdentity、autoUpgradeMode、managementDetails、scope などのプロパティが確認できます。(Microsoft Learn)

そのため、SDK と IaC は競合するものではありません。使い分けは次のように考えると実務で判断しやすくなります。

方法	向いている作業	向いていない作業
Bicep / ARM / Terraform AzAPI	初期構築、標準構成の宣言、監査しやすい定義管理	実行時条件に応じた細かい分岐、動的な棚卸し
SDK	複数クラスター巡回、状態確認、条件付き更新、CI/CD連携	すべてを宣言的に固定したい構成管理
ポータル操作	検証、単発作業、初学者の確認	大量展開、再現性が必要な本番運用

おすすめは、初期構成は IaC、日々の確認・差分検知・条件付き更新は SDK です。すべてを SDK で作ると構成の見通しが悪くなり、すべてを IaC に寄せると運用時の柔軟な判断が難しくなります。

実装時に失敗しやすいポイント

clusterRp と clusterResourceName を取り違える

AKS と Azure Arc-enabled Kubernetes を同じように扱うと、ここでつまずきます。

AKS なら多くの場合、clusterRp は Microsoft.ContainerService、clusterResourceName は managedClusters です。Arc 対応 Kubernetes なら、clusterRp は Microsoft.Kubernetes、clusterResourceName は connectedClusters です。

この組み合わせはコード内で定数化せず、クラスター種別ごとに設定として持たせましょう。

機密値を configurationSettings に入れてしまう

configurationSettings は通常の設定値、configurationProtectedSettings は機密性の高い設定値を入れるための項目です。REST API の説明でも、configurationProtectedSettings は機密性の高い構成設定として説明されています。(Microsoft Learn)

ワークスペースキー、トークン、接続文字列などは configurationProtectedSettings に入れ、ログ出力しないようにしてください。CI/CD の失敗ログに機密値が出る設計は避けるべきです。

バージョン固定と自動更新を同時に考えてしまう

version で固定したい場合、autoUpgradeMinorVersion を false にする必要があります。自動更新したいのか、特定バージョンに固定したいのかを最初に決めてください。

本番環境でよくある失敗は、「安定運用のために固定したつもりが、自動更新も有効で意図と違う動きになる」ことです。設定レビューでは、version、autoUpgradeMinorVersion、autoUpgradeMode の3つをセットで確認しましょう。

作成直後の状態だけ見て成功と判断する

Create のレスポンスが返っても、拡張機能がクラスター上で完全に利用可能になったとは限りません。レスポンス例でも、作成時に provisioningState が Creating となり、その後 Succeeded になるケースが示されています。(Microsoft Learn)

自動化では、作成後に get を実行し、provisioningState、extensionState、currentVersion を確認するステップを入れてください。

ベータ版のコードをそのまま残す

特に JavaScript の beginCreateAndWait 系と、Python の PatchExtension 構造は見直し対象です。動いているコードでも、SDK の 1.0.0 に合わせてメソッド名、戻り値、ペイロード構造を整理しておくと、後の保守が楽になります。

どのチームが優先して対応すべきか

すべてのチームがすぐに SDK 化すべきとは限りません。優先度は次のように判断するとよいでしょう。

チーム・状況	優先度	理由
複数の AKS / Arc クラスターを管理している platform engineering チーム	高	横展開と棚卸しの効果が大きい
Kubernetes 拡張機能を CI/CD の前提条件にしている DevOps チーム	高	デプロイ前チェックに組み込みやすい
Python で運用スクリプトを持っているチーム	高	PyPI の 1.0.0 を採用しやすい
Node.js / TypeScript で内部ツールを作っているチーム	高	JavaScript SDK の create / update / list を使って管理画面や自動化ツールを作りやすい
単一クラスターをポータル中心で運用しているチーム	中	すぐに SDK 化するより、まず IaC 化や手順標準化を優先してもよい
検証環境だけで使っているチーム	中	1.0.0移行の影響確認には向いている

まず着手すべきなのは、既存の拡張機能を一覧化するスクリプトです。作成や更新よりリスクが低く、現状把握の価値が高いためです。その後、差分検知、更新、作成の順に自動化範囲を広げると失敗しにくくなります。

まず何をすべきか

Azure Kubernetes Configuration Extensions SDKs 1.0.0 は、クラスター拡張機能の管理をコードに寄せるうえで、JavaScript と Python の両方から採用しやすくなった更新です。

実務では、次の順番で進めるのがおすすめです。

| 順番 | 作業 |
| -: | ————————————————————— |
| 1 | 現在使っている拡張機能名、拡張機能タイプ、対象クラスターを棚卸しする |
| 2 | JavaScript または Python で list / get の読み取りスクリプトを作る |
| 3 | ベータ版 SDK を使っている場合は、1.0.0 のメソッド名とペイロード構造を確認する |
| 4 | autoUpgradeMode、autoUpgradeMinorVersion、version の運用方針を決める |
| 5 | 検証環境で create / update を実行し、Poller 完了後の状態確認まで組み込む |
| 6 | CI/CD や定期ジョブに組み込み、差分検知から段階的に自動化する |

最初から「全拡張機能を完全自動管理する」と考える必要はありません。まずは一覧化と状態確認から始め、運用ルールが固まった部分だけ作成・更新まで広げるのが安全です。1.0.0になったことで、Azure Kubernetes Configuration Extensions SDKs は検証用のコードだけでなく、platform engineering や DevOps の日常運用に組み込みやすい選択肢になりました。