API layanan Host Compute Network (HCN) untuk VM dan kontainer
Berlaku untuk: Windows Server 2022, Windows Server 2019
API layanan Host Compute Network (HCN) adalah API Win32 yang menghadap publik yang menyediakan akses tingkat platform untuk mengelola jaringan virtual, titik akhir jaringan virtual, dan kebijakan terkait. Bersama-sama ini menyediakan konektivitas dan keamanan untuk komputer virtual (VM) dan kontainer yang berjalan pada host Windows.
Pengembang menggunakan API layanan HCN untuk mengelola jaringan untuk VM dan kontainer dalam alur kerja aplikasi mereka. API HCN telah dirancang untuk memberikan pengalaman terbaik bagi pengembang. Pengguna akhir tidak berinteraksi dengan API ini secara langsung.
Fitur API Layanan HCN
Diimplementasikan sebagai C API yang dihosting oleh Host Network Service (HNS) pada OnCore/VM.
Menyediakan kemampuan untuk membuat, memodifikasi, menghapus, dan menghitung objek HCN seperti jaringan, titik akhir, namespace layanan, dan kebijakan. Operasi dilakukan pada handel ke objek (misalnya, handel jaringan), dan secara internal handel ini diimplementasikan menggunakan handel konteks RPC.
Berbasis skema. Sebagian besar fungsi API menentukan parameter input dan output sebagai string yang berisi argumen panggilan fungsi sebagai dokumen JSON. Dokumen JSON didasarkan pada skema yang diketik dan diberi versi yang kuat, skema ini adalah bagian dari dokumentasi publik.
API langganan/panggilan balik disediakan untuk memungkinkan klien mendaftar untuk pemberitahuan peristiwa di seluruh layanan seperti pembuatan dan penghapusan jaringan.
HCN API berfungsi di aplikasi Desktop Bridge (alias Centennial) yang berjalan di layanan sistem. API memeriksa ACL dengan mengambil token pengguna dari pemanggil.
Tip
API layanan HCN didukung dalam tugas latar belakang dan jendela non-latar depan.
Terminologi: Host vs. Komputasi
Layanan komputasi host memungkinkan penelepon untuk membuat dan mengelola komputer virtual dan kontainer pada satu komputer fisik. Ini dinamai untuk mengikuti terminologi industri.
Host banyak digunakan dalam industri virtualisasi untuk merujuk ke sistem operasi yang menyediakan sumber daya virtual.
Komputasi digunakan untuk merujuk ke metode virtualisasi yang lebih luas dari sekadar komputer virtual. Layanan Jaringan Komputasi Host memungkinkan penelepon untuk membuat dan mengelola jaringan untuk komputer virtual dan kontainer pada satu komputer fisik.
Dokumen konfigurasi berbasis skema
Dokumen konfigurasi berdasarkan skema yang ditentukan dengan baik adalah standar industri yang mapan di ruang virtualisasi. Sebagian besar solusi virtualisasi, seperti Docker dan Kubernetes, menyediakan API berdasarkan dokumen konfigurasi. Beberapa inisiatif industri, dengan partisipasi Microsoft, mendorong ekosistem untuk menentukan dan memvalidasi skema ini, seperti OpenAPI. Inisiatif ini juga mendorong standarisasi definisi skema tertentu untuk skema yang digunakan untuk kontainer, seperti Open Container Initiative (OCI).
Bahasa yang digunakan untuk menulis dokumen konfigurasi adalah JSON, yang Anda gunakan dalam kombinasi dengan:
- Definisi skema yang menentukan model objek untuk dokumen
- Validasi apakah dokumen JSON sesuai dengan skema
- Konversi otomatis dokumen JSON ke dan dari representasi asli skema ini dalam bahasa pemrograman yang digunakan oleh pemanggil API
Definisi skema yang sering digunakan adalah OpenAPI dan JSON Schema, yang memungkinkan Anda menentukan definisi terperinci properti dalam dokumen, misalnya:
- Kumpulan nilai yang valid untuk properti, seperti 0-100 untuk properti yang mewakili persentase.
- Definisi enumerasi, yang direpresentasikan sebagai sekumpulan string yang valid untuk properti.
- Ekspresi reguler untuk format string yang diharapkan.
Sebagai bagian dari mendokumentasikan API HCN, kami berencana untuk menerbitkan skema dokumen JSON kami sebagai Spesifikasi OpenAPI. Berdasarkan spesifikasi ini, representasi khusus bahasa dari skema dapat memungkinkan penggunaan objek skema yang aman untuk jenis dalam bahasa pemrograman yang digunakan oleh klien.
Contoh
Berikut ini adalah contoh alur kerja ini untuk objek yang mewakili pengontrol SCSI dalam dokumen konfigurasi 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;
};
Tip
Anotasi [NewIn("2.0") adalah bagian dari dukungan penerapan versi untuk definisi skema. Dari definisi internal ini, kami menghasilkan spesifikasi OpenAPI untuk skema:
{
"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"
}
}
}
}
}
Anda dapat menggunakan alat, seperti Swagger, untuk menghasilkan representasi khusus bahasa dari bahasa pemrograman skema yang digunakan oleh klien. Swagger mendukung berbagai bahasa seperti C#, Go, Javascript, dan Python).
Contoh kode C# yang dihasilkan untuk ipam tingkat atas & objek Subnet.
Contoh kode Go yang dihasilkan untuk objek IPAM &Subnet tingkat atas. Go digunakan oleh Docker dan Kubernetes yang merupakan dua dari konsumen API Layanan Jaringan Komputasi Host. Go memiliki dukungan bawaan untuk jenis Marshaling Go ke dan dari dokumen JSON.
Selain pembuatan dan validasi kode, Anda dapat menggunakan alat untuk menyederhanakan pekerjaan dengan dokumen JSON—yaitu Visual Studio Code.
Objek tingkat atas yang ditentukan dalam skema HCN
Objek tingkat atas adalah:
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[];
};
Langkah berikutnya
Pelajari selengkapnya tentang skenario HCN umum.
Pelajari selengkapnya tentang handel konteks RPC untuk HCN.
Pelajari selengkapnya tentang skema dokumen JSON HCN.