API del servizio HCN (Host Compute Network) per macchine virtuali e contenitori
L'API del servizio HCN (Host Compute Network) è un'API Win32 pubblica che fornisce l'accesso a livello di piattaforma per gestire le reti virtuali, gli endpoint di rete virtuale e i criteri associati. Insieme, offre connettività e sicurezza per le macchine virtuali (VM) e i contenitori in esecuzione in un host Windows.
Gli sviluppatori usano l'API del servizio HCN per gestire la rete per macchine virtuali e contenitori nei flussi di lavoro dell'applicazione. L'API HCN è stata progettata per offrire un'esperienza ottimale per gli sviluppatori. Gli utenti finali non interagiscono direttamente con queste API.
Funzionalità dell'API del servizio HCN
Implementato come API C ospitata dal servizio di rete host (HNS) in OnCore/VM.
Consente di creare, modificare, eliminare ed enumerare oggetti HCN, ad esempio reti, endpoint, spazi dei nomi e criteri. Le operazioni eseguite sugli handle per gli oggetti (ad esempio, un handle di rete) e internamente questi handle vengono implementati usando handle di contesto RPC.
Basato sullo schema. La maggior parte delle funzioni dell'API definisce parametri di input e output come stringhe contenenti gli argomenti della chiamata di funzione come documenti JSON. I documenti JSON sono basati su schemi fortemente tipizzato e con controllo delle versioni, questi schemi fanno parte della documentazione pubblica.
Viene fornita un'API di sottoscrizione/callback per consentire ai client di registrarsi per le notifiche di eventi a livello di servizio, ad esempio creazioni di rete ed eliminazioni.
L'API HCN funziona nelle app Desktop Bridge (k.a. Centennial) in esecuzione nei servizi di sistema. L'API controlla l'ACL recuperando il token utente dal chiamante.
Suggerimento
L'API del servizio HCN è supportata nelle attività in background e nelle finestre non in primo piano.
Terminologia: host e calcolo
Il servizio di calcolo host consente ai chiamanti di creare e gestire sia macchine virtuali che contenitori in un singolo computer fisico. È denominato per seguire la terminologia del settore.
L'host è ampiamente usato nel settore della virtualizzazione per fare riferimento al sistema operativo che fornisce risorse virtualizzate.
L'ambiente di calcolo viene usato per fare riferimento a metodi di virtualizzazione più ampi rispetto alle sole macchine virtuali. Il servizio di rete ambiente di calcolo host consente ai chiamanti di creare e gestire la rete per macchine virtuali e contenitori in un singolo computer fisico.
Documenti di configurazione basati su schema
I documenti di configurazione basati su schemi ben definiti sono uno standard di settore definito nello spazio di virtualizzazione. La maggior parte delle soluzioni di virtualizzazione, ad esempio Docker e Kubernetes, offre API basate sui documenti di configurazione. Diverse iniziative del settore, con la partecipazione di Microsoft, guidano un ecosistema per la definizione e la convalida di questi schemi, ad esempio OpenAPI. Queste iniziative determinano anche la standardizzazione di definizioni di schemi specifiche per gli schemi usati per i contenitori, ad esempio Open Container Initiative (OCI).
Il linguaggio usato per la creazione di documenti di configurazione è JSON, che viene usato in combinazione con:
- Definizioni di schema che definiscono un modello a oggetti per il documento
- Convalida del fatto che un documento JSON sia conforme a uno schema
- Conversione automatica di documenti JSON da e verso rappresentazioni native di questi schemi nei linguaggi di programmazione usati dai chiamanti delle API
Le definizioni di schema usate di frequente sono OpenAPI e JSON Schema, che consente di specificare le definizioni dettagliate delle proprietà in un documento, ad esempio:
- Set di valori valido per una proprietà, ad esempio 0-100 per una proprietà che rappresenta una percentuale.
- Definizione di enumerazioni, rappresentate come un set di stringhe valide per una proprietà.
- Espressione regolare per il formato previsto di una stringa.
Nell'ambito della documentazione delle API HCN, si prevede di pubblicare lo schema dei documenti JSON come specifica OpenAPI. In base a questa specifica, le rappresentazioni specifiche del linguaggio dello schema possono consentire l'uso indipendente dai tipi degli oggetti dello schema nel linguaggio di programmazione usato dal client.
Esempio
Di seguito è riportato un esempio di questo flusso di lavoro per l'oggetto che rappresenta un controller SCSI nel documento di configurazione di una macchina virtuale.
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;
};
Suggerimento
Le annotazioni [NewIn("2.0") fanno parte del supporto del controllo delle versioni per le definizioni dello schema. Da questa definizione interna, vengono generate le specifiche OpenAPI per lo schema:
{
"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"
}
}
}
}
}
È possibile usare strumenti, ad esempio Swagger, per generare rappresentazioni specifiche del linguaggio del linguaggio di programmazione dello schema usato da un client. Swagger supporta un'ampia gamma di linguaggi, ad esempio C#, Go, Javascript e Python.
Esempio di codice C# generato per l'oggetto IPAM & Subnet di primo livello.
Esempio di codice Go generato per l'oggetto IPAM & Subnet di primo livello. Go viene usato da Docker e Kubernetes, due dei consumer delle API del servizio di rete di calcolo host. Go include il supporto predefinito per il marshalling dei tipi Go da e verso i documenti JSON.
Oltre alla generazione e alla convalida del codice, è possibile usare strumenti per semplificare l'uso di documenti JSON, ovvero Visual Studio Code.
Oggetti di primo livello definiti nello schema HCN
Gli oggetti di primo livello sono:
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[];
};
Passaggi successivi
Maggiori informazioni sugli scenari HCN comuni.
Maggiori informazioni sugli handle di contesto RPC per HCN.
Maggiori informazioni sugli schemi di documento JSON HCN.