API del servicio Host Compute Network (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. Juntos, esto proporciona conectividad y seguridad para las máquinas virtuales (VM) y los contenedores que se ejecutan en Windows host.

Los desarrolladores usan la API del servicio HCN para administrar redes para máquinas virtuales y 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 HCN Service API

  • Se implementa como API de C hospedada por el servicio de red 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 los identificadores de los objetos (por ejemplo, un identificador de red) y internamente estos identificadores se implementan mediante identificadores de contexto RPC.

  • Basado en esquemas. La mayoría de las funciones de la API definen 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 con tipo y con versiones, 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 de todo el servicio, como creaciones y eliminaciones de red.

  • HCN API funciona en aplicaciones Puente de dispositivo de escritorio (también llamada 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 están en 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 solo equipo físico. Se denomina para seguir la terminología del sector.

  • El host se usa ampliamente en el sector de virtualización para hacer referencia al sistema operativo que proporciona recursos virtualizados.

  • El proceso se usa para hacer referencia a 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 solo 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 normalización de definiciones de esquema específicas para los esquemas usados para los 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 hacia y desde representaciones nativas de estos esquemas en los lenguajes de programación usados por los autores de llamada de las API

Las definiciones de esquema usadas con frecuencia son OpenAPI y esquema JSON,que le permiten 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, tenemos previsto publicar el esquema de nuestros documentos JSON como una especificación de OpenAPI. Según 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 con el control de versiones para las definiciones de esquema. A partir de esta definición interna, generamos 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 usar herramientas, como Swagger,para generar representaciones específicas del lenguaje del lenguaje de programación de esquema que usa un cliente. Swagger admite una variedad de lenguajes, como C#, Go, Javascript y Python.

  • Ejemplo de código de C# generado para el objeto de nivel superior IPAM subnet.

  • Ejemplo de código Go generado para el nivel superior IPAM subnet. 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 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