In iWorkflow 101 (episode #03) - Deploying a services template via the Tenant GUI we deployed an L4 - L7 Service onto a BIG-IP device via the iWorkflow Tenant web interface. In that episode we logged into the iWorkflow platform as an Administrator and setup a BIG-IP Connector, created a Tenant, and added an L4 - l7 Service Template to the Tenant Catalog. We then logged in to the iWorkflow Platform GUI as a Tenant and deployed L4 - L7 Service via the Tenant catalog. Oh the fun we had!

Well, in this episode we will perform the Tenant deployment via the iControl REST API.

The lab environment

For this episode we will be communicating with “iworkflow1.n8lab.local” on “10.128.1.130". Communication with the iWorkflow REST API with be performed using the Google Chrome app, POSTMAN. For more details on using POSTMAN to communicate with the REST API please review the previous episode: iWorkflow 201 (episode #01) - Introducing the iControl REST API.

Understanding iWorkflow Roles: the Provider/Tenant model  

Before we execute any more commands, its time for a quick refresh on iWorkflow’s Provider/Tenant model. In iWorkflow 101 (episode #03) - Deploying a service template via the Tenant GUI we split the article into two parts. Part 1 was performed by using iWorkflow administrator credentials and in that part we configured the platform by adding connectors, templates, catalog’s, users, etc. These steps made the platform ready for service deployments. Next, covered in Part 2 of the article, we logged in using iWorkflow Tenant credentials and deployed an L4 - L7 Service. An Administrator cannot deploy an application delivery policy onto a BIG-IP and a Tenant cannot modify the operation or integration of the iWorkflow platform. These roles apply just the same via the REST API as they do in the GUI.

For this episode, iworkflow1.n8lab.local has two users on it: 1) the default ‘admin’ account, which is an iWorkflow Administrator role, and 2) the 'User1' Tenant account we created back in iWorkflow 101 (episode #2) - Install and Setup.

To review the differing behavior of these roles lets first perform a GET request to the following REST collection as an administrator role:

https://ip_address/mgmt/shared/resolver/device-groups/cm-cloud-managed-devices/devices

You’ll receive a list of devices including the members of the iWorkflow cluster and the bigip.n8lab.local depicted in the diagram at the start of the article.

Now, perform the same transaction after changing the user credentials from “admin" to “User1”:

Execute the command again. You will receive an error like the following:

The Tenant doesn’t have permission to access ALL of the iWorkflow resources. This is by design. iWorkflow provides highly-granular, per-Tenant access control. While we will go through the iWorkflow role-based access control (RBAC) in detail in a future episode, it is important to understand that a Provider/Tenant model is in play and that it applies to the iWorkflow REST API just as it does to the iWorkflow GUI.

While there are a few minor exceptions to this rule, the default access policy applied to a User account is inherited from the iWorkflow Tenant(s) that the User has been granted access. Note in the diagram above that access is specific to the Tenant name and its child sub-collections and resource. For example, in the diagram above, the resources all start with: /mgmt/cm/cloud/tenants/MyTenant/ 

Anywho, more on RBAC in a different episode!

So, how does a Tenant view its available resources?

Take a look at the iWorkflow Connectors: https://10.128.1.130/mgmt/cm/cloud/tenants/MyTenant/connectors

As discussed in iWorkflow 101 (episode #1) - The Architecture Explained the iWorkflow connectors are the conduits to BIG-IP resources, in addition to third-party environments like Cisco ACI and VMware NSX. The connectors are created by iWorkflow Administrators under the ‘Clouds’ tab and are then associated with iWorkflow Tenants.

In this environment we have only a ‘Local’ BIG-IP connector. You may be asking why the Tenant cannot list the BIG-IP devices in their connector. This is because the Tenants job is to deploy L4 - L7 Services, which are pushed to the available BIG-IP’s. The Tenant doesn’t manage the BIG-IPs. Put another way, this is not a BIG-IP/device centric perspective and such enables a simpler self-service model.

With the iWorkflow Tenant/Provider model refresh out of the way lets get back to deploying an L4 - L7 Service via REST. 

Token Auth & Some POSTMAN Pro-tips

We introduced the POSTMAN tool in the last episode. POSTMAN isn’t the only tool that can communicate with iWorkflow. You can take any of these examples and perform them via scripting languages or directly from 3rd party orchestration tools. I use POSTMAN to show examples while remaining both scripting language and orchestration tool agnostic. In the following video we will explain POSTMAN collections and environment variables. To show how these work we will walk through the exercise of using iWorkflow Auth Tokens so you no longer need to send your credentials back and for the across the network for every request. So, sit back and learn how to use iWorkflow Auth Tokens while also learning how to be really efficient with POSTMAN.

NOTE: If you’re trying these exercises out in a lab then, like me, you are probably using self-signed SSL certificates on your iWorkflow platform. POSTMAN doesn’t handle these as gracefully as a web browser so you might want to take a look at this (instructions for Mac, Windows, and Linux): http://blog.getpostman.com/2014/01/28/using-self-signed-certificates-with-postman/

 

Review:

The iWorkflow REST API calls made in this video (using the environment variables for “iWorkflow_Mgmt_IP" and “iWorkflow1_Auth_Token”) were:

https://{{iWorkflow_Mgmt_IP}}/mgmt/shared/authn/login

https://{{iWorkflow_Mgmt_IP}}/mgmt/shared/authz/tokens/{{iWorkflow1_Auth_Token}}

https://{{iWorkflow_Mgmt_IP}}/mgmt/cm/cloud/tenants

Links referenced in this video:

The “F5_iWorkflow_REST_Commands” GitHub repository can be found here: https://github.com/npearce/F5_iWorkflow_REST_API_Commands 

The RAW files that were imported from GitHub in the video above are here (you can import these yourself):

• The POSTMAN environment: https://raw.githubusercontent.com/npearce/F5_iWorkflow_REST_API_Commands/master/iWorkflow%20Lab.postman_environment.json
• The Auth Token POSTMAN Collection: https://raw.githubusercontent.com/npearce/F5_iWorkflow_REST_API_Commands/master/F5%20iWorkflow%20REST%20API%20-%20Auth%20Tokens.postman_collection.json

Pre-launch check-list

We’re using the same n8lab.local environment (see diagram at the top) that starred in previous episodes. Within n8lab.local we’ve already discovered a BIG-IP device, created a local BIG-IP Cloud connector, and an iWorkflow Tenant. That’s the ‘administrator’ role tasks taken care of (FYI: those administrator tasks can also be performed via REST).

So, lets now perform the Tenant L4 - L7 Service deployment via the iWorkflow REST API!

Step #1: The iWorkflow Tenant REST perspective

Lest take a walk through the iWorkflow objects via the REST API. There are some small exceptions to this rule but, MOST of the Tenant activity happens below the Tenant assigned REST collection. In this lab, that refers to child resources and sub-collections of: https://{{iWorkflow_Mgmt_IP}}/mgmt/cm/cloud/tenants/myTenant1/ 

NOTE: Before we go making any transactions remember, if you’ve downloaded the POST collection from Github, make sure the current Auth Token is for the “User1” credentials and not the “admin” user. Refer to the diagram below:

You’ll see after the credentials change that if you try and run “List Tenants” in the Auth Token POSTMAN collection it will fail. The Tenant User is not permitted to see all the tenants. Hence, calling this /mgmt/cm/cloud/tenants REST collection will report a 401 Unauthorized error. However, if you reference a specific REST collection that the Tenant User is assigned to, you will receive happy data.  

Using the ‘User1’ Auth Token, lets call "/mgmt/cm/cloud/tenants/myTenant1"

List the L4 - L7 Services deployed by this Tenant: “/mgmt/cm/cloud/tenants/myTenant1/services/iapp/"

Step #2: Review the resources

In the iWorkflow 101 series we’ve already established that “User1" has been associated with “myTenant1” (an iWorkflow Tenant is a collection of resources that facilitates service deployments). We saw that myTenant1 has a local BIG-IP connector, and an L4 - L7 Service Catalog that contains the L4 - L7 Service Template “f5.http_ServiceTypeA”. We’ve looked at these resources via the GUI so now we can take a look at them via the REST API.

In the video below we take a look at the resources available to “User1” in the following order:

The Roles this user has been granted: /mgmt/shared/authz/roles

The connectors associated with myTenant1: “/mgmt/cm/cloud/tenants/myTenant1/connectors"

There servers deployed through myTenant1 (both Virtual's and Pool members): “/mgmt/cm/cloud/tenants/myTenant1/virtual-servers/"

The L4 - L7 Service Templates available to User1 through its Tenant assignments (we only have one Tenant in this lab): /mgmt/cm/cloud/tenant/templates/iapp/

The L4 - L7 Services that have been deployed already using the myTenant1 service templates: /mgmt/cm/cloud/tenants/myTenant1/services/iapp/

Having familiarized ourselves with the various iWorkflow objects we used in the 101 series, we may now deploy an L4 - L7 Service via the iWorkflow REST API.

Step #3: Deploying an L4 - L7 Service

Time to hit the Go button. As per the video below, to deploy an L4 - L7 Service, we POST to to the Tenant resource (.../myTenant/services/iapp). For example, to deploy using the “f5.http_ServiceTypeA” service templates, which is in the “myTenant1” service catalog, we would execute a POST with a JSON payload as follows:

POST https://{{iWorkflow1_Mgmt_IP}}/mgmt/cm/cloud/tenants/myTenant1/services/iapp

{
   "name":"myTestDeployment",
   "tenantTemplateReference":{
      "link":"https://localhost/mgmt/cm/cloud/tenant/templates/iapp/f5.http_ServiceTypeA"
   },
   "properties":[
      {
         "id":"cloudConnectorReference",
         "value":"https://localhost/mgmt/cm/cloud/connectors/local/bea388b8-46f8-4363-9f89-d8920ea8931f"

      }
   ],
   "tables":[
      {
         "name":"pool__hosts",
         "columns":["name"],
         "rows":[["acme.com"]]
      },
      {
         "name":"pool__members",
         "columns":["addr", "port"],
         "rows":[
            ["10.128.20.1", "8080"],
            ["10.128.20.2", "8080"]
         ]
      }
   ],
   "vars":[
      {
         "name":"pool__addr",
         "value":"10.128.10.21"
      }
   ]
}

Note the reference to the Service Template and the connector within the JSON body of the post. This is followed by the deployment specific details. Watch it all happen in the video below.

The POSTMAN collection for this episode can be imported from Github using this link: https://raw.githubusercontent.com/npearce/F5_iWorkflow_REST_API_Commands/master/F5%20iWorkflow%20REST%20API%20-%20Tenant%20L4%20-%20L7%20Service%20Deployment.postman_collection.json