NSX-T two APIs. How do they relate?

In this post, I will review how the new NSX-T policy API interacts with the old management plane API. If you want an overview of the benefits and properties of the new Policy API first, you can review my previous post.
The Policy API endpoint resides on the same appliance as the Management Plane API, which means the NSX Manager. So even if the Management Plane and the Policy API run as completely different processes, you will use the same endpoint IP to interact with both. The differentiation between the two is performed based on the base URI for the two APIs. The management plane API uses https://<nsxmanager-ip>/api as the base URI, while the Policy API uses https://<nsxmanager-ip>/policy/api.

When the end-user defines a configuration trough the intent base interface, the policy engine stores the desired intent in the database and interacts with the NSX manager imperative interface to realize the intent. If we create an object through the policy API, a corresponding read-only object will be created as part of the management plane API. The object will be visible but cannot be modified through the management plane API. the opposite is not true though. When we create an object trough the imperative interface, its existence will not be propagated to the Policy engine, and the lifecycle of that object must be managed through the management plane API.

Screen Shot 2019-07-10 at 12.02.18 PM

Let’s see a quick example with a logical switch, now named segment in the policy API data model. We first create a segment (logical-switch) using the Policy API. We will name it test-switch and it will be part of the transport zone named OVERLAY-TZ. For the API call, we need to collect the ID of Transport Zone. I know that having to collect a long alphanumeric system-created ID is not in line with the Policy API paradigms, but fabric-related objects are an exception, and I will probably write something specific about them. Note that the segment object will use the user-defined ID “test-switch” I included in the URI.

curl --user admin -H 'Content-Type: application/json' --request PUT https://nsxmgr-01a/policy/api/v1/infra/segments/test-switch -k -d '{"display_name":"test-switch" , "transport_zone_path" : "/infra/sites/default/enforcement-points/default/transport-zones/605ea381-c34b-42f8-84dc-a1bf561e81d4" }'

The result for the PUT above is:

{
  "type" : "DISCONNECTED",
  "transport_zone_path" : "/infra/sites/default/enforcement-points/default/transport-zones/605ea381-c34b-42f8-84dc-a1bf561e81d4",
  "resource_type" : "Segment",
  "id" : "test-switch",
  "display_name" : "test-switch",
  "path" : "/infra/segments/test-switch",
  "relative_path" : "test-switch",
  "parent_path" : "/infra/segments/test-switch",
  "marked_for_delete" : false,
  "_create_user" : "admin",
  "_create_time" : 1562779615822,
  "_last_modified_user" : "admin",
  "_last_modified_time" : 1562779615822,
  "_system_owned" : false,
  "_protection" : "NOT_PROTECTED",
  "_revision" : 0
}

The segment has been successfully created and stored in the Policy engine database. Let’s now verify that a corresponding object has been realized in the NSX Manager API. Because we do not know the system-generated ID for the logical switch corresponding to the segment we created, we will need to query all the logical switches and see if we can find one with the same name.

curl --user admin  --request GET  https://nsxmgr-01a/api/v1/logical-switches -k

Note that we are using the management plane API URI now. One of the logical switches presented in the answer is our test-switch segment.  In the object tags, you can note additional information about the fact that this object was created by the policy engine and what is its path in the policy api hierarchical structure. If we wanted to refer to this logical switch in the management plane API we would have to use its system-generated ID 671e84fd-daba-40f0-b862-67e9e764a8e3.

{
    "switch_type" : "DEFAULT",
    "transport_zone_id" : "605ea381-c34b-42f8-84dc-a1bf561e81d4",
    "vni" : 71692,
    "admin_state" : "UP",
    "replication_mode" : "MTEP",
    "address_bindings" : [ ],
    "switching_profile_ids" : [ {
      "key" : "SwitchSecuritySwitchingProfile",
      "value" : "fbc4fb17-83d9-4b53-a286-ccdf04301888"
    }, {
      "key" : "SpoofGuardSwitchingProfile",
      "value" : "fad98876-d7ff-11e4-b9d6-1681e6b88ec1"
    }, {
      "key" : "IpDiscoverySwitchingProfile",
      "value" : "64814784-7896-3901-9741-badeff705639"
    }, {
      "key" : "MacManagementSwitchingProfile",
      "value" : "1e7101c8-cfef-415a-9c8c-ce3d8dd078fb"
    }, {
      "key" : "PortMirroringSwitchingProfile",
      "value" : "93b4b7e8-f116-415d-a50c-3364611b5d09"
    }, {
      "key" : "QosSwitchingProfile",
      "value" : "f313290b-eba8-4262-bd93-fab5026e9495"
    } ],
    "hybrid" : false,
    "resource_type" : "LogicalSwitch",
    "id" : "671e84fd-daba-40f0-b862-67e9e764a8e3",
    "display_name" : "test-switch",
    "tags" : [ {
      "scope" : "policyPath",
      "tag" : "/infra/segments/test-switch"
    } ],
    "_create_user" : "nsx_policy",
    "_create_time" : 1562779617374,
    "_last_modified_user" : "nsx_policy",
    "_last_modified_time" : 1562779617374,
    "_system_owned" : false,
    "_protection" : "REQUIRE_OVERRIDE",
    "_revision" : 0,
    "_schema" : "/v1/schema/LogicalSwitch"
  }

Let’s try the opposite now. We are going to create a logical switch named test-switch2 via the management plane API.

curl --user admin -H 'Content-Type: application/json' --request POST  https://nsxmgr-01a/api/v1/logical-switches -k -d '{"display_name":"test-swith2" , "transport_zone_id" : "605ea381-c34b-42f8-84dc-a1bf561e81d4" , "admin_state" : "UP" , "replication_mode" : "MTEP"}'

Now we can check if we see a corresponding segment in the Policy API.

curl --user admin  --request GET  https://nsxmgr-01a/policy/api/v1/infra/segments -k

You will not find any corresponding segment in the answer from NSX Manager.

In conclusion, it is recommended to leverage the policy API as much as possible in order to avoid inconsistencies between the two API models.

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s