Sous-ensemble de l'API NSX Policy

Kyvernon sert un sous-ensemble de l'API NSX Policy au-dessus de son propre pare-feu distribué, afin que des outils écrits pour cette API puissent gérer des groupes, des services, des stratégies de sécurité, des règles et des étiquettes de machines virtuelles. Ce n'est pas NSX. NSX est nommé ici pour décrire l'API que parlent les outils existants, et la compatibilité n'est revendiquée que pour les points d'accès, les champs et les outils listés sur cette page. Les objets écrits par ce point d'accès sont des objets de pare-feu ordinaires : la console, la CLI et l'API native les montrent et les modifient aussi.

Activation du point d'accès

Le point d'accès est désactivé par défaut et dispose de son propre écouteur avec le certificat TLS du contrôleur. La console ne propose pas ces paramètres ; ils font partie de la configuration du contrôleur (voir Configuration), dans la section [facades.nsx].

Les clients se connectent avec HTTP Basic à chaque requête, ou avec POST /api/session/create (j_username et j_password), qui répond par un cookie JSESSIONID ; les écritures portent ensuite l'en-tête X-XSRF-TOKEN. Les deux sont des connexions de façade, la stratégie de connexion des points d'accès de compatibilité s'applique donc : par défaut, le compte a besoin d'une attribution de rôle. Les privilèges sont les privilèges natifs du pare-feu (Kyvernon.Firewall.*), voir Référence du pare-feu.

Portées

Seul le domaine default existe. Les locataires sont listés, en lecture seule, sous /orgs/default/projects.

Points d'accès servis

Sous /policy/api/v1, avec {scope} comme dans le tableau ci-dessus.

En dehors de /policy/api/v1 :

Les listes répondent {results, result_count, cursor} et acceptent page_size et cursor. Chaque objet porte 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 et marked_for_delete, qui vaut toujours false. PUT répond avec l'objet, PATCH et DELETE avec un 200 vide, et supprimer un objet absent n'est pas une erreur. _revision est la version de l'enregistrement, et un PUT avec une version périmée échoue avec 412.

Objets et correspondance

Une plage d'adresses devient la plus petite liste de préfixes qui couvre exactement cette plage, 256 au plus, et le point d'accès renvoie la plage telle qu'elle a été écrite.

Les services intégrés sont en lecture seule (_system_owned vaut 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 et ICMPv6-ALL.

Identité, noms et écritures simultanées

• L'identifiant est choisi par le client, comme dans NSX, et est unique par portée. Un objet créé par l'API native apparaît sous son identifiant natif, tel que fwgroup-3, et les clients ne peuvent pas créer d'objets sous des identifiants de cette forme.
• display_name n'a pas besoin d'être unique et peut compter jusqu'à 255 caractères. Le point d'accès le renvoie tel qu'il a été écrit. L'objet de pare-feu qui se trouve derrière a un nom unique que Kyvernon dérive : les caractères de contrôle, / et \ deviennent _, un sys: initial reçoit le préfixe nsx-, et un nom déjà pris ou de plus de 80 caractères est raccourci et suivi de l'identifiant entre crochets. Après une modification par une autre surface, le point d'accès affiche le nom natif.
• Les champs pour lesquels le modèle du pare-feu n'a pas de place, comme tcp_strict, sont conservés tels que le client les a écrits et renvoyés inchangés tant que l'objet n'est pas modifié par une autre surface.
• Les écritures simultanées, comme les ressources parallèles de Terraform, sont chacune calculées à partir de l'état qu'elles ont lu. Une écriture qui perd la course contre un autre auteur est rejouée sur le nouvel état, jusqu'à 12 fois. Seule une _revision périmée du client est refusée.
• Une écriture par le point d'accès déclenche les mêmes événements que l'API native, par exemple quand une règle est ajoutée, modifiée, supprimée ou déplacée.
• Les étiquettes que ce point d'accès a créées pour des machines virtuelles sont supprimées avec leur dernier usage, sauf si un groupe de pare-feu les nomme. Les étiquettes portent la description Created for NSX tags. Les utilisateurs de locataire ne voient ni ne modifient les catégories d'étiquettes que le fournisseur gère.

Appel hiérarchique

PATCH et PUT sur {scope} acceptent un corps Infra avec ChildResourceReference ou ChildDomain du domaine default. En dessous, ChildGroup, ChildSecurityPolicy avec des enfants ChildRule, et ChildService au niveau supérieur sont servis ; marked_for_delete supprime un objet. Tout autre enfant est refusé avec sa position dans le corps. Le corps entier est vérifié comme un tout : Kyvernon valide les objets et le résultat, et applique tout ou rien. Les objets que le corps crée peuvent se référencer entre eux. C'est l'appel que le fournisseur Terraform NSX utilise pour écrire les stratégies de sécurité.

Recherche

GET /policy/api/v1/search/query?query= accepte des termes joints par AND  : field:value sur resource_type, id, display_name, path, parent_path, marked_for_delete, external_id, tags.scope, tags.tag ou tout champ de texte de premier niveau, et des valeurs seules, qui correspondent à l'identifiant, au nom affiché, à l'identifiant externe et au chemin. * est un caractère générique, \ échappe, et les guillemets sont permis. Les types de ressource sont Group, Service, SecurityPolicy, Rule, VirtualMachine, Domain et Project. OR, NOT, les parenthèses et les intervalles sont refusés.

Erreurs

Le point d'accès répond avec le corps d'erreur NSX (httpStatus, error_code, module_name, error_message, related_errors) et l'identifiant de message natif dans details.

Les erreurs de l'API native gardent leur identifiant error.firewall.* ; voir Erreurs du pare-feu.

Différences et limites

Vérifié avec Terraform

Le fournisseur Terraform NSX vmware/nsxt 3.12.2 a été exécuté contre le point d'accès pour la création, la lecture, la mise à jour, l'import et la destruction.

Le côté vSphere de Terraform est décrit dans Fournisseur Terraform vSphere.

Voir aussi

• Concepts du pare-feu
• Règles et stratégies
• Groupes et services
• Référence du pare-feu
• Vue d'ensemble de la compatibilité