Update an Application Created Using a Service-Template from the Service Catalog

Overview

This document describes how to update and deploy an existing application on your BIG-IP using the BIG-IQ 6.0.1 API. Updates to existing applications can be done either by updating the application’s service-template and synchronizing, or by changing the parameters of the application and deploying. The parameters and prototype resources available during an application update are determined by the service-template that was used to create it. Service-templates can be added to the Service Catalog by your engineering organization responsible for determining best practices for each application.

Prerequisites

  • The BIG-IQ is operational, has completed setup and has all system-level configuration in place. The application exists on BIG-IQ.
  • All BIG-IPs are operational and have the services provisioned that will be managed by the BIG-IQ.
  • Trust has been established between the BIG-IP and the BIG-IQ, and the current configuration of the BIG-IP has been discovered on the BIG-IQ.
  • The user whose credentials will be used for these operations, has either originally created the application, or the network engineer has later assigned the <application-name> Manager role to the user.

Required Information

In addition to meeting the prerequisites, the application owner will need to prepare to provide the following information for the application.

  • A service template for the application.
  • The application’s name and a description.
  • Input values for variables in the template which define the application. Please review the listed IP addresses and change them as appropriate for your environment. If you are not running the script directly on the BIG-IQ system, you should change localhost to be the IP address of the BIG-IQ.
  • A SSG or a BIG-IP where the application can be deployed.

Actions

Using the BIG-IQ API, the application owner can perform the following actions to collect information and update the application.

  • Retrieve the existing application
  • Retrieve a specific Service-Template
  • Update and deploy the application task
  • Switch template and deploy the change
  • List the update and deploy task status

Retrieve the existing application

Before you update an application, you need to make sure the application exists in BIG-IQ. To do this, send a GET request to the collection and filter by configSetName.

GET https://{ip_address}/mgmt/cm/global/config-sets?$filter=configSetName eq 'myApp'

Alternatively, you can retrieve the application-state by sending a GET request to the resource identified by it’s id.

GET https://{ip_address}/mgmt/cm/global/config-sets/daa60df2-f808-3505-802d-0ce37fbfcff0

If the application exists on BIG-IQ, the response body will look like the following.

{
    "selfLink": "https://localhost/mgmt/cm/global/config-sets",
    "totalItems": 1,
    "items": [
        {
            "alertRuleName": "myApp-health",
            "configSetName": "myApp",
            "createDateTime": "2018-05-14T22:29:06.175Z",
            "deviceReference": {
                "link": "https://localhost/mgmt/shared/resolver/device-groups/cm-bigip-allBigIpDevices/devices/35a18732-d42a-4507-bc81-cab532d75d56"
            },
            "domains": [],
            "generation": 5,
            "id": "daa60df2-f808-3505-802d-0ce37fbfcff0",
            "kind": "cm:global:config-sets:configsetstate",
            "lastConfigTime": "2018-05-14T22:29:06.175Z",
            "lastDeploymentTime": "2018-05-14T22:30:00.042Z",
            "lastUpdateMicros": 1526337000043998,
            "partition": "Common",
            "protectionMode": "Not Protected",
            "resources": {
                "ltm:virtual:a06a8674d3c6": [
                    {
                        "parameters": {
                            "name": "vs",
                            "destinationAddress": "12.23.3.3",
                            "mask": "255.255.255.255",
                            "destinationPort": "80"
                        },
                        "parametersToRemove": [],
                        "subcollectionResources": {
                            "profiles:43ce8df2147c": [
                                {
                                    "parameters": {},
                                    "parametersToRemove": []
                                }
                            ]
                        }
                    }
                ],
                "ltm:pool:228fc448343a": [
                    {
                        "parameters": {
                            "name": "pool",
                            "description": ""
                        },
                        "parametersToRemove": [],
                        "subcollectionResources": {
                            "members:40af4bd2fd6f": [
                                {
                                    "parameters": {
                                        "port": 23,
                                        "nodeReference": {
                                            "link": "#/resources/ltm:node:f177952d6602/myNode1",
                                            "fullPath": "# myNode1"
                                        },
                                        "description": ""
                                    },
                                    "parametersToRemove": []
                                }
                            ]
                        }
                    }
                ],
                "ltm:node:f177952d6602": [
                    {
                        "parameters": {
                            "name": "myNode1",
                            "address": "10.23.2.1"
                        },
                        "parametersToRemove": []
                    }
                ]
            },
            "selfLink": "https://localhost/mgmt/cm/global/config-sets/daa60df2-f808-3505-802d-0ce37fbfcff0",
            "status": "DEPLOYED",
            "subPath": "myApp",
            "templateReference": {
                "link": "https://localhost/mgmt/cm/global/templates/f4f84362-61d1-3222-a01b-68fba8d0f0ea"
            }
        }
    ],
    "generation": 6,
    "kind": "cm:global:config-sets:configsetcollectionstate",
    "lastUpdateMicros": 1526337000056795
}

Retrieve a Specific Service-Template

The response body in ‘Retrieve the existing application’ provides the template reference. It looks like "https://localhost/mgmt/cm/global/templates/<id>". By sending a GET to this URL, you can retrieve the state of the template used to create this application.

GET https://{ip_address}/mgmt/cm/global/templates<id>

The response will look like the following.

{
    "addressSharing": false,
    "generation": 6,
    "id": "f4f84362-61d1-3222-a01b-68fba8d0f0ea",
    "kind": "cm:global:templates:templatestate",
    "lastUpdateMicros": 1526336544021013,
    "name": "exampleTemp",
    "resources": {
        "ltm:pool:228fc448343a": {
            "subcollectionResources": {
                "members:40af4bd2fd6f": {
                    "prompt": "Add object of type: ltm pool members",
                    "prototypeReference": {
                        "link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/pool/e81ff342-3ca8-339a-a752-228fc448343a/members/5c6bde8b-546a-38d8-bc45-40af4bd2fd6f"
                    },
                    "parameters": {
                        "port": {},
                        "nodeReference": {},
                        "description": {}
                    },
                    "allowMultiple": true
                }
            },
            "prompt": "Add object of type: ltm pool",
            "prototypeReference": {
                "link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/pool/e81ff342-3ca8-339a-a752-228fc448343a"
            },
            "parameters": {
                "name": {},
                "description": {}
            },
            "allowMultiple": false
        },
        "ltm:node:f177952d6602": {
            "prompt": "Add a node",
            "prototypeReference": {
                "link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/node/3a187ca3-5281-3f99-8837-f177952d6602"
            },
            "parameters": {
                "name": {},
                "address": {}
            },
            "allowMultiple": true
        },
        "ltm:virtual:a06a8674d3c6": {
            "subcollectionResources": {
                "profiles:43ce8df2147c": {
                    "prompt": "Attach a profile",
                    "prototypeReference": {
                        "link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/virtual/edc26ae8-9f02-3d6e-b326-a06a8674d3c6/profiles/febe580f-b151-3c8d-95a0-43ce8df2147c"
                    },
                    "parameters": {},
                    "allowMultiple": true
                }
            },
            "prompt": "Add object of type: ltm virtual",
            "prototypeReference": {
                "link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/virtual/edc26ae8-9f02-3d6e-b326-a06a8674d3c6"
            },
            "parameters": {
                "name": {},
                "destinationAddress": {},
                "mask": {},
                "destinationPort": {}
            },
            "allowMultiple": false
        }
    },
    "selfLink": "https://localhost/mgmt/cm/global/templates/f4f84362-61d1-3222-a01b-68fba8d0f0ea"
}

Update and deploy application task

To update the settings of the config objects of an existing application, send a POST request to apply-template with the value of mode set to “UPDATE”. This task will update the application in BIG-IQ, and by default, it will also deploy the updated application on the single BIG-IP or SSG.

The following example shows a POST request to update an application named testApp. The example only modifies the description of the pool.

POST http://{ip_address}/mgmt/cm/global/tasks/apply-template

{
    "resources": {
        "ltm:virtual:a06a8674d3c6": [
            {
                "parameters": {
                    "name": "vs",
                    "destinationAddress": "12.23.3.3",
                    "mask": "255.255.255.255",
                    "destinationPort": "80"
                },
                "parametersToRemove": [],
                "subcollectionResources": {
                    "profiles:43ce8df2147c": [
                        {
                            "parameters": {},
                            "parametersToRemove": []
                        }
                    ]
                }
            }
        ],
        "ltm:pool:228fc448343a": [
            {
                "parameters": {
                    "name": "pool",
                    "description": "This is an update application test"
                },
                "parametersToRemove": [],
                "subcollectionResources": {
                    "members:40af4bd2fd6f": [
                        {
                            "parameters": {
                                "port": 23,
                                "nodeReference": {
                                    "link": "#/resources/ltm:node:f177952d6602/myNode1",
                                    "fullPath": "# myNode1"
                                },
                                "description": ""
                            },
                            "parametersToRemove": []
                        }
                    ]
                }
            }
        ],
        "ltm:node:f177952d6602": [
            {
                "parameters": {
                    "name": "myNode1",
                    "address": "10.23.2.1"
                },
                "parametersToRemove": []
            }
        ]
    },
    "configSetName": "myApp",
    "mode": "UPDATE"
}

In the request, you need to provide mode as UPDATE, provide configSetName and also provides the resources with the desires modifications. When updating an application, you can modify the settings in the existing config objects of the application or add new instances. You cannot create a new config object through UPDATE if the resource defined in the template has allowMultiple: false.

Switch template and deploy the change

Sometime, you may want to change the base template of an existing application. To do that, you need to follow two steps:

  1. Send a GET to https://localhost/mgmt/cm/global/templates?$filter=name eq 'newTemplate' to get the new template state

The response can look similar to the following

{
    "addressSharing": false,
    "generation": 1,
    "id": "98fe6e03-c7e7-3c05-8f1f-d1a6965b34f1",
    "kind": "cm:global:templates:templatestate",
    "lastUpdateMicros": 1532579359595098,
    "name": "newTemplate",
    "resources": {
        "ltm:pool:0f75e26bc3ce": {
            "subcollectionResources": {
                "members:80b750431a28": {
                    "prompt": "Add object of type: ltm pool members",
                    "prototypeReference": {
                        "link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/pool/c5c523bc-9554-3010-83f9-0f75e26bc3ce/members/f8101108-e68f-3b82-91ac-80b750431a28"
                    },
                    "parameters": {
                        "port": {},
                        "nodeReference": {},
                        "description": {}
                    },
                    "allowMultiple": true
                }
            },
            "prompt": "Add object of type: ltm pool",
            "prototypeReference": {
                "link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/pool/c5c523bc-9554-3010-83f9-0f75e26bc3ce"
            },
            "parameters": {
                "name": {},
                "description": {}
            },
            "allowMultiple": false
        },
        "ltm:node:61e02f2fe2b1": {
            "prompt": "Add a node",
            "prototypeReference": {
                "link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/node/fe8995c8-1a80-3704-93db-61e02f2fe2b1"
            },
            "parameters": {
                "name": {},
                "address": {}
            },
            "allowMultiple": true
        },
        "ltm:virtual:b1d235db5aa6": {
            "subcollectionResources": {
                "profiles:43ce8df2147c": {
                    "prompt": "Attach a profile",
                    "prototypeReference": {
                        "link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/virtual/88421c4a-d234-3a08-9bf0-b1d235db5aa6/profiles/febe580f-b151-3c8d-95a0-43ce8df2147c"
                    },
                    "parameters": {},
                    "allowMultiple": true
                }
            },
            "prompt": "Add object of type: ltm virtual",
            "prototypeReference": {
                "link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/virtual/88421c4a-d234-3a08-9bf0-b1d235db5aa6"
            },
            "parameters": {
                "name": {},
                "destinationAddress": {},
                "mask": {},
                "destinationPort": {}
            },
            "allowMultiple": false
        }
    },
    "selfLink": "https://localhost/mgmt/cm/global/templates/98fe6e03-c7e7-3c05-8f1f-d1a6965b34f1"
}
  1. Send a POST to https://localhost/mgmt/cm/global/tasks/apply-template to update the existing the application using the new template resources.

The request body can look similar to the following

{
    "resources": {
        "ltm:virtual:b1d235db5aa6": [
            {
                    "parameters": {
                        "name": "vs",
                        "destinationAddress": "12.23.3.3",
                        "mask": "255.255.255.255",
                        "destinationPort": "80"
                    },
                    "parametersToRemove": [],
                    "subcollectionResources": {
                        "profiles:43ce8df2147c": [
                            {
                                "parameters": {},
                                "parametersToRemove": []
                            }
                        ]
                    }
                }
            ],
            "ltm:pool:0f75e26bc3ce": [
                {
                    "parameters": {
                        "name": "pool",
                        "description": "This is an update application test"
                    },
                    "parametersToRemove": [],
                    "subcollectionResources": {
                        "members:40af4bd2fd6f": [
                            {
                                "parameters": {
                                    "port": 23,
                                    "nodeReference": {
                                        "link": "#/resources/ltm:node:61e02f2fe2b1/myNode1",
                                        "fullPath": "# myNode1"
                                    },
                                    "description": ""
                                },
                                "parametersToRemove": []
                            }
                        ]
                    }
                }
            ],
            "ltm:node:61e02f2fe2b1": [
                {
                    "parameters": {
                        "name": "myNode1",
                        "address": "10.23.2.1"
                    },
                    "parametersToRemove": []
                }
            ]
        },
        "templateReference": {
            "link": "https://localhost/mgmt/cm/global/templates/98fe6e03-c7e7-3c05-8f1f-d1a6965b34f1"
        }
        "configSetName": "myApp",
        "mode": "UPDATE"
    }

In the POST request, you need to provide mode as UPDATE, provide configSetName, templateReference points to the new template state and also provides the resources with the desired modifications.

List the update and deploy task status

The body of the response to the POST to apply-template contains a selfLink of the apply-template task. The selfLink will look like this: "http://localhost/mgmt/cm/global/tasks/apply-template/<id>". To check the apply-template task’s status, send a GET request to this selfLink.

GET https://{ip_address}/mgmt/cm/global/tasks/apply-template/<id>

The response can look similar to the following.

{
    "appDeployConfigTaskReference": {
        "link": "https://localhost/mgmt/cm/global/tasks/app-deploy/5375de06-3e15-4903-86e6-9b0539440d8b"
    },
    "configSetName": "myApp",
    "configSetReference": {
        "link": "https://localhost/mgmt/cm/global/config-sets/daa60df2-f808-3505-802d-0ce37fbfcff0"
    },
    "currentStep": "DONE",
    "defaultDeviceReference": {
        "link": "https://localhost/mgmt/shared/resolver/device-groups/cm-bigip-allBigIpDevices/devices/35a18732-d42a-4507-bc81-cab532d75d56"
    },
    "deploy": true,
    "domains": [],
    "endDateTime": "2018-05-14T22:33:25.897-0700",
    "generation": 25,
    "id": "8428ea0e-5c42-4e24-b5a6-880801143767",
    "identityReferences": [
        {
            "link": "https://localhost/mgmt/shared/authz/users/admin"
        }
    ],
    "kind": "cm:global:tasks:apply-template:applytemplatetaskstate",
    "lastUpdateMicros": 1526362405947484,
    "mode": "UPDATE",
    "ownerMachineId": "0dd198e9-aa1a-4514-bdf2-0d45f1a89700",
    "partition": "Common",
    "protectionMode": "Not Protected",
    "resources": {
        "ltm:virtual:a06a8674d3c6": [
            {
                "parameters": {
                    "name": "vs",
                    "destinationAddress": "12.23.3.3",
                    "mask": "255.255.255.255",
                    "destinationPort": "80"
                },
                "parametersToRemove": [],
                "subcollectionResources": {
                    "profiles:43ce8df2147c": [
                        {
                            "parameters": {},
                            "parametersToRemove": []
                        }
                    ]
                }
            }
        ],
        "ltm:pool:228fc448343a": [
            {
                "parameters": {
                    "name": "pool",
                    "description": "This is an update application test"
                },
                "parametersToRemove": [],
                "subcollectionResources": {
                    "members:40af4bd2fd6f": [
                        {
                            "parameters": {
                                "port": 23,
                                "nodeReference": {
                                    "link": "#/resources/ltm:node:f177952d6602/myNode1",
                                    "fullPath": "# myNode1"
                                },
                                "description": ""
                            },
                            "parametersToRemove": []
                        }
                    ]
                }
            }
        ],
        "ltm:node:f177952d6602": [
            {
                "parameters": {
                    "name": "myNode1",
                    "address": "10.23.2.1"
                },
                "parametersToRemove": []
            }
        ]
    },
    "scriptParameters": {
        "partition": "Common",
        "subPath": "myApp"
    },
    "selfLink": "https://localhost/mgmt/cm/global/tasks/apply-template/8428ea0e-5c42-4e24-b5a6-880801143767",
    "startDateTime": "2018-05-14T22:32:32.314-0700",
    "status": "FINISHED",
    "subPath": "myApp",
    "templateReference": {
        "link": "https://localhost/mgmt/cm/global/templates/f4f84362-61d1-3222-a01b-68fba8d0f0ea"
    },
    "userReference": {
        "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "username": "admin"
}

Result

Updates the application in BIG-IQ and deploys the new application to a single BIG-IP or SSG.