Compartilhar via

API do serviço HCN (Rede de Computação de Host) para VMs e contêineres

A API de serviço da HCN (Rede de Computação de Host) é uma API do Win32 que fornece acesso no nível da plataforma para gerenciar as redes virtuais, pontos de extremidade virtuais e políticas associadas. Juntos, isso fornece conectividade e segurança para VMs (máquinas virtuais) e contêineres em execução em um host do Windows.

Os desenvolvedores usam a API do serviço HCN para gerenciar redes de VMs e contêineres em seus fluxos de trabalho de aplicativo. A API do HCN foi projetada para fornecer a melhor experiência para desenvolvedores. Os usuários finais não interagem diretamente com essas APIs.

Recursos da API do serviço HCN

  • Implementada como API C hospedada pelo HNS (Serviço de Rede de Host) no OnCore/VM.

  • Fornece a capacidade de criar, modificar, excluir e enumerar objetos HCN, como redes, pontos de extremidade, namespaces e políticas. As operações são executadas em identificadores para os objetos (por exemplo, um identificador de rede). Internamente, esses identificadores são implementados usando identificadores de contexto RPC.

  • Baseado em esquema. A maioria das funções da API define parâmetros de entrada e saída como cadeias de caracteres que contêm os argumentos da chamada de função como documentos JSON. Os documentos JSON baseiam-se em esquemas fortemente tipados e com versão. Esses esquemas fazem parte da documentação pública.

  • Uma API de assinatura/retorno de chamada é fornecida para permitir que os clientes se registrem para notificações de eventos em todo o serviço, como criações e exclusões de rede.

  • A API do HCN funciona em aplicativos Ponte de Desktop (também conhecidos como Centennial) em execução nos serviços do sistema. A API verifica a ACL recuperando o token de usuário do chamador.

Dica

A API do serviço HCN tem suporte nas tarefas em segundo plano e nas janelas que não estão em primeiro plano.

Terminologia: comparação entre host e computação

O serviço de computação de host permite que os chamadores criem e gerenciem máquinas virtuais e contêineres em um único computador físico. Ele é nomeado para seguir a terminologia do setor.

  • Host é amplamente usado no setor de virtualização para se referir ao sistema operacional que fornece recursos virtualizados.

  • Computação é usada para se referir a métodos de virtualização mais amplos do que apenas máquinas virtuais. O Serviço de Rede de Computação de Host permite que os chamadores criem e gerenciem redes em máquinas virtuais e no contêiner em um único computador físico.

Documentos de configuração baseados em esquema

Os documentos de configuração baseados em esquemas bem definidos são um padrão estabelecido do setor no espaço de virtualização. A maioria das soluções de virtualização, como Docker e Kubernetes, fornece APIs de acordo com os documentos de configuração. Várias iniciativas do setor, com a participação da Microsoft, impulsionam um ecossistema para definir e validar esses esquemas, como OpenAPI. Essas iniciativas também impulsionam a padronização de definições de esquema específicas para os esquemas usados em contêineres, como OCI (Open Container Initiative).

A linguagem usada para criar documentos de configuração é JSON, que você usa em combinação com:

  • Definições de esquema que definem um modelo de objeto para o documento
  • Validação se um documento JSON está em conformidade com um esquema
  • Conversão automatizada de documentos JSON em e de representações nativas desses esquemas nas linguagens de programação usadas pelos chamadores das APIs

As definições de esquema usadas com frequência são OpenAPI e Esquema JSON, o que permite especificar as definições detalhadas das propriedades em um documento, por exemplo:

  • O conjunto válido de valores para uma propriedade, como 0-100 para uma propriedade que representa uma porcentagem.
  • A definição de enumerações, que são representadas como um conjunto de cadeias de caracteres válidas para uma propriedade.
  • Uma expressão regular para o formato esperado de uma cadeia de caracteres.

Como parte da documentação das APIs do HCN, estamos planejando publicar o esquema de nossos documentos JSON como uma Especificação OpenAPI. De acordo com essa especificação, representações específicas de linguagem do esquema podem permitir o uso seguro de tipo dos objetos de esquema na linguagem de programação usada pelo cliente.

Exemplo

Veja a seguir um exemplo desse fluxo de trabalho para o objeto que representa um controlador SCSI no documento de configuração de uma VM.

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;
};

Dica

As anotações [NewIn("2.0") fazem parte do suporte de controle de versão para as definições de esquema. Nessa definição interna, geramos as especificações OpenAPI para o 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"
                }
            }
        }
    }
}

Você pode usar ferramentas, como Swagger, para gerar representações específicas da linguagem de programação de esquema usada por um cliente. O Swagger é compatível com várias linguagens, como C#, Go, Javascript e Python.

  • Exemplo de código C# gerado para o IPAM de nível superior e objeto de sub-rede.

  • Exemplo de código do Go gerado para o IPAM de nível superior e objeto de sub-rede. O Go é usado pelo Docker e Kubernetes, que são dois dos consumidores das APIs do Serviço de Rede de Computação de Host. O Go tem suporte interno para marshaling de tipos Go de e para documentos JSON.

Além da geração e validação de código, você pode usar ferramentas para simplificar o trabalho com documentos JSON, ou seja, Visual Studio Code.

Objetos de nível superior definidos no esquema HCN

Os objetos de nível superior são:

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[];
};

Próximas etapas