Dela via

Api för värdbaserad beräkningsnätverkstjänst (HCN) för virtuella datorer och containrar

HCN-tjänst-API (Host Compute Network) är ett offentligt Win32-API som ger åtkomst på plattformsnivå för att hantera virtuella nätverk, virtuella nätverksslutpunkter och associerade principer. Tillsammans ger detta anslutning och säkerhet för virtuella datorer (VM) och containrar som körs på en Windows-värd.

Utvecklare använder HCN-tjänst-API:et för att hantera nätverk för virtuella datorer och containrar i sina programarbetsflöden. HCN-API:et har utformats för att ge utvecklare bästa möjliga upplevelse. Slutanvändarna interagerar inte direkt med dessa API:er.

Funktioner i HCN-tjänst-API:et

  • Implementerad som C-API som värdhanteras av värdnätverkstjänsten (HNS) på OnCore/VM.

  • Ger möjlighet att skapa, ändra, ta bort och räkna upp HCN-objekt som nätverk, slutpunkter, namnområden och principer. Åtgärder utförs på handtag till objekten (t.ex. ett nätverkshandtag), och internt implementeras dessa handtag med RPC-kontexthandtag.

  • Schemabaserat. De flesta funktioner i API:et definierar indata- och utdataparametrar som strängar som innehåller argumenten för funktionsanropet som JSON-dokument. JSON-dokumenten baseras på starkt inskrivna och versionsbaserade scheman. Dessa scheman är en del av den offentliga dokumentationen.

  • En prenumerations-/motringnings-API tillhandahålls för att klienter ska kunna registrera sig för meddelanden om tjänstomfattande händelser, till exempel nätverksskapanden och borttagningar.

  • HCN-API:et fungerar i Desktop Bridge-appar (till.k.a. Centennial) som körs i systemtjänster. API:et kontrollerar ACL:n genom att hämta användartoken från anroparen.

Tips/Råd

HCN-tjänstens API stöds i bakgrundsaktiviteter och i fönster som inte är i förgrunden.

Terminologi: Värd kontra datorkapacitet

Med värdberäkningstjänsten kan anropare skapa och hantera både virtuella datorer och containrar på en enda fysisk dator. Den är namngiven för att följa branschens terminologi.

  • Värden används ofta i virtualiseringsindustrin för att syfta på operativsystemet som tillhandahåller virtualiserade resurser.

  • Beräkning används för att referera till virtualiseringsmetoder som är bredare än bara virtuella datorer. Med Host Compute Network Service kan anropare skapa och hantera nätverk för både virtuella datorer och containrar på en enda fysisk dator.

Schemabaserade konfigurationsdokument

Konfigurationsdokument baserade på väldefinierade scheman är en etablerad branschstandard i virtualiseringsutrymmet. De flesta virtualiseringslösningar, till exempel Docker och Kubernetes, tillhandahåller API:er baserat på konfigurationsdokument. Flera branschinitiativ, med Microsofts deltagande, driver ett ekosystem för att definiera och validera dessa scheman, till exempel OpenAPI. Dessa initiativ styr också standardiseringen av specifika schemadefinitioner för de scheman som används för containrar, till exempel Open Container Initiative (OCI).

Det språk som används för att redigera konfigurationsdokument är JSON, som du använder i kombination med:

  • Schemadefinitioner som definierar en objektmodell för dokumentet
  • Verifiering av om ett JSON-dokument överensstämmer med ett schema
  • Automatisk konvertering av JSON-dokument till och från interna representationer av dessa scheman på de programmeringsspråk som används av api:ernas anropare

Schemadefinitioner som används ofta är OpenAPI och JSON-schema, vilket gör att du kan ange detaljerade definitioner av egenskaperna i ett dokument, till exempel:

  • Den giltiga uppsättningen värden för en egenskap, till exempel 0–100 för en egenskap som representerar en procentandel.
  • Definitionen av uppräkningar, som representeras som en uppsättning giltiga strängar för en egenskap.
  • Ett reguljärt uttryck för det förväntade formatet för en sträng.

Som en del av dokumentationen av HCN-API:erna planerar vi att publicera schemat för våra JSON-dokument som en OpenAPI-specifikation. Baserat på den här specifikationen kan språkspecifika representationer av schemat tillåta typsäker användning av schemaobjekten på det programmeringsspråk som används av klienten.

Exempel

Följande är ett exempel på det här arbetsflödet för objektet som representerar en SCSI-styrenhet i konfigurationsdokumentet för en virtuell dator.

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;
};

Tips/Råd

Anteckningarna [NewIn("2.0") ingår i versionsstödet för schemadefinitionerna. Från den här interna definitionen genererar vi OpenAPI-specifikationerna för schemat:

{
    "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"
                }
            }
        }
    }
}

Du kan använda verktyg, till exempel Swagger, för att generera språkspecifika representationer av det schemaprogrammeringsspråk som används av en klient. Swagger har stöd för en mängd olika språk, till exempel C#, Go, Javascript och Python.

  • Exempel på genererad C#-kod för ipam- och undernätsobjektet på den översta nivån.

  • Exempel på genererad Go-kod för ipam- och undernätsobjektet på den översta nivån. Go används av Docker och Kubernetes som är två av konsumenterna av API:erna för värdberäkningsnätverkstjänsten. Go har inbyggt stöd för att konvertera Go-typer till och från JSON-dokument.

Förutom kodgenerering och validering kan du använda verktyg för att förenkla arbetet med JSON-dokument, dvs. Visual Studio Code.

Objekt på den översta nivån som definierats i HCN-schemat

Objekten på den översta nivån är:

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[];
};

Nästa steg