API de service HCN (Host Compute Network) pour les machines virtuelles et les conteneurs
S’applique à : Windows Server 2022, Windows Server 2019
L’API du service HCN est une API Win32 exposée publiquement qui fournit un accès au niveau de la plateforme pour gérer les réseaux virtuels, les points de terminaison de réseaux virtuels et les stratégies associées. Ensemble, cela fournit la connectivité et la sécurité pour les machines virtuelles et les conteneurs s’exécutant sur un hôte Windows.
Les développeurs utilisent l’API de service HCN pour gérer la mise en réseau des machines virtuelles et des conteneurs dans leurs workflows d’application. L’API HCN a été conçue pour offrir la meilleure expérience aux développeurs. Les utilisateurs finaux n’interagissent pas directement avec ces API.
Fonctionnalités de l’API de service HCN
Implémenté en tant qu’API C hébergée par le service réseau hôte (HNS) sur l’onCore/machine virtuelle.
Permet de créer, modifier, supprimer et énumérer des objets HCN tels que des réseaux, des points de terminaison, des espaces de noms et des stratégies. Les opérations s’exécutent sur les handles des objets (par exemple, un handle réseau), et ces handles sont implémentés en interne à l’aide de handles de contexte RPC.
Basé sur un schéma. La plupart des fonctions de l’API définissent les paramètres d’entrée et de sortie sous forme de chaînes contenant les arguments de l’appel de fonction en tant que documents JSON. Les documents JSON sont basés sur des schémas fortement typés et versionnés. Ces schémas font partie de la documentation publique.
Une API d’abonnement/rappel est fournie pour permettre aux clients de s’inscrire aux notifications d’événements à l’échelle du service, tels que les créations et les suppressions réseau.
L’API HCN fonctionne dans Pont du bureau (alias Centennial) applications s’exécutant dans les services système. L’API vérifie la liste de contrôle d’accès en récupérant le jeton utilisateur de l’appelant.
Conseil
L’API de service HCN est prise en charge dans les tâches en arrière-plan et les fenêtres non au premier plan.
Terminologie : hôte et calcul
Le service de calcul hôte permet aux appelants de créer et de gérer des machines virtuelles et des conteneurs sur un seul ordinateur physique. Il est nommé pour suivre la terminologie de l’industrie.
Hôte est largement utilisé dans le secteur de la virtualisation pour faire référence au système d’exploitation qui fournit des ressources virtualisées.
Calcul est utilisé pour faire référence à des méthodes de virtualisation qui sont plus larges que de simples machines virtuelles. Le service de réseau de calcul hôte permet aux appelants de créer et de gérer la mise en réseau pour les machines virtuelles et le conteneur sur un seul ordinateur physique.
Documents de configuration basés sur des schémas
Les documents de configuration basés sur des schémas bien définis sont une norme industrielle établie dans l’espace de virtualisation. La plupart des solutions de virtualisation, telles que Docker et Kubernetes, fournissent des API basées sur des documents de configuration. Plusieurs initiatives du secteur, avec la participation de Microsoft, pilotent un écosystème pour la définition et la validation de ces schémas, comme OpenAPI. Ces initiatives pilotent également la normalisation des définitions de schémas spécifiques pour les schémas utilisés pour les conteneurs, comme Open Container Initiative (OCI).
Le langage utilisé pour la création de documents de configuration est JSON, que vous utilisez en combinaison avec :
- Définitions de schéma qui définissent un modèle objet pour le document
- Validation de la conformité d’un document JSON à un schéma
- Conversion automatisée de documents JSON vers et à partir de représentations natives de ces schémas dans les langages de programmation utilisés par les appelants des API
Les définitions de schéma fréquemment utilisées sont OpenAPI et JSON Schema, ce qui vous permet de spécifier les définitions détaillées des propriétés d’un document, par exemple :
- Ensemble de valeurs valide pour une propriété, par exemple 0-100 pour une propriété représentant un pourcentage.
- Définition d’énumérations, qui sont représentées sous la forme d’un ensemble de chaînes valides pour une propriété.
- Expression régulière pour le format attendu d’une chaîne.
Dans le cadre de la documentation des API HCN, nous prévoyons de publier le schéma de nos documents JSON en tant que spécification OpenAPI. Sur la base de cette spécification, les représentations spécifiques au langage du schéma peuvent permettre une utilisation sans risque de type des objets de schéma dans le langage de programmation utilisé par le client.
Exemple
Voici un exemple de flux de travail pour l’objet représentant un contrôleur SCSI dans le document de configuration d’une machine virtuelle.
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;
};
Conseil
Les annotations [NewIn(« 2.0 ») font partie de la prise en charge du contrôle de version pour les définitions de schéma. À partir de cette définition interne, nous générons les spécifications OpenAPI pour le schéma :
{
"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"
}
}
}
}
}
Vous pouvez utiliser des outils, tels que Swagger, pour générer des représentations spécifiques au langage du langage de programmation de schéma utilisé par un client. Swagger prend en charge divers langages tels que C#, Go, Javascript et Python).
Exemple de code C# généré pour l’objet IPAM et sous-réseau de niveau supérieur.
Exemple de code Go généré pour l’objet IPAM et de sous-réseau de niveau supérieur. Go est utilisé par Docker et Kubernetes, qui sont deux des consommateurs des API du service de réseau de calcul hôte. Go dispose d’une prise en charge intégrée pour le marshaling des types Go vers et à partir de documents JSON.
En plus de la génération et de la validation du code, vous pouvez utiliser des outils pour simplifier le travail avec les documents JSON, c’est-à-dire Visual Studio Code.
Objets de niveau supérieur définis dans le schéma HCN
Les objets de niveau supérieur sont les suivants :
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[];
};
Étapes suivantes
En savoir plus sur les scénarios HCN courants.
En savoir plus sur les handles de contexte RPC pour HCN.
En savoir plus sur les schémas de document JSON HCN.