Product Documentation

How to Use API to Create Configurations from StyleBooks

Jan 30, 2017

After you have built your StyleBook, you have to import it to NetScaler MAS to use it either by using the NetScaler MAS GUI or by using NetScaler MAS APIs. NetScaler MAS validates your StyleBook when you import it, and if the validation is successful, your StyleBook appears on the NetScaler MAS GUI catalog of StyleBooks, ready to be used for creating configurations.

You can now use the StyleBook APIs to create configurations based on this StyleBook. You can use any tool such as the curl command line tool or the Postman chrome browser extension to send HTTP requests to NetScaler MAS.

Example 1

Consider the “lb-vserver” StyleBook you have created in StyleBook to Create a Load Balancing Virtual Server. Use REST API to create a config pack from this StyleBook as follows:

POST

https://<MAS-DNS-or-IP>/stylebook/nitro/v1/config/stylebooks/com.example.stylebooks/0.1/lb-vserver/configpacks

Content-Type: application/json

Accept: application/json

{

"configpack": {  

        "parameters": {

            "name": "lb1",

            "ip": "10.102.117.31"

             },

        "target_devices": 

          [

          {

                 "id": "deecee30-f478-4446-9741-a85041903410"

          }

          ]

        }

}
 

In this HTTP request, the id (for example, "deecee30-f478-4446-9741-a85041903410") is the instance ID of the NetScaler instance on which the load balancing virtual server lb1 with IP address 10.102.117.31 is created. The instance ID of the NetScaler instance is retrieved from NetScaler MAS.

To obtain the ID of an instance managed by NetScaler MAS, you can use NetScaler MAS APIs. For example, to retrieve the instance ID os a NetScaler instance whose IP address is 192.168.153.160, you can use the following API:

     GET https://<MAS-IP>/nitro/v1/config/ns?filter=ip_address:192.168.153.160

     Accept: application/json

The response contains the ID in the payload:

     200 OK

     Content-Type: application/json

     {

          "errorcode": 0,

          "message": "Done",

          "operation": "get",

          "resourceType": "ns",

          "username": "nsroot",

          "tenant_name": "Owner",

          "resourceName": "",

          "ns": [

           {

                "is_grace": "false",

                 "hostname": "",

                 "std_bw_config": "0",

                 "gateway_deployment": "false",

                  ….

                 "id": "deecee30-f478-4446-9741-a85041903410",

                 ...

           }

           ]

      }

If the configuration (config pack) is successfully created, you receive the following HTTP response:

 

     200 OK

     Content-Type: application/json               

     {

           "configpack": {

            "config_id": "1460806080"

           }

     }

 

You have created your first configuration (config pack) that is uniquely identified by using the id 1460806080. You can use this ID to query, update, or delete the configuration.

Example 2

You can use the same StyleBook to create another configuration or config pack and execute it on the same or different NetScaler instances. In this example, create another configuration and provide a different name and IP address for the virtual server and also specify LEASTCONNECTION as the load balancing method. Deploy this configuration on two NetScaler instances.

The HTTP request is as follows:

POST

https://<MAS-DNS-or-IP>/stylebook/nitro/v1/config/stylebooks/com.example.stylebooks/0.1/lb-vserver/configpacks

Content-Type: application/json

Accept: application/json

{

"configpack": {  

        "parameters": {

              "name": "lb2",

              "ip": "10.102.117.32",

              "lb-alg": "LEASTCONNECTION"  

             },

        "target_devices": 

                    [

                         {

                                "id": "deecee30-f478-4446-9741-a85041903410"

                         },

                         {

                                 "id": "debecc60-d589-4557-8632-a74032802412"

                           }

                    ]

     }

}

In this HTTP request, the load balancing virtual server lb2 with IP address 10.102.117.32 is created on the two NetScaler instances represented by the ids "deecee30-f478-4446-9741-a85041903410" and "debecc60-d589-4557-8632-a74032802412".

On successful creation of the config pack, the following HTTP response is received:

200 OK

Content-Type: application/json

{

 "configpack": {

  "config_id": "1657696292"

 }

}

 

This new config pack has a different id 165769629. You can update or remove this configuration by using this id.

Example 3

Consider the "basic-lb-config" StyleBook you have created in StyleBook to Create a Basic Load balancing Configuration. Use REST API to create a config pack from this StyleBook as follows:

POST

http://<MAS-DNS-or-IP>/stylebook/nitro/v1/config/stylebooks/com.example.stylebooks/0.1/basic-lb-config/configpacks

          Content-Type: application/json

          Accept: application/json

{

  "configpack": {  

        "parameters": {

            "name" : "myapp",

            "ip": "10.70.122.25",

            "svc-servers" : ["192.168.100.11", "192.168.100.12"],

            "svc-port": 8080

        },  

        "target_devices": 

          [

                         {

                                "id": "deecee30-f478-4446-9741-a85041903410"

                         },

                         {

                                 "id": "debecc60-d589-4557-8632-a74032802412"

                           }

          ]  

     }

}


In this HTTP request, the load balancing configuration is executed on two NetScaler instances. You can log on to these NetScaler instances to verify whether a virtual server and a service group with two services bound are created.

Example 4

Consider the composite StyleBook composite-example you created in Create a Composite StyleBook. Use REST API to create a config pack from this StyleBook as follows:

POST http://<MAS-DNS-or-IP>/stylebook/nitro/v1/config/stylebooks/com.example.stylebooks/0.1/composite-example/configpacks

Content-Type: application/json

Accept: application/json

{

"configpack": {  

        "parameters": {

            "name" : "myapp",

            "ip": "2.2.2.2",

            "svc-servers": ["10.102.29.52", "10.102.29.53"]

        },  

       "target_devices": 

          [

                         {

                                "id": "deecee30-f478-4446-9741-a85041903410"

                         },

                         {

                                 "id": "debecc60-d589-4557-8632-a74032802412"

                           }

          ]   

     }

}

In this HTTP request, the configuration is created on two NetScaler instances represented by their ids. If you log on to the NetScaler instances, you can view the configuration objects created by the "basic-lb-config" StyleBook that was imported into the "composite-example" StyleBook. You can also see a new HTTP monitor called "myapp-mon" that was part of the "composite-example" StyleBook.

On successful creation of the config pack, the following HTTP response is received:

200 OK

Content-Type: application/json

{

 "configpack": {

  "config_id": "4917276817"

 }

}

Updating a Configuration

To update this configuration, for example, by adding a new backend server with IP address 10.102.29.54 to the load balancing virtual server myapp, use the API for updating a config pack as follows:

PUT http://<MAS-DNS-or-IP>/stylebook/nitro/v1/config/stylebooks/com.example.stylebooks/0.1/composite-example/configpacks/4917276817

Content-Type: application/json

Accept: application/json

{

"configpack": {  

        "parameters": {

            "name" : "myapp",

            "ip": "2.2.2.2",

            "svc-servers": ["10.102.29.52", "10.102.29.53", "10.102.29.54"]

        },  

       "target_devices": 

          [

                         {

                                "id": "deecee30-f478-4446-9741-a85041903410"

                         },

                         {

                                 "id": "debecc60-d589-4557-8632-a74032802412"

                           }

          ]  

      }

}

 

On successful update of the config pack, the following HTTP response is received:

 

200 OK

Content-Type: application/json

{

 "configpack": {

  "config-id": "4917276817"

 }

}

Deleting a Configuration

To delete this configuration (from all the NetScaler instances), you can use the API for deleting a config pack as follows:

DELETE http://<MAS-DNS-or-IP>/stylebook/nitro/v1/config/stylebooks/com.example.stylebooks/0.1/composite-example/configpacks/4917276817

Accept: application/json

On successful deletion of the config pack, the following HTTP response is received:

200 OK

Content-Type: application/json

{

 "configpack": {

  "config_id": "4917276817"

 }

}


You can log on to the NetScaler instance and verify that all the configuration objects that are part of this config pack have been removed.

If you want to remove the configuration from specific NetScaler instances instead of from all, use the update configpack operation described above and change the "target_devices" attribute in the JSON payload to remove the specific NetScaler instance IDs.