VM とコンテナーのホスト コンピューティング ネットワーク (HCN) サービス API
ホスト コンピューティング ネットワーク (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 ドキュメントのスキーマについて確認する。