Azure Cosmos DB (プレビュー) で Azure Kubernetes を使用する方法How to use Azure Kubernetes with Azure Cosmos DB (preview)

Azure Cosmos DB の etcd API では、Azure Cosmos DB を Azure Kubernetes のバックエンド ストアとして使用できます。The etcd API in Azure Cosmos DB allows you to use Azure Cosmos DB as the backend store for Azure Kubernetes. Azure Cosmos DB は etcd ワイヤ プロトコルを実装します。これにより、マスター ノードの API サーバーは、ローカルにインストールされた etcd にアクセスする場合と同様に Azure Cosmos DB を使用できるようになります。Azure Cosmos DB implements the etcd wire protocol, which allows the master node’s API servers to use Azure Cosmos DB just like it would access a locally installed etcd. Azure Cosmos DB の etcd API は現在プレビュー段階にあります。etcd API in Azure Cosmos DB is currently in preview. Kubernetes のバッキング ストアとして Azure Cosmos etcd API を使用する場合、次の利点があります。When you use Azure Cosmos etcd API as the backing store for Kubernetes, you get the following benefits:

  • etcd を手動で構成して管理する必要はありません。No need to manually configure and manage etcd.
  • Cosmos で保証される etcd の高可用性 (単一のリージョンで 99.99%、複数のリージョンで 99.999%)。High availability of etcd, guaranteed by Cosmos (99.99% in single region, 99.999% in multiple regions).
  • etcd の柔軟なスケーラビリティ。Elastic scalability of etcd.
  • 既定でのセキュリティ保護とエンタープライズ対応。Secure by default & enterprise ready.
  • 業界をリードする包括的な SLA。Industry-leading, comprehensive SLAs.

Azure Cosmos DB での etcd API の詳細については、概要の記事をご覧ください。To learn more about etcd API in Azure Cosmos DB, see the overview article. この記事では、Azure Kubernetes エンジン (aks-engine) を使用して、ローカルでインストールされ構成されている etcd の代わりに Azure Cosmos DB を使用する、Azure 上の Kubernetes クラスターをブートストラップする方法について説明します。This article shows you how to use Azure Kubernetes Engine (aks-engine) to bootstrap a Kubernetes cluster on Azure that uses Azure Cosmos DB instead of a locally installed and configured etcd.


  1. Azure CLI の最新バージョンをインストールします。Install the latest version of Azure CLI. お使いのオペレーティング システムに固有の Azure CLI をダウンロードしてインストールできます。You can download Azure CLI specific to your operating system and install.

  2. Azure Kubernetes エンジンの最新バージョンをインストールします。Install the latest version of Azure Kubernetes Engine. さまざまなオペレーティング システムのインストール手順は、Azure Kubernetes エンジンのページに記載されています。The installation instructions for different operating systems are available in Azure Kubernetes Engine page. リンク先のドキュメントの AKS エンジンのインストールに関するセクションの手順だけが必要です。ダウンロード後、zip ファイルを抽出します。You just need the steps from Install AKS Engine section of the linked doc. After downloading, extract the zip file.

    Azure Kubernetes エンジン (aks-engine) は、Azure 上の Kubernetes クラスター用の Azure Resource Manager テンプレートを生成します。The Azure Kubernetes Engine (aks-engine) generates Azure Resource Manager templates for Kubernetes clusters on Azure. aks-engine への入力は、オーケストレーター、フィーチャー、エージェントなど、目的のクラスターを記述したクラスター定義ファイルです。The input to aks-engine is a cluster definition file that describes the desired cluster, including orchestrator, features, and agents. 入力ファイルの構造は、Azure Kubernetes Service のパブリック API に似ています。The structure of the input files is similar to the public API for Azure Kubernetes Service.

  3. Azure Cosmos DB の etcd API は現在プレビュー段階にあります。The etcd API in Azure Cosmos DB is currently in preview. でサインアップしてプレビュー バージョンを使用します。Sign up to use the preview version at: フォームを送信した後、サブスクリプションは、Azure Cosmos etcd API を使用できるようにホワイトリストに登録されます。After you submit the form, your subscription will be whitelisted to use the Azure Cosmos etcd API.

Azure Cosmos DB でクラスターをデプロイするDeploy the cluster with Azure Cosmos DB

  1. コマンド プロンプト ウィンドウを開き、次のコマンドで Azure にサインインします。Open a command prompt window, and sign into Azure with the following command:

    az login 
  2. 複数のサブスクリプションがある場合は、Azure Cosmos DB etcd API のホワイトリストに登録されているサブスクリプションに切り替えます。If you have more than one subscription, switch to the subscription that has been whitelisted for Azure Cosmos DB etcd API. 次のコマンドを使用して、必要なサブスクリプションに切り替えることができます。You can switch to the required subscription using the following command:

    az account set --subscription "<Name of your subscription>"
  3. 次に、Azure Kubernetes クラスターが必要とするリソースをデプロイする新しいリソース グループを作成します。Next create a new resource group where you will deploy the resources required by the Azure Kubernetes cluster. 必ず "centralus" リージョンにリソース グループを作成します。Make sure to create the resource group in the "centralus" region. リソース グループが "centralus" リージョン内にあることは必須ではありませんが、Azure Cosmos etcd API は現在、"centralus" リージョンへのデプロイのみに使用できます。It's not mandatory for the resource group to be in "centralus" region however, Azure Cosmos etcd API is currently available to deploy in "centralus" region only. したがって、Kubernetes クラスターを Cosmos etcd インスタンスと併置することをお勧めします。So it's best to have the Kubernetes cluster to be colocated with the Cosmos etcd instance:

    az group create --name <Name> --location "centralus"
  4. 次に、同じリソース グループの一部であるリソースと通信できるように、Azure Kubernetes クラスターのサービス プリンシパルを作成します。Next create a service principal for the Azure Kubernetes cluster so that it can communicate with the resources that are a part of the same resource group. Azure CLI、PowerShell または Azure portal を使用してサービス プリンシパルを作成することができます。この例では CLI を使用して作成します。You can create a service principal using Azure CLI, PowerShell or Azure portal, in this example you will you CLI to create it.

    az ad sp create-for-rbac --role="Contributor" --scopes="/subscriptions/<Your_Azure_subscription_ID>/resourceGroups/<Your_resource_group_name>"

    このコマンドは、たとえば次のようなサービス プリンシパルの詳細を出力します。This command outputs the details of a service principal, for example:

    Retrying role assignment creation: 1/36
      "appId": "8415a4e9-4f83-46ca-a704-107457b2e3ab",
      "displayName": "azure-cli-2019-04-19-19-01-46",
      "name": "http://azure-cli-2019-04-19-19-01-46",
      "password": "102aecd3-5e37-4f3d-8738-2ac348c2e6a7",
      "tenant": "72f988bf-86f1-41af-91ab-2d7cd011db47"

    appId[パスワード] フィールドを書き留めます。次の手順でこれらのパラメーターを使用するためです。Make a note of the appId and the password fields, as you will use these parameters in the next steps.

  5. コマンド プロンプトから、Azure Kubernetes エンジン実行可能ファイルが配置されているフォルダーに移動します。From the command prompt, navigate to the folder where the Azure Kubernetes Engine executable is located. たとえば、次のようにコマンド プロンプトでフォルダーに移動することができます。For example, on your command prompt you can navigate to the folder as:

    cd "\aks-engine-v0.36.3-windows-amd64\aks-engine-v0.36.3-windows-amd64"
  6. 任意のテキスト エディターを開き、Azure Cosmos DB etcd API を使用して、Azure Kubernetes クラスターをデプロイする Resource Manager テンプレートを定義します。Open a text editor of your choice and define a Resource Manager template that deploys the Azure Kubernetes cluster with Azure Cosmos DB etcd API. 次の JSON 定義をテキスト エディターにコピーし、apiModel.json としてファイルに保存します。Copy the following JSON definition to your text editor and save the file as apiModel.json:

     "apiVersion": "vlabs",
     "properties": {
         "orchestratorProfile": {
             "orchestratorType": "Kubernetes",
             "kubernetesConfig": {
                 "useManagedIdentity": false
         "masterProfile": {
             "count": 1,
             "dnsPrefix": "",
             "vmSize": "Standard_D2_v3",
             "cosmosEtcd": true
         "agentPoolProfiles": [
                 "name": "agent",
                 "count": 1,
                 "vmSize": "Standard_D2_v3",
                 "availabilityProfile": "AvailabilitySet"
         "linuxProfile": {
             "adminUsername": "azureuser",
             "ssh": {
                 "publicKeys": [
                         "keyData": ""

    JSON/クラスター定義ファイルで、注意すべきキー パラメーターは "cosmosEtcd": true です。In the JSON/cluster definition file, the key parameter to note is "cosmosEtcd": true. このパラメーターは、"masterProfile" プロパティ内にあり、通常の etcd ではなく、Azure Cosmos etcd API を使用するようにデプロイに指示します。This parameter is in the "masterProfile" properties and it indicates the deployment to use Azure Cosmos etcd API instead of regular etcd.

  7. 次のコマンドで、Azure Cosmos DB を使用する Azure Kubernetes クラスターをデプロイします。Deploy the Azure Kubernetes cluster that uses Azure Cosmos DB with the following command:

    aks-engine deploy \
      --subscription-id <Your_Azure_subscription_ID> \
      --client-id <Service_ principal_appId> \
      --client-secret <Service_ principal_password> \
      --dns-prefix <Region_unique_dns_name > \
      --location centralus \
      --resource-group <Resource_Group_Name> \
      --api-model <Fully_qualified_path_to_the_template_file>  \

    Azure Kubernetes エンジンは、Azure Kubernetes の目的の図形、サイズ、および構成について説明するクラスター定義を使用します。Azure Kubernetes Engine consumes a cluster definition that outlines the desired shape, size, and configuration of the Azure Kubernetes. クラスター定義を通じて有効にできる複数の機能があります。There are several features that can be enabled through the cluster definition. この例では、次のパラメーターを使用します。In this example you will use the following parameters:

    • subscription-id: Azure Cosmos DB etcd API が有効になっている Azure サブスクリプション ID。subscription-id: Azure subscription ID that has Azure Cosmos DB etcd API enabled.
    • client-id: サービス プリンシパルの appId。client-id: The service principal's appId. appId は、手順 4 で出力として返されました。The appId was returned as output in step 4.
    • Client-secret: サービス プリンシパルのパスワードまたはランダムに生成されたパスワード。Client-secret: The service principal's password or a randomly generated password. この値は、手順 4 の 'password' パラメーターで出力として返されました。This value was returned as output in the 'password' parameter in step 4.
    • dnsPrefix: リージョン固有の DNS 名。dnsPrefix: A region-unique DNS name. この値は、ホスト名 (値の例は - myprod1, staging) の一部を形成します。This value will form part of the hostname (example values are- myprod1, staging).
    • location: クラスターのデプロイ先の場所。現在、"centralus" だけがサポートされています。location: Location where the cluster should be deployed to, currently only "centralus" is supported.


    Azure Cosmos etcd API は現在、"centralus" リージョンでのデプロイにのみ利用できます。Azure Cosmos etcd API is currently available to deploy in "centralus" region only.

    • api-model: テンプレート ファイルへの完全修飾パス。api-model: Fully qualified path to the template file.
    • force-overwrite: このオプションは、出力ディレクトリ内の既存のファイルを自動的に上書きするために使用されます。force-overwrite: This option is used to automatically overwrite existing files in the output directory.

    次のコマンドはデプロイの例を示します。The following command shows an example deployment:

    aks-engine deploy \
      --subscription-id 1234fc61-1234-1234-1234-be1234d12c1b \
      --client-id 1234a4e9-4f83-46ca-a704-107457b2e3ab \
      --client-secret 123aecd3-5e37-4f3d-8738-2ac348c2e6a7 \
      --dns-prefix aks-sg-test \
      --location centralus \
      --api-model "C:\Users\demouser\Downloads\apiModel.json"  \

デプロイを検証するVerify the deployment

テンプレート デプロイが完了するまで、数分間かかります。The template deployment takes several minutes to complete. デプロイが正常に完了すると、コマンド プロンプトで次の出力が表示されます。After the deployment is successfully completed, you will see the following output in the commands prompt:

WARN[0006] apimodel: missing masterProfile.dnsPrefix will use "aks-sg-test"
WARN[0006] --resource-group was not specified. Using the DNS prefix from the apimodel as the resource group name: aks-sg-test
INFO[0025] Starting ARM Deployment (aks-sg-test-546247491). This will take some time...
INFO[0587] Finished ARM Deployment (aks-sg-test-546247491). Succeeded

リソース グループには、仮想マシン、Azure Cosmos アカウント (etcd API)、仮想ネットワーク、可用性セット、Kubernetes クラスターで必要なその他のリソースなどのリソースが含まれるようになりました。The resource group now contains resources such as- virtual machine, Azure Cosmos account(etcd API), virtual network, availability set, and other resources required by the Kubernetes cluster.

Azure Cosmos アカウントの名前は、k8s が付加された、指定した DNS プレフィックスに一致します。The Azure Cosmos account’s name will match your specified DNS prefix appended with k8s. Azure Cosmos アカウントは、EtcdDB という名前のデータベースと EtcdData という名前のコンテナーで自動的にプロビジョニングされます。Your Azure Cosmos account will be automatically provisioned with a database named EtcdDB and a container named EtcdData. コンテナーにはすべての etcd 関連データが格納されます。The container will store all the etcd related data. コンテナーは、特定数の要求ユニットでプロビジョニングされ、ワークロードに基づいて、スループットを拡大縮小 (増減)できます。The container is provisioned with a certain number of request units and you can scale (increase/decrease) the throughput based on your workload.

次の手順Next steps