VM 및 컨테이너용 HCN(Host Compute Network) 서비스 API
적용 대상: Windows Server 2022, Windows Server 2019
HCN(호스트 컴퓨팅 네트워크) 서비스 API는 가상 네트워크, 가상 네트워크 엔드포인트 및 관련 정책을 관리하기 위한 플랫폼 수준 액세스를 제공하는 공용 Win32 API입니다. 이를 통해 Windows 호스트에서 실행되는 VM(가상 머신) 및 컨테이너에 대한 연결 및 보안을 제공합니다.
개발자는 HCN 서비스 API를 사용하여 애플리케이션 워크플로에서 VM 및 컨테이너에 대한 네트워킹을 관리합니다. HCN API는 개발자에게 최상의 환경을 제공하도록 설계되었습니다. 최종 사용자는 이러한 API와 직접 상호 작용하지 않습니다.
HCN 서비스 API의 기능
OnCore/VM의 HNS(호스트 네트워크 서비스)에서 호스트하는 C API로 구현됩니다.
네트워크, 엔드포인트, 네임스페이스 및 정책과 같은 HCN 개체를 만들고, 수정하고, 삭제하고, 열거하는 기능을 제공합니다. 작업은 개체(예: 네트워크 핸들)에 대한 핸들에서 수행되며 내부적으로 이러한 핸들은 RPC 컨텍스트 핸들을 사용하여 구현됩니다.
스키마 기반. API의 대부분의 함수는 입력 및 출력 매개 변수를 JSON 문서로 함수 호출의 인수를 포함하는 문자열로 정의합니다. JSON 문서는 강력한 형식의 스키마와 버전이 지정된 스키마를 기반으로 하며, 이러한 스키마는 공용 설명서의 일부입니다.
클라이언트가 네트워크 생성 및 삭제와 같은 서비스 전체 이벤트의 알림을 등록할 수 있도록 구독/콜백 API가 제공됩니다.
HCN API는 시스템 서비스에서 실행되는 데스크톱 브리지(즉, Centennial) 앱에서 작동합니다. API는 호출자에서 사용자 토큰을 검색하여 ACL을 검사.
팁
HCN 서비스 API는 백그라운드 작업 및 포그라운드가 아닌 창에서 지원됩니다.
용어: 호스트 및 컴퓨팅
호스트 컴퓨팅 서비스를 사용하면 호출자가 단일 물리적 컴퓨터에서 가상 머신과 컨테이너를 모두 만들고 관리할 수 있습니다. 업계 용어를 따르도록 명명되었습니다.
호스트 는 가상화 업계에서 가상화된 리소스를 제공하는 운영 체제를 참조하는 데 널리 사용됩니다.
컴퓨팅은 가상 머신보다 더 광범위한 가상화 메서드를 참조하는 데 사용됩니다. Host Compute Network Service를 사용하면 호출자가 단일 물리적 컴퓨터에서 가상 머신과 컨테이너 모두에 대한 네트워킹을 만들고 관리할 수 있습니다.
스키마 기반 구성 문서
잘 정의된 스키마를 기반으로 하는 구성 문서는 가상화 공간에서 확립된 업계 표준입니다. Docker 및 Kubernetes와 같은 대부분의 가상화 솔루션은 구성 문서를 기반으로 API를 제공합니다. Microsoft가 참여하는 여러 업계 이니셔티브는 OpenAPI와 같은 이러한 스키마를 정의하고 유효성을 검사하기 위한 에코시스템을 추진합니다. 또한 이러한 이니셔티브는 OCI(Open Container Initiative)와 같은 컨테이너에 사용되는 스키마에 대한 특정 스키마 정의의 표준화를 추진합니다.
구성 문서를 작성하는 데 사용되는 언어는 다음과 함께 사용하는 JSON입니다.
- 문서의 개체 모델을 정의하는 스키마 정의
- JSON 문서가 스키마를 준수하는지 여부의 유효성 검사
- API 호출자가 사용하는 프로그래밍 언어로 이러한 스키마의 네이티브 표현과 JSON 문서를 자동으로 변환합니다.
자주 사용되는 스키마 정의는 OpenAPI 및 JSON 스키마로, 문서의 속성에 대한 자세한 정의를 지정할 수 있습니다. 예를 들면 다음과 같습니다.
- 백분율을 나타내는 속성의 경우 0-100과 같이 속성의 유효한 값 집합입니다.
- 속성에 유효한 문자열 집합으로 표현되는 열거형의 정의입니다.
- 문자열의 예상 형식에 대한 정규식입니다.
HCN API를 문서화하는 과정의 일환으로 JSON 문서의 스키마를 OpenAPI 사양으로 게시할 계획입니다. 이 사양에 따라 스키마의 언어별 표현을 사용하면 클라이언트에서 사용하는 프로그래밍 언어로 스키마 개체를 형식이 안전하게 사용할 수 있습니다.
예시
다음은 VM의 구성 문서에서 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과 같은 다양한 언어를 지원합니다.
최상위 IPAM 및 서브넷 개체에 대해 생성된 C# 코드 의 예입니다.
최상위 IPAM 및 서브넷 개체에 대해 생성된 Go 코드 의 예입니다. Go는 호스트 컴퓨팅 네트워크 서비스 API의 두 소비자인 Docker 및 Kubernetes에서 사용됩니다. 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 시나리오에 대해 자세히 알아봅니다.
HCN에 대한 RPC 컨텍스트 핸들에 대해 자세히 알아봅니다.
HCN JSON 문서 스키마에 대해 자세히 알아봅니다.