VM とコンテナーのホストコンピューティングネットワーク (HCN) サービス API

[アーティクル]
10/06/2023

適用対象: Windows Server 2022、Windows Server 2019

ホストコンピューティングネットワーク (HCN) サービス API は、仮想ネットワーク、仮想ネットワークエンドポイント、および関連付けられているポリシーを管理するためのプラットフォームレベルのアクセスを提供する、一般公開されている Win32 API です。これにより、Windows ホストで実行されている仮想マシン (VM) とコンテナーに対して接続とセキュリティが提供されます。

開発者は HCN サービス API を使用して、アプリケーションワークフロー内の VM とコンテナーのネットワークを管理します。 HCN API は、開発者に最適なエクスペリエンスを提供するように設計されています。エンドユーザーは、これらの API を直接操作することはできません。

HCN サービス API の機能

OnCore/VM 上のホストネットワークサービス (HNS) によってホストされる C API として実装されます。
ネットワーク、エンドポイント、名前空間、ポリシーなどの HCN オブジェクトを作成、変更、削除、列挙する機能を提供します。操作はオブジェクトに対するハンドル (ネットワークハンドルなど) に対して実行され、内部的にこれらのハンドルは RPC コンテキストハンドルを使用して実装されます。
スキーマベースです。 API のほとんどの関数では、入力パラメーターと出力パラメーターを、関数呼び出しの引数を JSON ドキュメントとして含む文字列として定義します。 JSON ドキュメントは厳密に型指定されバージョン管理されたスキーマに基づいており、これらのスキーマはパブリックドキュメントの一部です。
サブスクリプション/コールバック API は、クライアントがネットワークの作成や削除などのサービス全体のイベントの通知に登録するために提供されます。
HCN API は、システムサービスで実行されているデスクトップブリッジ (別名、Centennial) アプリで動作します。この API は、呼び出し元からユーザートークンを取得して ACL をチェックします。

ヒント

HCN サービス API は、バックグラウンドタスクとフォアグラウンド以外のウィンドウでサポートされています。

用語: ホストとコンピューティング

ホストコンピューティングサービスを使用すると、呼び出し元は単一の物理コンピューター上の仮想マシンとコンテナーの両方を作成および管理できます。業界用語に従う名前が付きます。

ホストは、仮想化されたリソースを提供するオペレーティングシステムを参照するために仮想化業界で広く使用されています。
コンピューティングは、単なる仮想マシンよりも広い仮想化方法を参照するために使用されます。ホストコンピューティングネットワークサービスを使用すると、呼び出し元は単一の物理コンピューター上の仮想マシンとコンテナーの両方のネットワークを作成および管理できます。

スキーマベースの構成ドキュメント

明確に定義されたスキーマに基づく構成ドキュメントは、仮想化空間で確立された業界標準です。 Docker や Kubernetes などのほとんどの仮想化ソリューションは、構成ドキュメントに基づいて API を提供します。 Microsoft も参加するいくつかの業界イニシアチブによって、OpenAPI などのスキーマを定義および検証するためのエコシステムが推進されます。これらのイニシアチブでは、Open Container Initiative (OCI) など、コンテナーに使用されるスキーマの特定のスキーマ定義の標準化も推進されます。

構成ドキュメントの作成に使用される言語は JSON で、次と組み合わせて使用します。

ドキュメントのオブジェクトモデルを定義するスキーマ定義
JSON ドキュメントがスキーマに準拠するかどうかの検証
API の呼び出し元で使用されるプログラミング言語における、これらのスキーマのネイティブ表現間での JSON ドキュメントの自動変換

よく使用されるスキーマ定義は OpenAPI と JSON スキーマです。これにより、ドキュメント内のプロパティの詳細な定義を指定できます。次に例を示します。

パーセンテージを表すプロパティの 0 ～ 100 など、プロパティの有効な値のセット。
プロパティの有効な文字列のセットとして表される列挙体の定義。
文字列の予期される形式の正規表現。

HCN API の文書化の一環として、JSON ドキュメントのスキーマを OpenAPI 仕様として公開する予定です。この仕様に基づいてスキーマの言語固有の表現を使用すると、クライアントで使用されるプログラミング言語でスキーマオブジェクトをタイプセーフで使用できます。

例

VM の構成ドキュメントで SCSI コントローラーを表すオブジェクトについて、このワークフローの例を次に示します。

enum IpamType
{
    [NewIn("2.0")] Static,
    [NewIn("2.0")] Dhcp,
};
class Ipam
{
    // Type : dhcp
    [NewIn("2.0"),OmitEmpty] IpamType   Type;
    [NewIn("2.0"),OmitEmpty] Subnet     Subnets[];
};
class Subnet : HCN.Schema.Common.Base
{
    [NewIn("2.0"),OmitEmpty] string         IpAddressPrefix;
    [NewIn("2.0"),OmitEmpty] SubnetPolicy   Policies[];
    [NewIn("2.0"),OmitEmpty] Route          Routes[];
};
enum SubnetPolicyType
{
    [NewIn("2.0")] VLAN
};
class SubnetPolicy
{
    [NewIn("2.0"),OmitEmpty] SubnetPolicyType                 Type;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Common.PolicySettings Data;
};
class PolicySettings
{
    [NewIn("2.0"),OmitEmpty]  string      Name;
};
class VlanPolicy : HCN.Schema.Common.PolicySettings
{
    [NewIn("2.0")] uint32 IsolationId;
};
class Route
{
    [NewIn("2.0"),OmitEmpty] string NextHop;
    [NewIn("2.0"),OmitEmpty] string DestinationPrefix;
    [NewIn("2.0"),OmitEmpty] uint16 Metric;
};

ヒント

[NewIn("2.0") 注釈は、スキーマ定義のバージョン管理サポートの一部です。この内部定義から、スキーマの OpenAPI 仕様を生成します。

{
    "swagger" : "2.0",
    "info" : {
       "version" : "2.1",
       "title" : "HCN API"
    },
    "definitions": {
        "Ipam": {
            "type": "object",
            "properties": {
                "Type": {
                    "type": "string",
                    "enum": [
                        "Static",
                        "Dhcp"
                    ],
                    "description": " Type : dhcp"
                },
                "Subnets": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/Subnet"
                    }
                }
            }
        },
        "Subnet": {
            "type": "object",
            "properties": {
                "ID": {
                    "type": "string",
                    "pattern": "^[0-9A-Fa-f]{8}-([0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}$"
                },
                "IpAddressPrefix": {
                    "type": "string"
                },
                "Policies": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/SubnetPolicy"
                    }
                },
                "Routes": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/Route"
                    }
                }
            }
        },
        "SubnetPolicy": {
            "type": "object",
            "properties": {
                "Type": {
                    "type": "string",
                    "enum": [
                        "VLAN",
                        "VSID"
                    ]
                },
                "Data": {
                    "$ref": "#/definitions/PolicySettings"
                }
            }
        },
        "PolicySettings": {
            "type": "object",
            "properties": {
                "Name": {
                    "type": "string"
                }
            }
        },
        "VlanPolicy": {
            "type": "object",
            "properties": {
                "Name": {
                    "type": "string"
                },
                "IsolationId": {
                    "type": "integer",
                    "format": "uint32"
                }
            }
        },
        "Route": {
            "type": "object",
            "properties": {
                "NextHop": {
                    "type": "string"
                },
                "DestinationPrefix": {
                    "type": "string"
                },
                "Metric": {
                    "type": "integer",
                    "format": "uint16"
                }
            }
        }
    }
}

Swagger などのツールを使用して、クライアントで使用されるスキーマプログラミング言語の言語固有の表現を生成できます。 Swagger では、C#、Go、Javascript、Python など、さまざまな言語がサポートされています。

最上位レベルの IPAM およびサブネットオブジェクトに対して生成された C# コードの例。
トップレベルの IPAM およびサブネットオブジェクトに対して生成された Go コードの例。 Go は、ホストコンピューティングネットワークサービス API のコンシューマーである Docker と Kubernetes によって使用されます。 Go には、JSON ドキュメント間で Go 型をマーシャリングするためのサポートが組み込まれています。

ツールを使用すると、コードの生成と検証に加えて、JSON ドキュメント (つまり、Visual Studio Code) の操作を簡略化できます。

HCN スキーマで定義されている最上位のオブジェクト

最上位のオブジェクトは次のとおりです。

class HostComputeNetwork : HCN.Schema.Common.Base
{
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.NetworkMode          Type;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.NetworkPolicy        Policies[];
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.MacPool              MacPool;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.DNS                  Dns;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.Ipam                 Ipams[];
};
class HostComputeEndpoint : HCN.Schema.Common.Base
{
    [NewIn("2.0"),OmitEmpty] string                                     HostComputeNetwork;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.Endpoint.EndpointPolicy Policies[];
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.Endpoint.IpConfig       IpConfigurations[];
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.DNS                     Dns;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.Route                   Routes[];
    [NewIn("2.0"),OmitEmpty] string                                     MacAddress;
};
class HostComputeNamespace : HCN.Schema.Common.Base
{
    [NewIn("2.0"),OmitEmpty] uint32                                    NamespaceId;
    [NewIn("2.0"),OmitEmpty] Guid                                      NamespaceGuid;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Namespace.NamespaceType        Type;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Namespace.NamespaceResource    Resources[];
};
class HostComputeLoadBalancer : HCN.Schema.Common.Base
{
    [NewIn("2.0"), OmitEmpty] string                                               HostComputeEndpoints[];
    [NewIn("2.0"), OmitEmpty] string                                               VirtualIPs[];
    [NewIn("2.0"), OmitEmpty] HCN.Schema.Network.Endpoint.Policy.PortMappingPolicy PortMappings[];
    [NewIn("2.0"), OmitEmpty] HCN.Schema.LoadBalancer.LoadBalancerPolicy           Policies[];
};

次の手順

一般的な HCN シナリオについて確認する。
HCN の RPC コンテキストハンドルについて確認する。
HCN JSON ドキュメントのスキーマについて確認する。

VM とコンテナーのホスト コンピューティング ネットワーク (HCN) サービス API