API de servicio de red de proceso de host (HCN) para máquinas virtuales y contenedores
Se aplica a: Windows Server 2022, Windows Server 2019
La API de servicio de red de proceso de host (HCN) es una API de Win32 orientada al público que proporciona acceso de nivel de plataforma para administrar redes virtuales, puntos de conexión de red virtual y directivas asociadas. Esto proporciona conectividad y seguridad para máquinas virtuales (VM) y contenedores que se ejecutan en un host de Windows.
Los desarrolladores usan la API de servicio HCN para administrar las redes de las máquinas virtuales y los contenedores en sus flujos de trabajo de aplicación. La API de HCN se ha diseñado para proporcionar la mejor experiencia para los desarrolladores. Los usuarios finales no interactúan directamente con estas API.
Características de la API del servicio HCN
Se implementa como API de C hospedada por el servicio de red de host (HNS) en OnCore/VM.
Proporciona la capacidad de crear, modificar, eliminar y enumerar objetos HCN, como redes, puntos de conexión, espacios de nombres y directivas. Las operaciones se realizan en identificadores para los objetos (por ejemplo, un identificador de red) e, internamente, estos identificadores se implementan mediante identificadores de contexto RPC.
Basado en esquemas. La mayoría de las funciones de la API definen los parámetros de entrada y salida como cadenas que contienen los argumentos de la llamada de función como documentos JSON. Los documentos JSON se basan en esquemas fuertemente tipados y versionados, estos esquemas forman parte de la documentación pública.
Se proporciona una API de suscripción o devolución de llamada para permitir que los clientes se registren para recibir notificaciones de eventos en todo el servicio, como las creaciones y eliminaciones de red.
LA API de HCN funciona en aplicaciones de Puente de dispositivo de escritorio (p.ej., Centennial) que se ejecutan en servicios del sistema. La API comprueba la ACL recuperando el token de usuario del autor de la llamada.
Sugerencia
La API del servicio HCN se admite en tareas en segundo plano y ventanas que no son de primer plano.
Terminología: host frente a proceso
El servicio de proceso de host permite a los autores de llamadas crear y administrar máquinas virtuales y contenedores en un único equipo físico. Se denomina para seguir la terminología del sector.
Host se usa ampliamente en el sector de la virtualización para hacer referencia al sistema operativo que proporciona recursos virtualizados.
Proceso se usa para hacer referencia a los métodos de virtualización que son más amplios que solo las máquinas virtuales. El servicio de red de proceso de host permite a los autores de llamadas crear y administrar redes para máquinas virtuales y contenedores en un único equipo físico.
Documentos de configuración basados en esquemas
Los documentos de configuración basados en esquemas bien definidos son un estándar del sector establecido en el espacio de virtualización. La mayoría de las soluciones de virtualización, como Docker y Kubernetes, proporcionan API basadas en documentos de configuración. Varias iniciativas del sector, con la participación de Microsoft, impulsan un ecosistema para definir y validar estos esquemas, como OpenAPI. Estas iniciativas también impulsan la estandarización de definiciones de esquema específicas para los esquemas usados para contenedores, como Open Container Initiative (OCI).
El lenguaje que se usa para crear documentos de configuración es JSON, que se usa en combinación con:
- Definiciones de esquema que definen un modelo de objetos para el documento
- Validación de si un documento JSON se ajusta a un esquema
- Conversión automatizada de documentos JSON a y desde representaciones nativas de estos esquemas en los lenguajes de programación usados por los autores de llamadas de las API
Las definiciones de esquema usadas con frecuencia son OpenAPI y esquema JSON, lo que le permite especificar las definiciones detalladas de las propiedades de un documento, por ejemplo:
- Conjunto válido de valores para una propiedad, como 0-100 para una propiedad que representa un porcentaje.
- Definición de enumeraciones, que se representan como un conjunto de cadenas válidas para una propiedad.
- Expresión regular para el formato esperado de una cadena.
Como parte de la documentación de las API de HCN, estamos planeando publicar el esquema de nuestros documentos JSON como una especificación de OpenAPI. En función de esta especificación, las representaciones específicas del lenguaje del esquema pueden permitir el uso seguro de tipos de los objetos de esquema en el lenguaje de programación utilizado por el cliente.
Ejemplo
A continuación se muestra un ejemplo de este flujo de trabajo para el objeto que representa un controlador SCSI en el documento de configuración de una máquina virtual.
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;
};
Sugerencia
Las anotaciones [NewIn("2.0") forman parte de la compatibilidad de control de versiones con las definiciones de esquema. A partir de esta definición interna, se generan las especificaciones de OpenAPI para el esquema:
{
"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"
}
}
}
}
}
Puede utilizar herramientas, como Swagger, para generar representaciones específicas del lenguaje de programación del esquema utilizado por un cliente. Swagger admite una variedad de lenguajes como C#, Go, Javascript y Python).
Ejemplo de código de C# generado para el objeto IPAM y subred de nivel superior
Ejemplo de código de Go generado para el objeto IPAM y subred de nivel superior. Docker y Kubernetes usan Go, que son dos de los consumidores de las API del servicio de red de proceso de host. Go tiene compatibilidad integrada para serializar tipos de Go hacia y desde documentos JSON.
Además de la generación y validación de código, puede usar herramientas para simplificar el trabajo con documentos JSON, es decir, Visual Studio Code.
Objetos de nivel superior definidos en el esquema HCN
Los objetos de nivel superior son:
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[];
};
Pasos siguientes
Obtenga más información sobre los escenarios comunes de HCN.
Obtenga más información sobre los identificadores de contexto RPC para HCN.
Obtenga más información sobre los esquemas de documentos JSON de HCN.