NSX Policy API subset

Kyvernon serves a subset of the NSX Policy API over its own distributed firewall, so that tools written for that API can manage groups, services, security policies, rules and virtual machine tags. It is not NSX. NSX is named here to describe the API that existing tools speak, and compatibility is claimed only for the endpoints, fields and tools listed on this page. Objects written through this endpoint are ordinary firewall objects: the console, the CLI and the native API show and change them as well.

Turning the endpoint on

The endpoint is off by default and has its own listener with the TLS certificate of the controller. The console does not offer these settings; they are part of the controller configuration (see Configuration) in the section [facades.nsx].

Clients sign in with HTTP Basic on every request, or with POST /api/session/create (j_username and j_password), which answers with a JSESSIONID cookie; writes then carry the header X-XSRF-TOKEN. Both are facade sign-ins, so the sign-in policy for compatibility endpoints applies: by default the account needs a role assignment. The privileges are the native firewall privileges (Kyvernon.Firewall.*), see Firewall reference.

Scopes

Only the domain default exists. The tenants are listed, read only, at /orgs/default/projects.

Served endpoints

Below /policy/api/v1, with {scope} as in the table above.

Outside /policy/api/v1:

Lists answer {results, result_count, cursor} and take page_size and cursor. Every object carries 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 and marked_for_delete, which is always false. PUT answers with the object, PATCH and DELETE with an empty 200, and deleting an object that is absent is not an error. _revision is the version of the record, and a PUT with a stale one fails with 412.

Objects and their mapping

An address range becomes the smallest list of prefixes that covers exactly that range, at most 256, and the endpoint returns the range as it was written.

The built-in services are read only (_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 and ICMPv6-ALL.

Identity, names and concurrent writes

• The id is chosen by the client, as in NSX, and is unique per scope. An object that the native API created appears under its native id, such as fwgroup-3, and clients cannot create objects under ids of that form.
• display_name need not be unique and can have up to 255 characters. The endpoint returns it as written. The firewall object behind it has a unique name that Kyvernon derives: control characters, / and \ become _, a leading sys: gets the prefix nsx-, and a name that is taken or longer than 80 characters is shortened and followed by the id in brackets. After a change through another surface, the endpoint shows the native name.
• Fields that the firewall model has no place for, such as tcp_strict, are kept as the client wrote them and returned unchanged while the object is not changed through another surface.
• Writes that run at the same time, such as the parallel resources of Terraform, are each computed from the state they read. A write that loses the race to another writer runs again on the new state, up to 12 times. Only a stale _revision of the client is refused.
• A write through the endpoint raises the same events as the native API, for example when a rule is added, changed, deleted or moved.
• Tags that this endpoint created for virtual machines are removed with their last use, unless a firewall group names them. The tags carry the description Created for NSX tags. Tenant users neither see nor change tag categories that the provider manages.

Hierarchical call

PATCH and PUT on {scope} take an Infra body with ChildResourceReference or ChildDomain of the domain default. Below it, ChildGroup, ChildSecurityPolicy with ChildRule children, and ChildService at the top level are served; marked_for_delete removes an object. Any other child is refused with its position in the body. The whole body is checked as one: Kyvernon validates the objects and the result, and commits all of it or none of it. Objects that the body creates may refer to each other. This is the call that the Terraform NSX provider uses to write security policies.

Search

GET /policy/api/v1/search/query?query= takes terms joined with AND : field:value on resource_type, id, display_name, path, parent_path, marked_for_delete, external_id, tags.scope, tags.tag or any top-level string field, and bare values, which match the id, the display name, the external id and the path. * is a wildcard, \ escapes, and quotes are allowed. The resource types are Group, Service, SecurityPolicy, Rule, VirtualMachine, Domain and Project. OR, NOT, parentheses and ranges are refused.

Errors

The endpoint answers with the NSX error body (httpStatus, error_code, module_name, error_message, related_errors) and the native message id in details.

Errors of the native API keep their error.firewall.* id; see Firewall errors.

Differences and gaps

Verified with Terraform

The Terraform NSX provider vmware/nsxt 3.12.2 was run against the endpoint through create, read, update, import and destroy.

The vSphere side of Terraform is described in Terraform vSphere provider.

Related

• Firewall concepts
• Rules and policies
• Groups and services
• Firewall reference
• Compatibility overview