Subset van de NSX Policy API

Kyvernon biedt een subset van de NSX Policy API aan bovenop zijn eigen gedistribueerde firewall, zodat tools die voor die API zijn geschreven groepen, services, beveiligingsbeleid, regels en tags van virtuele machines kunnen beheren. Het is geen NSX. NSX wordt hier genoemd om de API te beschrijven die bestaande tools spreken, en compatibiliteit wordt alleen geclaimd voor de endpoints, velden en tools die op deze pagina staan. Objecten die via dit endpoint worden geschreven, zijn gewone firewallobjecten: de console, de CLI en de native API tonen en wijzigen ze ook.

Het endpoint inschakelen

Het endpoint staat standaard uit en heeft een eigen listener met het TLS-certificaat van de controller. De console biedt deze instellingen niet aan; ze horen bij de configuratie van de controller (zie Configuratie), in de sectie [facades.nsx].

Clients melden zich aan met HTTP Basic bij elk verzoek, of met POST /api/session/create (j_username en j_password), dat antwoordt met een JSESSIONID-cookie; schrijfacties dragen daarna de header X-XSRF-TOKEN. Beide zijn facade-aanmeldingen, dus het aanmeldbeleid voor compatibiliteitsendpoints is van toepassing: standaard heeft het account een roltoewijzing nodig. De bevoegdheden zijn de native firewallbevoegdheden (Kyvernon.Firewall.*), zie Firewallreferentie.

Scopes

Alleen het domein default bestaat. De tenants staan, alleen-lezen, onder /orgs/default/projects.

Aangeboden endpoints

Onder /policy/api/v1, met {scope} zoals in de tabel hierboven.

Buiten /policy/api/v1:

Lijsten antwoorden met {results, result_count, cursor} en accepteren page_size en cursor. Elk object draagt id, display_name, description, path, parent_path, relative_path, unique_id, resource_type, tags, _revision, _create_time, _create_user, _last_modified_time, _system_owned, _protection en marked_for_delete, dat altijd false is. PUT antwoordt met het object, PATCH en DELETE met een lege 200, en het verwijderen van een object dat er niet is, is geen fout. _revision is de versie van het record, en een PUT met een verouderde versie mislukt met 412.

Objecten en hun koppeling

Een adresbereik wordt de kleinste lijst prefixen die precies dat bereik dekt, ten hoogste 256, en het endpoint geeft het bereik terug zoals het is geschreven.

De ingebouwde services zijn alleen-lezen (_system_owned is true): SSH, HTTP, HTTPS, DNS, DNS-UDP, NTP, SMTP, SMTP_TLS, SMTP-Submission, IMAP, IMAPS, POP3, POP3S, RDP, VNC, FTP, TFTP, LDAP, LDAP-UDP, LDAP-over-SSL, KERBEROS, KERBEROS-UDP, SNMP, SNMP-Trap, Syslog-UDP, Syslog-TCP, MySQL, PostgreSQL, MS-SQL-S, DHCP-Server, DHCP-Client, ICMP_Echo_Request, ICMP_Echo_Reply, ICMPv6_Echo_Request, ICMPv6_Echo_Reply, ICMP-ALL en ICMPv6-ALL.

Identiteit, namen en gelijktijdige schrijfacties

• Het id wordt door de client gekozen, zoals in NSX, en is uniek per scope. Een object dat de native API heeft gemaakt, verschijnt onder zijn native id, zoals fwgroup-3, en clients kunnen geen objecten maken onder id's van die vorm.
• display_name hoeft niet uniek te zijn en kan tot 255 tekens bevatten. Het endpoint geeft het terug zoals het is geschreven. Het firewallobject erachter heeft een unieke naam die Kyvernon afleidt: stuurtekens, / en \ worden _, een voorafgaande sys: krijgt het voorvoegsel nsx-, en een naam die al bestaat of langer is dan 80 tekens wordt ingekort en gevolgd door het id tussen haakjes. Na een wijziging via een ander oppervlak toont het endpoint de native naam.
• Velden waarvoor het firewallmodel geen plaats heeft, zoals tcp_strict, worden bewaard zoals de client ze schreef en ongewijzigd teruggegeven zolang het object niet via een ander oppervlak wordt gewijzigd.
• Schrijfacties die tegelijk lopen, zoals de parallelle resources van Terraform, worden elk berekend uit de status die ze lazen. Een schrijfactie die de race van een andere schrijver verliest, draait opnieuw op de nieuwe status, tot 12 keer. Alleen een verouderde _revision van de client wordt geweigerd.
• Een schrijfactie via het endpoint veroorzaakt dezelfde gebeurtenissen als de native API, bijvoorbeeld wanneer een regel wordt toegevoegd, gewijzigd, verwijderd of verplaatst.
• Tags die dit endpoint voor virtuele machines heeft gemaakt, worden met hun laatste gebruik verwijderd, tenzij een firewallgroep ze noemt. De tags dragen de beschrijving Created for NSX tags. Tenantgebruikers zien of wijzigen geen tagcategorieën die de provider beheert.

Hiërarchische aanroep

PATCH en PUT op {scope} accepteren een Infra-body met ChildResourceReference of ChildDomain van het domein default. Daaronder worden ChildGroup, ChildSecurityPolicy met ChildRule-kinderen en ChildService op het hoogste niveau aangeboden; marked_for_delete verwijdert een object. Elk ander kind wordt geweigerd met zijn positie in de body. De hele body wordt als één geheel gecontroleerd: Kyvernon valideert de objecten en het resultaat, en voert alles of niets door. Objecten die de body aanmaakt, mogen naar elkaar verwijzen. Dit is de aanroep die de Terraform NSX-provider gebruikt om beveiligingsbeleid te schrijven.

Zoeken

GET /policy/api/v1/search/query?query= accepteert termen verbonden met AND : field:value op resource_type, id, display_name, path, parent_path, marked_for_delete, external_id, tags.scope, tags.tag of een tekstveld op het hoogste niveau, en losse waarden, die overeenkomen met het id, de weergavenaam, het externe id en het pad. * is een jokerteken, \ is het ontsnappingsteken en aanhalingstekens zijn toegestaan. De resourcetypen zijn Group, Service, SecurityPolicy, Rule, VirtualMachine, Domain en Project. OR, NOT, haakjes en bereiken worden geweigerd.

Fouten

Het endpoint antwoordt met de NSX-foutbody (httpStatus, error_code, module_name, error_message, related_errors) en het native bericht-id in details.

Fouten van de native API behouden hun error.firewall.*-id; zie Firewallfouten.

Verschillen en beperkingen

Geverifieerd met Terraform

De Terraform NSX-provider vmware/nsxt 3.12.2 is tegen het endpoint uitgevoerd voor aanmaken, lezen, bijwerken, importeren en vernietigen.

De vSphere-kant van Terraform staat beschreven in Terraform vSphere-provider.

Zie ook

• Firewallconcepten
• Regels en beleid
• Groepen en services
• Firewallreferentie
• Overzicht van compatibiliteit