API-интерфейс службы вычислительной сети узла (HCN) для виртуальных машин и контейнеров
Область применения: Windows Server 2022, Windows Server 2019
API службы "Вычислительная сеть узла" (HCN) — это общедоступный API Win32, который предоставляет доступ на уровне платформы для управления виртуальными сетями, конечными точками виртуальных сетей и связанными с ними политиками. Вместе это обеспечивает подключение и безопасность для виртуальных машин и контейнеров, работающих на узле Windows.
Разработчики используют API службы HCN для управления сетями для виртуальных машин и контейнеров в рабочих процессах приложений. API HCN разработан для обеспечения оптимального интерфейса для разработчиков. Конечные пользователи не взаимодействуют с этими API напрямую.
Функции API службы HCN
Реализован как API C, размещенный службой сети узла (HNS) в onCore/VM.
Предоставляет возможность создавать, изменять, удалять и перечислять объекты HCN, такие как сети, конечные точки, пространства имен и политики. Операции выполняются с дескрипторами объектов (например, сетевой дескриптор), а внутренние эти дескрипторы реализуются с помощью дескрипторов контекста RPC.
На основе схемы. Большинство функций API определяют входные и выходные параметры в виде строк, содержащих аргументы вызова функции в виде документов JSON. Документы JSON основаны на строго типизированных и версиях схем, эти схемы являются частью общедоступной документации.
Api обратного вызова подписки и обратного вызова предоставляется для того, чтобы клиенты могли регистрировать уведомления о событиях на уровне службы, таких как создание сети и удаление.
API HCN работает в мост для классических приложений приложениях (a.a. Centennial), работающих в системных службах. API проверка ACL, извлекая маркер пользователя из вызывающего средства.
Совет
API службы HCN поддерживается в фоновых задачах и окнах, отличных от переднего плана.
Терминология: узел и вычисления
Служба вычислений узла позволяет вызывающим пользователям создавать виртуальные машины и контейнеры на одном физическом компьютере и управлять ими. Оно называется для того, чтобы следовать терминологии отрасли.
Узел широко используется в отрасли виртуализации для ссылки на операционную систему, которая предоставляет виртуализированные ресурсы.
Вычисления используются для ссылки на методы виртуализации, которые являются более широкими, чем только виртуальные машины. Служба вычислительной сети узла позволяет вызывающим пользователям создавать сети и управлять ими для виртуальных машин и контейнеров на одном физическом компьютере.
Документы конфигурации на основе схемы
Документы конфигурации на основе четко определенных схем — это стандартный отраслевый стандарт в пространстве виртуализации. Большинство решений виртуализации, таких как Docker и Kubernetes, предоставляют API на основе документов конфигурации. Некоторые отраслевые инициативы, с участием Корпорации Майкрософт, управляют экосистемой для определения и проверки этих схем, таких как OpenAPI. Эти инициативы также управляют стандартизацией конкретных определений схем для схем, используемых для контейнеров, таких как Open Container Initiative (OCI).
Язык, используемый для разработки документов конфигурации, — JSON, который используется в сочетании с:
- Определения схемы, определяющие объектную модель для документа
- Проверка соответствия документа JSON схеме
- Автоматическое преобразование документов JSON в собственные представления этих схем на языках программирования, используемых вызывающими API
Часто используемые определения схем : OpenAPI и JSON Schema, что позволяет указать подробные определения свойств в документе, например:
- Допустимый набор значений для свойства, например 0–100 для свойства, представляющего процент.
- Определение перечислений, представленных как набор допустимых строк для свойства.
- Регулярное выражение ожидаемого формата строки.
В рамках документирования API HCN мы планируем опубликовать схему наших документов JSON в качестве спецификации OpenAPI. На основе этой спецификации представления схемы на языке, зависящие от языка, могут позволить типобезопасно использовать объекты схемы на языке программирования, используемом клиентом.
Пример
Ниже приведен пример этого рабочего процесса для объекта, представляющего контроллер SCSI в документе конфигурации виртуальной машины.
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;
};
Совет
Заметки [NewIn("2.0") являются частью поддержки управления версиями для определений схем. Из этого внутреннего определения мы создадим спецификации OpenAPI для схемы:
{
"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"
}
}
}
}
}
Вы можете использовать такие средства, как Swagger, для создания представлений языка программирования схемы, используемого клиентом. Swagger поддерживает различные языки, такие как C#, Go, Javascript и Python).
Пример созданного кода C# для объекта IPAM и подсети верхнего уровня.
Пример созданного кода Go для объекта IPAM верхнего уровня и подсети. Go используется Docker и Kubernetes, которые являются двумя потребителями API-интерфейсов службы вычислительной сети узла. Go имеет встроенную поддержку маршалинг типов Go в документы JSON и из него.
Помимо создания и проверки кода можно использовать средства для упрощения работы с документами JSON, то есть Visual Studio Code.
Объекты верхнего уровня, определенные в схеме HCN
Объекты верхнего уровня:
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[];
};
Следующие шаги
Дополнительные сведения о распространенных сценариях HCN.
Дополнительные сведения о дескрипторах контекста RPC для HCN.
Дополнительные сведения о схемах документов JSON HCN.