Configure and Deploy an Application from the Service Catalog¶
Overview¶
The BIG-IQ Service Catalog is a collection of service-templates for applications that have been approved for you to instantiate and deploy. Service-templates can enable you to configure and deploy your applications faster, and help make sure they conform to your own best-practices. Service-templates for approved applications can be set up by your engineering organization responsible for determining which applications to use and the best practices for each application. Because this organization understands the technology and the application’s requirements, they can provide a service-template which will ensure the best configuration and they can also set appropriate role-based access controls (RBAC) designating who can view, edit, or remove the service-templates. Your engineering organization can set up a service-template with editable fields which can enable the operations team or the application owner to provide values for selected application parameters while remaining consistent with the requirements of your organization.
When you use a service-template from the Service Catalog to create and deploy a new application, you must also provide all the information required by the application which has not already been specified in the service-template by your engineering or operations teams. To instantiate a new application you may also need to provide specific information required for the application to work, for example the node IP addresses and ports. Although you can use the BIG-IQ to deploy new applications based upon the Service Catalog, if you prefer using a script to deploy your new application with a common configuration, you can reference the service-template, provide required information, instantiate the new application, and deploy to the BIG-IP using the BIG-IQ REST API.
This topic explains how you can use the BIG-IQ REST API to instantiate and deploy a new application based upon a service-template that you have found in the Service Catalog.
Prerequisites¶
- The BIG-IQ Centralized Management device is operational, has completed the setup wizard, and completed any other needed configuration.
- All BIG-IP devices are operational and have the services provisioned that will be managed by the BIG-IQ Centralized Management device.
- Trust has been established between the BIG-IP device and the BIG-IQ Centralized Management device, and the current configuration of the BIG-IP device has been discovered on the BIG-IQ Centralized Management device.
- When performing the tasks in this example, review the listed IP
addresses and change them as appropriate for your environment. For
example, if you are not running the script directly on the BIG-IQ
system, you should change
localhostto be the IP address of the BIG-IQ Centralized Management system. - Your engineering or operations team have added an applicable service-template to your Service Catalog.
List All Service-Templates¶
The service-templates in the Service Catalog of your BIG-IQ are represented as a template-state collection. To retrieve a list of all the service templates, you can send a GET request to this collection using the BIG-IQ REST API. The url for your GET request may look similar to the following.
GET: https://{ip_address}/mgmt/cm/global/templates
The JSON returned in the body of a successful response may look similar to the following example for the template-states: fg, myTemplate, and test. You would also see the names of these template-states listed in the Service Catalog section of the BIG-IQ UI. If you know the name of the service-template for your application, you can determine that it is available on your BIG-IQ by examining the list returned by the REST API or by looking for its name in the BIG-IQ UI.
{
"items": [
{
"generation": 2,
"id": "3d4044d6-5abd-3a40-ba92-991f1300ec97",
"kind": "cm:global:templates:templatestate",
"lastUpdateMicros": 1505946432354974,
"name": "fg",
"resources": {
"virtual_resource_1": {
"prompt": "Add object of type: ltm virtual",
"prototypeReference": {
"link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/virtual/bb74cd9e-4cbb-323f-ae37-caa67db94109"
},
"parameters": {
"name": {}
},
"subcollectionResources": {
"virtual_profile_tcp_resource_1": {
"prompt": "Add object of type: ltm virtual profiles",
"prototypeReference": {
"link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/virtual/bb74cd9e-4cbb-323f-ae37-caa67db94109/profiles/febe580f-b151-3c8d-95a0-43ce8df2147c"
},
"parameters": {}
}
},
"allowMultiple": false
}
},
"selfLink": "https://localhost/mgmt/cm/global/templates/3d4044d6-5abd-3a40-ba92-991f1300ec97"
},
{
"name": "test",
"resources": {},
"id": "098f6bcd-4621-3373-8ade-4e832627b4f6",
"generation": 1,
"lastUpdateMicros": 1505957139312770,
"kind": "cm:global:templates:templatestate",
"selfLink": "https://localhost/mgmt/cm/global/templates/098f6bcd-4621-3373-8ade-4e832627b4f6"
},
{
"generation": 14,
"id": "923a0063-665a-3c90-b52b-66b4b920ea88",
"kind": "cm:global:templates:templatestate",
"lastUpdateMicros": 1506035448465574,
"name": "myTemplate",
"resources": {
"virtual_resource_2": {
"prompt": "Add object of type: ltm virtual",
"prototypeReference": {
"link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/virtual/69d71e6f-a382-374f-b215-0d2d4b2ce1eb"
},
"parameters": {
"name": {},
"destinationAddress": {},
"mask": {},
"destinationPort": {}
},
"subcollectionResources": {
"virtual_profile_tcp_resource_2": {
"prompt": "Attach a profile with context: all",
"prototypeReference": {
"link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/virtual/69d71e6f-a382-374f-b215-0d2d4b2ce1eb/profiles/febe580f-b151-3c8d-95a0-43ce8df2147c"
},
"parameters": {},
"allowMultiple": true
}
},
"allowMultiple": true
},
"virtual_resource_3": {
"prompt": "Add object of type: ltm pool",
"prototypeReference": {
"id": "a920a4e5-9f06-3342-97cc-402a15321087",
"name": "myTemplate_p",
"kind": "cm:adc-core:template-config:ltm:pool:adcpoolstate",
"partition": "Common",
"description": "",
"link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/pool/a920a4e5-9f06-3342-97cc-402a15321087"
},
"parameters": {
"name": {}
},
"subcollectionResources": {
"node_myTemplate_5~5~4~4_resource_1": {
"prompt": "Add object of type: ltm pool members",
"prototypeReference": {
"link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/pool/a920a4e5-9f06-3342-97cc-402a15321087/members/78d1456c-bae4-3d10-a8c8-16dbb58afd47"
},
"parameters": {
"port": {},
"nodeReference": {}
},
"allowMultiple": true
}
},
"allowMultiple": false
},
"node_myTemplate_5~5~4~4_resource_1": {
"prompt": "Add a node",
"prototypeReference": {
"link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/node/f0be52a6-2c3a-313f-8fec-22b241227cf8"
},
"parameters": {
"name": {},
"address": {}
},
"allowMultiple": true
}
},
"selfLink": "https://localhost/mgmt/cm/global/templates/923a0063-665a-3c90-b52b-66b4b920ea88"
}
],
"generation": 2,
"kind": "cm:global:templates:templatecollectionstate",
"lastUpdateMicros": 1506035448474989,
"selfLink": "https://localhost/mgmt/cm/global/templates"
}
Retrieve a Specific Service-Template¶
After you have determined the correct service-template is available in
the Service Catalog, you can retrieve this specific template-state by
sending a GET request to the collection and filtering by its name.
GET
https://{ip_address}/mgmt/cm/global/templates?$filter=name eq 'myTemplate'
Alternatively, you can retrieve the specific template-state by sending a
GET request directly to the resource identified by it’s id.
GET
https://{ip_address}/mgmt/cm/global/templates/923a0063-665a-3c90-b52b-66b4b920ea88
The JSON returned in the response of a successful request contains only those fields of the template which have been approved for you to edit. Fields for application parameters which your engineering organization has restricted access are non-editable and will not appear. For example, the JSON for the template-state can look similar to the following.
{
"selfLink": "https://localhost/mgmt/cm/global/templates",
"totalItems": 1,
"items": [
{
"generation": 14,
"id": "923a0063-665a-3c90-b52b-66b4b920ea88",
"kind": "cm:global:templates:templatestate",
"lastUpdateMicros": 1506035448465574,
"name": "myTemplate",
"resources": {
"virtual_resource_2": {
"prompt": "Add object of type: ltm virtual",
"prototypeReference": {
"link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/virtual/69d71e6f-a382-374f-b215-0d2d4b2ce1eb"
},
"parameters": {
"name": {},
"destinationAddress": {},
"mask": {},
"destinationPort": {}
},
"subcollectionResources": {
"virtual_profile_tcp_resource_2": {
"prompt": "Attach a profile with context: all",
"prototypeReference": {
"link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/virtual/69d71e6f-a382-374f-b215-0d2d4b2ce1eb/profiles/febe580f-b151-3c8d-95a0-43ce8df2147c"
},
"parameters": {},
"allowMultiple": true
}
},
"allowMultiple": true
},
"virtual_resource_3": {
"prompt": "Add object of type: ltm pool",
"prototypeReference": {
"id": "a920a4e5-9f06-3342-97cc-402a15321087",
"name": "myTemplate_p",
"kind": "cm:adc-core:template-config:ltm:pool:adcpoolstate",
"partition": "Common",
"description": "",
"link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/pool/a920a4e5-9f06-3342-97cc-402a15321087"
},
"parameters": {
"name": {}
},
"subcollectionResources": {
"node_myTemplate_5~5~4~4_resource_1": {
"prompt": "Add object of type: ltm pool members",
"prototypeReference": {
"link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/pool/a920a4e5-9f06-3342-97cc-402a15321087/members/78d1456c-bae4-3d10-a8c8-16dbb58afd47"
},
"parameters": {
"port": {},
"nodeReference": {}
},
"allowMultiple": true
}
},
"allowMultiple": false
},
"node_myTemplate_5~5~4~4_resource_1": {
"prompt": "Add a node",
"prototypeReference": {
"link": "https://localhost/mgmt/cm/adc-core/template-config/ltm/node/f0be52a6-2c3a-313f-8fec-22b241227cf8"
},
"parameters": {
"name": {},
"address": {}
},
"allowMultiple": true
}
},
"selfLink": "https://localhost/mgmt/cm/global/templates/923a0063-665a-3c90-b52b-66b4b920ea88"
}
],
"generation": 2,
"kind": "cm:global:templates:templatecollectionstate",
"lastUpdateMicros": 1506035448474989
}
Add or Modify Template Information¶
By changing only the editable fields of your template-state, you will help ensure that your application conforms to the requirements designated by your engineering organization. Edit the JSON that was provided by BIG-IQ in the previous step, provide a name for the new application, and give values for the virtual server IP, pool name, and pool members. Provide values for any of the other fields that are required to make your application work.
There are two main sections of the template-state. There is a section
for parameters common to all the config items, such as name, id,
generation, kind, lastUpdatedMicros, and selfLink. The
resources section defines config items that may be created in
working-config when the template is instantiated as an application.
The resources field defines resource items and associates each item
with a name. The resources section can contain the following fields.
| Name | Type | Description |
|---|---|---|
allowMultiple |
boolean | If true, BIG-IQ can instantiate the template to specify multiple items of the resource. This enables the user to create 0 or more config items described by the resource during instantiation. The default value of this property is false. |
name |
string | This is the name associated with the config item. |
parameters |
object | This field enables you to
modify the template object for
the application. Each config
item includes a parameters
field having a value which you
may modify during
instantiation. |
prompt |
string | A prompt to add a reference. |
prototypeReference |
object | A reference to a
template-config object which is
serving as a prototype. During
the instantiation of the
application, BIG-IQ copies the
prototype into
working-config after
applying the assignments
designated in the
parameters section. The
referenced object must be
included as a part of the JSON
request to instantiate. The
reference is provided as a
link to a uri. |
subcollectionResources |
object | Designates whether the resource has a subcollection resource. This can enable a user to instantiate multiple resource items in a pool member dynamically. |
The parameters object enables you to modify the template objects to
fit the needs of the application. Each config item may includes a field
having a value you may modify during instantiation. In the example,
parameters can include the following fields.
| Name | Type | Description |
|---|---|---|
address |
string | An IP address. |
destinationAddress |
string | The destination IP address. |
destinationPort |
number | The well-known port number associated with address. |
mask |
string | A network mask. |
name |
string | A name that identifies this parameter. |
Instantiate Template¶
To instantiate your edited template as a new application object in
working-config, send a POST request to apply-template. This
creates a new application based on the JSON provided in the payload of
the POST request plus the service-template. If the POST is successful,
BIG-IQ adds the application object to working-config.
The following example shows an example of a POST request to instantiate
an application named testApp.
POST http://{ip_address}/mgmt/cm/global/tasks/apply-template
{
"resources": {
"virtual_resource_2": [
{
"parameters": {
"name": "testApp_vs1",
"destinationAddress": "3.2.2.6",
"mask": "255.255.255.255",
"destinationPort": "80"
},
"subcollectionResources": {
"virtual_profile_tcp_resource_2": [
{
"parameters": {}
}
]
}
}
],
"virtual_resource_3": [
{
"parameters": {
"name": "testApp_p"
},
"subcollectionResources": {
"node_myTemplate_5~5~4~4_resource_1": [
{
"parameters": {
"port": 80,
"nodeReference": {
"link": "#/resources/node_myTemplate_5~5~4~4_resource_1/testApp_5.5.4.4"
}
}
}
]
}
}
],
"node_myTemplate_5~5~4~4_resource_1": [
{
"parameters": {
"name": "testApp_5.5.4.4",
"address": "5.5.4.4"
}
}
]
},
"configSetName": "testApp",
"prefix": "testApp",
"defaultDeviceReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/cm-adccore-allbigipDevices/devices/7c7fcedb-45e2-4f7d-b2de-5ff2c52053ac"
},
"templateReference": {
"link": "https://localhost/mgmt/cm/global/templates/923a0063-665a-3c90-b52b-66b4b920ea88"
}
}
List all Applications¶
A successful instantiation of your template adds your new application’s
config-set into the working-config collection of BIG-IQ. To list the
config-sets for the applications in working-config you can send a
GET request to the collection.
GET https://{ip_address}/mgmt/cm/global/config-sets
The response may look similar to the following, which lists config-sets
for zxcxc, myApp, and bazz.
{
"items": [
{
"configSetName": "zxcxc",
"prefix": "zxcxc",
"createDateTime": "2017-09-20T20:32:01.405Z",
"templateReference": {
"link": "https://localhost/mgmt/cm/global/templates/923a0063-665a-3c90-b52b-66b4b920ea88"
},
"id": "e4220fa1-0979-368e-b0b6-08e3d2b69d11",
"generation": 1,
"lastUpdateMicros": 1505939521427479,
"kind": "cm:global:config-sets:configsetstate",
"selfLink": "https://localhost/mgmt/cm/global/config-sets/e4220fa1-0979-368e-b0b6-08e3d2b69d11"
},
{
"configSetName": "myApp",
"prefix": "myApp",
"createDateTime": "2017-09-21T00:03:49.213Z",
"templateReference": {
"link": "https://localhost/mgmt/cm/global/templates/923a0063-665a-3c90-b52b-66b4b920ea88"
},
"id": "daa60df2-f808-3505-802d-0ce37fbfcff0",
"generation": 1,
"lastUpdateMicros": 1505952229227985,
"kind": "cm:global:config-sets:configsetstate",
"selfLink": "https://localhost/mgmt/cm/global/config-sets/daa60df2-f808-3505-802d-0ce37fbfcff0"
},
{
"configSetName": "bazz",
"prefix": "bazz",
"createDateTime": "2017-09-21T17:10:47.586Z",
"templateReference": {
"link": "https://localhost/mgmt/cm/global/templates/923a0063-665a-3c90-b52b-66b4b920ea88"
},
"id": "d06e481a-a6b6-351b-93e9-c03508990c65",
"generation": 1,
"lastUpdateMicros": 1506013847673285,
"kind": "cm:global:config-sets:configsetstate",
"selfLink": "https://localhost/mgmt/cm/global/config-sets/d06e481a-a6b6-351b-93e9-c03508990c65"
}
],
"generation": 1,
"kind": "cm:global:config-sets:configsetcollectionstate",
"lastUpdateMicros": 1505867486428397,
"selfLink": "https://localhost/mgmt/cm/global/config-sets"
}
Get Virtual Servers¶
To get the specific virtual servers associated with the application you
want to deploy, you can send a GET request to the resource using
$filter. Your GET request may look similar to the following. In this
example {ip_address} represents the IP address of the BIG-IQ and
{app-name} represents the string configSetName and also used in
BIGIQ_configSetName. In the following example, {app-name} should
be replaced with whatever value you used for configSetName.
GET
https://{ip_address}/mgmt/shared/index/config?$filter=kind eq 'cm:adc-core:working-config:ltm:virtual:adcvirtualstate' and tags/namevalue eq 'BIGIQ_configSetName : {app-name}&function=working-config
If the request is successful, the body of the response returns virtual servers associated with the application and may look similar to the following.
{
"items": [
{
"sourceAddress": "0.0.0.0/0",
"sourceAddressTranslation": {
"type": "none"
},
"destinationAddress": "4.3.3.32",
"destinationPort": "80",
"mask": "255.255.255.255",
"state": "enabled",
"mirror": "disabled",
"ipProtocol": "tcp",
"poolReference": {
"id": "ea816209-bc7b-3c33-b6b3-3ef923937b7e",
"name": "bazy_p1",
"kind": "cm:adc-core:working-config:ltm:pool:adcpoolstate",
"partition": "Common",
"link": "https://localhost/mgmt/cm/adc-core/working-config/ltm/pool/ea816209-bc7b-3c33-b6b3-3ef923937b7e"
},
"profilesCollectionReference": {
"link": "https://localhost/mgmt/cm/adc-core/working-config/ltm/virtual/e5240735-9cd3-3005-a665-2ea585e64d94/profiles",
"isSubcollection": true
},
"vlansEnabled": "disabled",
"addressStatus": "yes",
"autoLasthop": "default",
"connectionLimit": 0,
"gtmScore": 0,
"nat64": "disabled",
"rateLimit": "disabled",
"rateLimitMode": "object",
"translateAddress": "enabled",
"translatePort": "enabled",
"sourcePort": "preserve",
"partition": "Common",
"deviceReference": {
"id": "7c7fcedb-45e2-4f7d-b2de-5ff2c52053ac",
"name": "somebusiness.com",
"kind": "shared:resolver:device-groups:restdeviceresolverdevicestate",
"machineId": "7c7fcedb-45e2-4f7d-b2de-5ff2c52053ac",
"link": "https://localhost/mgmt/shared/resolver/device-groups/cm-adccore-allbigipDevices/devices/7c7fcedb-45e2-4f7d-b2de-5ff2c52053ac"
},
"name": "sdfdfdf_vs",
"id": "e5240735-9cd3-3005-a665-2ea585e64d94",
"generation": 1,
"lastUpdateMicros": 1506646483840253,
"kind": "cm:adc-core:working-config:ltm:virtual:adcvirtualstate",
"selfLink": "https://localhost/mgmt/cm/adc-core/working-config/ltm/virtual/e5240735-9cd3-3005-a665-2ea585e64d94",
"tags": [
{
"name": "BIGIQ_configSetName",
"value": "sdfdfdf"
}
]
}
],
"totalItems": 1,
"selfLink": "https://localhost/mgmt/shared/index/config?$filter=kind+eq+%27cm:adc-core:working-config:ltm:virtual:adcvirtualstate%27+and+tags/namevalue+eq+%27BIGIQ_configSetName+:+sdfdfdf%27&function=working-config"
}
Start an Evaluation and Deploy¶
To start an evaluation and deploy your application, you can send a POST
request to the deploy-configuration collection. The body of the POST
request may contain the following information.
| Name | Type | Description |
|---|---|---|
deploySpecifiedObjectsOnly |
boolean | If false, all objects
referenced by
objectsToDeployReferences
will also be deployed. The
value should be false so all
referenced
pools/pool members/nodes
are also deployed. If an object
in your application is not
referenced by the virtual
server, it should be included
in
objectsToDeplyoReferences,
otherwise it will not be
deployed. |
deviceReferences |
object | A reference to the BIG-IPs to
which the BIG-IQ is to deploy
application objects. Provided
as a link to a uri. All the
unique devices references
should have been returned in
the previous step. |
objectsToDeployReferences |
object | A reference to each object to
include in the deployment.
Provided as a link to a
uri. |
skipDistribution |
boolean | If true, BIG-IQ halts the deployment when evaluation is complete so user can examine differences. When deploying a new application from the Service Catalog, this value is typically false because this is a new config and unlikely to affect existing traffic. The BIG-IQ will still halt the deployment if verification finds critical errors. |
skipVerifyConfig |
boolean | If true, BIG-IQ skips additional verification of config. Typically this value is false. |
status |
string | When the deployment has been
completed, the value of
status will change to
“FINISH”. |
Your POST request can look similar to the following.
POST
https://{ip_address}/mgmt/cm/adc-core/tasks/deploy-configuration
The JSON in the body of the request may look similar to the following.
{
"skipVerifyConfig":false,
"skipDistribution":false,
"name":"test",
"deviceReferences":[
{
"link":"https://localhost/mgmt/shared/resolver/device-groups/cm-adccore-allbigipDevices/devices/7c7fcedb-45e2-4f7d-b2de-5ff2c52053ac"
}
],
"objectsToDeployReferences":[
{
"link":"https://localhost/mgmt/cm/adc-core/working-config/ltm/pool/fdc29c17-079f-364b-8b14-84848f240012"
}],
"deploySpecifiedObjectsOnly":false
}
The body of the response contains JSON representing the started task and
includes the status property. The user can send repeated GET
requests to determine when the value of the task’s status property
changes to “FINISHED”.
When the deployment has been completed, the value of status will
change to “FINISHED”.