API do serviço HCN (Rede de Computação de Host) para VMs e contêineres
Aplica-se a: Windows Server 2022, Windows Server 2019
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
Saiba mais sobre os cenários comuns de HCN.
Saiba mais sobre os identificadores de contexto RPC para HCN.
Saiba mais sobre os esquemas de documento JSON da HCN.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de