Host Compute-Netzwerkdienst-API (HCN) für VMs und Container
Gilt für: Windows Server 2022, Windows Server 2019
Host Compute Network (HCN)-Dienst-API ist eine öffentlich zugängliche Win32-API, die Zugriff auf Plattformebene zum Verwalten der virtuellen Netzwerke, virtuellen Netzwerkendpunkte und zugehörigen Richtlinien bietet. Zusammen bieten diese Konnektivität und Sicherheit für virtuelle Computer (VMs) und Container, die auf einem Windows-Host ausgeführt werden.
Entwickler verwenden die HCN-Dienst-API, um Netzwerke für VMs und Container in ihren Anwendungsworkflows zu verwalten. Die HCN-API wurde entwickelt, um Entwicklern die beste Benutzererfahrung zu bieten. Endbenutzer interagieren nicht direkt mit diesen APIs.
Features der HCN-Dienst-API
Implementiert als C-API, die vom Hostnetzwerkdienst (Host Network Service, HNS) auf OnCore/VM gehostet wird.
Bietet die Möglichkeit, HCN-Objekte wie Netzwerke, Endpunkte, Namespaces und Richtlinien zu erstellen, zu ändern, zu löschen und aufzuzählen. Vorgänge werden für Handles für die Objekte ausgeführt (z. B. für ein Netzwerkhandle), und intern werden diese Handles mithilfe von RPC-Kontexthandles implementiert.
Schemabasiert. Die meisten Funktionen der API definieren Eingabe- und Ausgabeparameter als Zeichenfolgen, die die Argumente des Funktionsaufrufs als JSON-Dokumente enthalten. Die JSON-Dokumente basieren auf stark typisierten und versionsbasierten Schemas. Diese Schemas sind Teil der öffentlichen Dokumentation.
Eine Abonnement-/Rückruf-API wird bereitgestellt, um Clients die Registrierung für Benachrichtigungen über dienstweite Ereignisse wie Netzwerkerstellungen und -löschungen zu ermöglichen.
Die HCN-API funktioniert in Desktop-Brücken-Apps (auch als Centennial-Apps bezeichnet), die in Systemdiensten ausgeführt werden. Die API überprüft die Zugriffssteuerungsliste, indem sie das Benutzertoken vom Aufrufer abruft.
Tipp
Die HCN-Dienst-API wird in Hintergrundaufgaben und nicht im Vordergrund ausgeführten Fenstern unterstützt.
Terminologie: Host im Vergleich zu Compute
Mit dem Host Compute-Dienst können Aufrufer sowohl virtuelle Computer als auch Container auf einem einzelnen physischen Computer erstellen und verwalten. Sein Name folgt der branchenspezifischen Terminologie.
Host wird in der Virtualisierungsbranche häufig verwendet, um das Betriebssystem zu bezeichnen, das virtualisierte Ressourcen bereitstellt.
Compute wird als Bezeichnung von Virtualisierungsmethoden verwendet, die über virtuelle Computer hinausgehen. Mit dem Host-Compute-Netzwerkdienst können Aufrufer Netzwerke sowohl für virtuelle Computer als auch für Container auf einem einzelnen physischen Computer erstellen und verwalten.
Schemabasierte Konfigurationsdokumente
Konfigurationsdokumente, die auf klar definierten Schemas basieren, sind ein etablierter Branchenstandard im Virtualisierungsbereich. Die meisten Virtualisierungslösungen, wie etwa Docker und Kubernetes, stellen APIs auf der Grundlage von Konfigurationsdokumenten bereit. Mehrere Brancheninitiativen, an denen auch Microsoft beteiligt ist, fördern ein Ökosystem zum Definieren und Validieren dieser Schemas, z. B. OpenAPI. Diese Initiativen fördern außerdem die Standardisierung spezifischer Schemadefinitionen für die Schemas, die für Container verwendet werden, z. B. Open Container Initiative (OCI).
Die Sprache, die zum Erstellen von Konfigurationsdokumenten verwendet wird, ist JSON, das in folgenden Kombinationen verwendet wird:
- Schemadefinitionen, die ein Objektmodell für das Dokument definieren
- Überprüfung, ob ein JSON-Dokument einem Schema entspricht
- Automatisierte Konvertierung von JSON-Dokumenten in und aus native(n) Darstellungen dieser Schemas in den Programmiersprachen, die von den Aufrufern der APIs verwendet werden
Häufig verwendete Schemadefinitionen sind OpenAPI und JSON Schema, mit denen Sie die detaillierten Definitionen der Eigenschaften in einem Dokument angeben können, z. B.:
- Die gültige Menge von Werten für eine Eigenschaft, z. B. 0–100 für eine Eigenschaft, die einen Prozentsatz darstellt.
- Die Definition von Enumerationen, die als Menge gültiger Zeichenfolgen für eine Eigenschaft dargestellt werden.
- Ein regulärer Ausdruck für das erwartete Format einer Zeichenfolge.
Im Rahmen der Dokumentation der HCN-APIs planen wir die Veröffentlichung des Schemas unserer JSON-Dokumente als OpenAPI-Spezifikation. Auf der Grundlage dieser Spezifikation können sprachspezifische Darstellungen des Schemas eine typsichere Verwendung der Schemaobjekte in der vom Client verwendeten Programmiersprache ermöglichen.
Beispiel
Hier sehen Sie ein Beispiel für diesen Workflow für das Objekt, das einen SCSI-Controller im Konfigurationsdokument eines virtuellen Computers darstellt.
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;
};
Tipp
Die [NewIn("2.0")]-Anmerkungen sind Teil der Versionsverwaltungsunterstützung für die Schemadefinitionen. Aus dieser internen Definition generieren wir die OpenAPI-Spezifikationen für das Schema:
{
"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"
}
}
}
}
}
Sie können Tools wie Swagger verwenden, um sprachspezifische Darstellungen der Schemaprogrammiersprache zu generieren, die von einem Client verwendet wird. Swagger unterstützt eine Vielzahl von Sprachen wie C#, Go, Javascript und Python.
Beispiel für generierten C#-Code für das IPAM- und Subnetzobjekt der obersten Ebene.
Beispiel für generierten Go-Code für das IPAM- und Subnetzobjekt der obersten Ebene. Go wird von Docker und Kubernetes verwendet, die zwei der Consumer der Host Compute-Netzwerkdienst-APIs sind. Go bietet integrierte Unterstützung für das Marshallen von Go-Typen in und aus JSON-Dokumente(n).
Zusätzlich zur Codegenerierung und -überprüfung können Sie Tools verwenden, um die Arbeit mit JSON-Dokumenten zu vereinfachen, d. h. Visual Studio Code.
Objekte der obersten Ebene, die im HCN-Schema definiert sind
Die Objekte der obersten Ebene sind:
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[];
};
Nächste Schritte
Erfahren Sie mehr über häufige HCN-Szenarien.
Erfahren Sie mehr über die RPC-Kontexthandles für HCN.
Erfahren Sie mehr über die HCN-JSON-Dokumentschemas.