The following section describes Grid URIs. For example, you can retrieve information about the grid, create a grid, and perform operations on the grid.
You can retrieve information about a set of grids, for a single grid, and for grid state.
GET BFC/grids
None
HTTP return code 200 and a payload that is a list of grid records on success. Returns an HTTP error code and the associated fault information on error.
Retrieves information about the current set of grids in the system as a list of grid records. For the 1.0 release of the BFC API, you cannot specify the range of grid records to return, rather records are returned for all grids in the system.
For the 1.0 release of the BFC API, the fields in the grid_record that are populated on a GET are: name, description, controller_ip, id, applogic_version, xen_config, esx_config, external_network, default_vlan, vmware_license_key, app_ip_count, app_ips, servers, oem_kit, global_user_dir, account_id and state.
Python Example
session = get_session()
conn = HTTPSConnection(bfcHost + ':8443')
conn.connect()
conn.request(method='GET',
url='/BFC/grids',
headers={'Content-Type':'application/json',
'Authorization':session})
grids = json.loads(conn.getresponse().read())
print grids
Example JSON Payload
{"grid":{"comp_id":1234,"id":2,"name":"SimpleGrid2",
"description":"SimpleGrid2 description","state":"resource_allocated_state",
"applogic_version":"3.1.2","applogic_hotfixes":null,"enable_language_packs":false,
"xen_config":{"grid_server_configuration":{"min":2,"target":2,"max":2,"selection_criteria":null}},
"esx_config":{"grid_server_configuration":{"min":2,"target":2,"max":2,"selection_criteria":null}},
"servers":[],"external_network":"127.10.10.0/24",
"app_ips":[{"grid_ip_range":{subnet_id:2345,vlan:10,public_private:"public",
ip_low:"127.10.10.2",ip_high:"127.10.10.11"}],"app_ip_count":10,
"controller_ip":"127.10.10.1","default_vlan":1,
"account_id":null,"account_key":null, "oem_kit":null,
"vmware_license_key":"XXXXX-XXXXX-XXXXX-XXXXX-XXXXX","global_user_dir":null,
"grid_controller_name":null,"grid_controller_user":null,"grid_controller_password":null,
"recovery_password":null,"additional_config":null}},
{"grid":{"comp_id":5678,"id":1,"name":"SimpleGrid1",
"description":"SimpleGrid1 description","state":"resource_allocated_state",
"applogic_version":"3.1.1","applogic_hotfixes":null,"enable_language_packs":false,
"xen_config":{"grid_server_configuration":{"min":2,"target":2,"max":2,"selection_criteria":null}},
"esx_config":{"grid_server_configuration":{"min":0,"target":0,"max":0,"selection_criteria":null}},
"servers":[],"external_network":"127.10.10.0/24",
"app_ips":[{"grid_ip_range":{subnet_id:1245,vlan:null,public_private:"public",
ip_low:"127.10.10.13",ip_high:"127.10.10.22"}],"app_ip_count":10,
"controller_ip":"127.10.10.12","default_vlan":1,
"account_id":null,"account_key":null, "oem_kit":null,
"vmware_license_key":"XXXXX-XXXXX-XXXXX-XXXXX-XXXXX","global_user_dir":null,
"grid_controller_name":null,"grid_controller_user":null,"grid_controller_password":null,
"recovery_password":null, "additional_config":null, "external_storage":null}}]}
Retrieve Information about a Single Grid
GET BFC/grids/<grid_name>
None
HTTP return code 200 and a payload that is a grid record on success. Returns an HTTP error code and the associated fault information on error.
Retrieves information about a single grid. The information is returned in a grid record. For the 1.0 release of the BFC API, the fields in the grid_record that are populated on a GET are: name, description, controller_ip, id, applogic_version, xen_config, esx_config, external_network, default_vlan, vmware_license_key, app_ip_count, app_ips, servers, oem_kit, account_id, global_user_dir, external_storage, and state.
Python Example
from httplib import HTTPSConnection
import json
import os
import sys
gridName = sys.argv[1]
print 'gridName: {0}'.format(gridName)
bfcHost = os.environ["BFC_HOST"]
bfcSession = os.environ["BFC_SESSION"]
conn = HTTPSConnection(bfcHost + ':8443')
conn.connect()
conn.request(method='GET',
url='/BFC/grids/' + gridName,
headers={'Content-Type':'application/json',
'Authorization':bfcSession})
r1 = conn.getresponse()
print 'HTTP Response Code: {0}'.format(r1.status)
grid = json.loads(conn.getresponse().read())
print json.dumps(grid, sort_keys=True, indent=4)
Example JSON Payload
{"grid":{"comp_id":null,"id":2,"name":"SimpleGrid2",
"description":"SimpleGrid2 description","state":"resource_allocated_state",
"applogic_version":"3.1.2","applogic_hotfixes":null,"enable_language_packs":false,
"xen_config":{"grid_server_configuration":{"min":2,"target":2,"max":2,"selection_criteria":[["xengold"]]}},
"esx_config":{"grid_server_configuration":{"min":2,"target":2,"max":2,"selection_criteria":[["esxgold"]]}},
"servers":[],"external_network":"127.10.10.0/24",
"app_ips":[{"grid_ip_range":{subnet_id:2345,vlan:10,public_private:"public",
ip_low:"127.10.10.2",ip_high:"127.10.10.11"}],"app_ip_count":10,
"controller_ip":"127.10.10.1","default_vlan":1,
"account_id":null,"account_key":null, "oem_kit":"Acme Computer Corp",
"vmware_license_key":"XXXXX-XXXXX-XXXXX-XXXXX-XXXXX","global_user_dir":null,
"grid_controller_name":null,"grid_controller_user":null,"grid_controller_password":null,
"recovery_password":null,"additional_config":null,"external_storage":null}}
Retrieve State Information for a Single Grid
GET BFC/grids/<grid_name>/state
None
HTTP return code 200 and a payload that is the grid state as a string on success. Returns an HTTP error code and the associated fault information on error.
Retrieves the state of a single grid. The grid state is returned in a string.
Example JSON Payload
"resource_allocated_state"
GET BFC/grids/<grid name>/app_ips
None
Returns the HTTP return code 200 and a payload that displays the grid IP range on success. Returns an HTTP error code and the associated fault information on error.
Use this operation to retrieve the grid IP range.
Example GET
GET BFC/grids/mygrid/app_ips
Python Example
from httplib import HTTPSConnection
import json
import os
import sys
gridName = sys.argv[1]
print 'gridName: {0}'.format(gridName)
bfcHost = os.environ["BFC_HOST"]
bfcSession = os.environ["BFC_SESSION"]
conn = HTTPSConnection(bfcHost + ':8443')
conn.connect()
conn.request(method='GET',
url='/BFC/grids/' + gridName + '/app_ips',
headers={'Content-Type':'application/json',
'Authorization':bfcSession})
r1 = conn.getresponse()
print 'HTTP Response Code: {0}'.format(r1.status)
if r1.status > 202:
error = json.loads(r1.read())
print error
In the following example you create a new grid component in the BFC/grids folder.
POST BFC/grids POST BFC/grids?checkExternalStorage&enableLanguagePacks&numAppIPs=10
The payload is a possibly sparse grid record. For the 1.0 release of the BFC, the following fields are required in the grid record:
Note: At least one of the two must be specified and have a target count greater than 0.
For the 1.0 release of the BFC API, the following parameters in the grid record are honored:
Note: If the applogic_version is not specified, the most recent (highest numbered) CA AppLogic version is used.
Note: If external_network is not specified, one of the available external networks is selected.
See the table below that details legal IP and VLAN parameter combinations.
Note: Used to reserve address ranges explicitly for grid application use. If not specified, then specify a count of addresses in the numAppIPs query string parameter and the system will reserve that many application IP addresses.
See the table below that details legal IP and VLAN parameter combinations.
See the table below that details legal IP and VLAN parameter combinations.
Note: The default VLAN determines the VLAN for the grid controller IP and if otherwise specified (through the app_ips parameter data) also determines the VLAN for the requested number of application IPs.
See the table below that details legal IP and VLAN parameter combinations.
Note: By default, accessibility of external storage is not checked as part of the create. To check accessibility as part of the create operation (and fail the create if the storage can't be accessed), specify the "checkExternalStorage" query string in the POST URI. See documentation for Check External Storage to check the accessibility of the storage independent of a create operation.
Create Grid supports two IP modes:
Use the following table to review permissible IP and VLAN parameter combinations when passing the parameter. The top row identifies the parameter that you are passing, the value in the column below the parameter indicates the system response. Combinations can be permitted (OK), REQUIRED, or result in an ERROR. For example, when passing the external_network parameter, numAppIPs is REQUIRED.
Table - Create Grid IP and VLAN input (parameter and query string) combination rules
|
Provided data: |
default_vlan |
external_network |
controller_ip |
app_ips |
numAppIPs* |
|
default_vlan |
N/A |
OK |
OK |
OK |
OK |
|
external_network |
OK |
N/A |
ERROR |
ERROR |
OK |
|
controller_ip |
OK |
ERROR |
N/A |
REQUIRED |
ERROR |
|
app_ips |
OK |
ERROR |
REQUIRED |
N/A |
ERROR |
|
numAppIPs* |
OK |
REQUIRED |
ERROR |
ERROR |
N/A |
* = Query String input data (see below)
Supported query string parameters in the POST URI
If simply present or set equal to true, then the accessibility of the external storage is verified as part of the grid creation operation.
If simply present or set equal to true, then all language packs will be applied to the grid being created.
Specifies the number of application IP addresses that should be reserved for use by applications running on the grid being created. The specific addresses will be chosen by the system. Also, either this parameter or the app_ips parameter in the grid record is required and those parameters are mutually exclusive; only one or the other may be specified.
See the previous table that details legal IP and VLAN parameter combinations.
On success, HTTP code 201 and the name of the created grid are returned. On error, an HTTP error code and fault(s) are returned.
Creates a new grid component in the BFC.
Note: This action does not create the AppLogic grid. The first call to the start operation for the grid creates the grid.
The following example assumes you are using the query string ?numAppIPs=10 on the POST URI and a sparse grid record with the following values:
Example JSON Payload
{"grid": {"grid_controller_user": "cadev@cadev.com", "name": "bfcapigrid",
"xen_config":{"grid_server_configuration":{"min":2,"target":2,"max":2,"selection_criteria":null}},
"applogic_version": "3.0.8",
"external_network": "222.222.222.131/16", "grid_controller_password": "F00b@r",
"description": "a grid created through the bfc api"}}
201
BFC/grids/bfcapigrid
Note: The PUT and DELETE actions are not supported.
DELETE BFC/grids/<grid name> DELETE BFC/grids/<grid name>?keepexternalstorage
None
HTTP return code 202 and an empty payload on success. Returns an HTTP error code and the associated fault information on error.
Deletes the specified grid. The BFC API operation will return after the grid delete operation is successfully submitted. The actual deletion of the AppLogic grid will continue asynchronously. If a grid uses external storage, the external storage is deleted by default as part of the grid delete operation. If retention of the external storage is desired, the keepExternalStorage querystring can be specified.
When a GET operation on the grid resource URI returns an HTTP 404 error code, the asynchronous delete of the CA AppLogic grid has completed.
Example DELETE
DELETE BFC/grids/mygrid
Python Example
from httplib import HTTPSConnection
import json
import os
import sys
gridName = 'mygrid'
bfcHost = os.environ["BFC_HOST"]
bfcSession = os.environ["BFC_SESSION"]
conn = HTTPSConnection(bfcHost + ':8443')
conn.connect()
conn.request(method='POST',
url='/BFC/grids/' + 'gridName',
headers={'Content-Type':'application/json',
'Authorization':bfcSession},
resp = conn.getresponse()
if resp.status > 202:
print 'Failed grid delete - '
print json.loads(resp.read())
else:
print 'Grid deleted'
You can update a grid with or without reboot.
Update a grid without reboot
PUT BFC/grids/<grid name>
The payload is a sparse grid record that is populated with only those fields that are to be updated.
For the 1.0 release of the BFC API, the parameters in the grid parameters that can be updated are:
In addition, the following set of parameters can be passed when not specified with the above parameters. If a reboot is required to enable these parameters, you should use the update grid method described below.
See the table below for valid combinations of these parameters for update.
HTTP return code 202 and an empty payload on success. Returns an HTTP error code and the associated fault information on error.
Updates a grid with the specified values. The underlying CA AppLogic grid is not rebooted as part of these updates. Grid updates happen asynchronously to the update call. When a GET call to the grid resource URL reflects the new attributes of the grid, the update has been completed.
Note: For the 1.0 release of the BFC API, when issuing a PUT to this URI, it is an error to include any of the grid parameters that can be updated by the updateGridWithReboot operation (except for the separately specified default_vlan, app_ips, controller_ip, and extra_parameters).
Example grid update using a sparsely populated grid record
JSON Payload:
{"grid":
"description":"Updated SimpleGrid1 description",
"oem_kit":"ACME Computer Corp",
"xen_config":
{"grid_server_configuration":{"min":3,"target":3,"max":3,
"selection_criteria":null}},
"esx_config":
("grid_server_configuration":{"min":1,"target":1,"max":1,
"selection_criteria":null}},
"vmware_license_key":"XXXXX-XXXXX-XXXXX-XXXXX-XXXXX"}
Update a grid with reboot
POST BFC/grids/<grid name>/operations/updateGridWithReboot
The payload is a sparsely populated grid record that contains only those fields that are to be updated.
For the 1.0 release of the BFC API, the parameters in the grid parameters that can be updated are:
In addition, the following set of parameters can be passed when not specified with the above parameters. If a reboot is not required to enable these parameters, you should use the update grid method described above.
See the table below for valid combinations of these parameters for update.
HTTP return code 202 and an empty payload on success. Returns an HTTP error code and the associated fault information on error.
Updates a grid with the specified values and then reboots the underlying AppLogic grid to make the new values active. Grid updates happen asynchronously to the update call. When a GET call to the grid resource URL reflects the new attributes of the grid, the update has been completed.
Note: For the 1.0 release of the BFC API, when issuing a POST to this URI, it is an error to include any of the grid parameters that can be updated via a PUT to the grid resource URI.
Table - Network properties combination for grid update
|
|
default_vlan |
controller_ip |
app_ips |
|
default_vlan |
N/A |
REQUIRED |
ALLOWED |
|
controller_ip |
REQUIRED |
N/A |
ALLOWED |
|
app_ips |
ALLOWED |
ALLOWED |
N/A |
POST BFC/grids/<grid name>/operations/start
Payload is empty.
202 on success or HTTP error code on error (for example, if the grid is busy).
Use this operation to start a grid that is stopped. Use this operation after you create the grid using the BFC Grid Create API, or after you stopped a grid using the web interface of API.
When you create a grid using the BFC web interface, the CA AppLogic grid is created and started in one step. If this step is the first call to start a grid that has never been started, it can be very expensive and may take up to several hours to complete. During this process, CA AppLogic grid nodes are imaged, catalogs are copied into place, volumes are configured, and so on.
After the grid is created, you can use the start operation to restart a stopped grid. To status the grid start, monitor the state field of the grid record that returns from a GET to the grid URL. The start is completed when the state is resource_running_state.
Note: The GET, PUT, and DELETE actions are not supported for grid operations.
Example POST
POST BFC/grids/mygrid/operations/start
POST BFC/grids/<grid name>/operations/stop
Payload is empty.
202 on success or HTTP error code on error (for example, if the grid is busy).
This operation stops the CA AppLogic grid. To status the grid stop, monitor the state field of the grid record returned from a GET to the grid URL. The grid is stopped when the state is resource_ready_state.
Note: The GET, PUT, and DELETE actions are not supported for grid operations.
Example POST
POST BFC/grids/mygrid/operations/stop
POST BFC/grids/<grid_name>/operations/reboot
Payload is empty.
202 on success or HTTP error code on error (for example, if the grid is busy).
This operation reboots the running CA AppLogic grid. To status the grid stop, monitor the state field of the grid record returned from a GET to the grid URL. The grid is rebooted when the state returns to resource_running_state.
Note: The GET, PUT, and DELETE actions are not supported for grid operations.
Example POST
POST BFC/grids/mygrid/operations/reboot
POST BFC/grids/<grid name>/operations/applyHotfixes
Payload is a list of strings that are the names of the hotfixes and/or language packs that should be applied or re-applied to the grid. The hotfix names should be of the form: hf1248. The language pack names are of the form lp1248-English.
202 on success or HTTP error code on error (for example, if the grid is busy).
This operation applies the specified hotfixes and/or language packs to a running CA AppLogic grid. To status the operation, monitor the state field of the grid record returned from a GET to the grid URL. The specified hotfixes and/or language packs have been applied to the grid when the state returns to resource_running_state.
Note: The GET, PUT, and DELETE actions are not supported for grid operations.
Example POST
POST BFC/grids/mygrid/operations/applyHotfixes
Example JSON Payload
{grids{"applogic_hotfixes":hf6169}}
POST BFC/grids/<grid name>/operations/removeNodes
Payload is a list of MAC and/or IP addresses specifying the nodes to be removed from the grid. Each MAC or IP address should correspond to the backbone interface of a grid server.
Note: Before you remove a node with this method, you must first disable the node in the CA AppLogic grid controller.
202 on success or HTTP error code on error (for example, if the grid is busy).
This operation removes the specified nodes from the running CA AppLogic grid. To status the operation, monitor the state field of the grid record returned from a GET to the grid URL. The specified nodes have been removed from the grid when the state returns to resource_running_state.
Note: The GET, PUT, and DELETE actions are not supported for grid operations.
Example POST
POST BFC/grids/mygrid/operations/removeNodes
Example JSON Payload
{"grids"{"Servers":01:02:03:04:05:06}
POST BFC/grids/<grid name>/app_ips
Payload is list of grid_ip_ranges. The VLAN parameter is optional.
Returns the HTTP return code 202 and adds a list of IP ranges to the existing list of ranges on the grid on success. Returns an HTTP error code and the associated fault information on error.
Use this operation to add a grid IP range to the list of ranges.
Example POST
POST BFC/grids/mygrid/app_ips
Python Example
from httplib import HTTPSConnection
import json
import os
import sys
gridName = sys.argv[1]
print 'gridName: {0}'.format(gridName)
bfcHost = os.environ["BFC_HOST"]
bfcSession = os.environ["BFC_SESSION"]
conn = HTTPSConnection(bfcHost + ':8443')
conn.connect()
conn.request(method='POST',
url='/BFC/grids/' + gridName + '/app_ips',
headers={'Content-Type':'application/json',
'Authorization':bfcSession},
body=json.dumps([{"grid_ip_range":{
"public_private":"public",
"ip_low":"10.x.x.31",
"ip_high":"10.x.x.51"}}]))
r1 = conn.getresponse()
print 'HTTP Response Code: {0}'.format(r1.status)
if r1.status > 202:
error = json.loads(r1.read())
print error
DELETE BFC/grids/<grid name>/app_ips/<ip_low>-<ip_high>
None.
Returns the HTTP return code 202 and deletes the specific grid IP range on success. Returns an HTTP error code and the associated fault information on error.
Use this operation to delete a grid IP range from the list of non-VLAN ranges.
Example DELETE
DELETE BFC/grids/mygrid/app_ips/10.x.x.31-10.x.x.40
DELETE BFC/grids/<grid name>/app_ips/<ip_low>-<ip_high>/<vlan>
None.
Returns the HTTP return code 202 and deletes the specific grid IP range from a VLAN on success. Returns an HTTP error code and the associated fault information on error.
Use this operation to delete a grid IP range from a VLAN.
Example DELETE
DELETE BFC/grids/mygrid/app_ips/10.x.x.31-10.x.x.40/4094
POST BFC/grids/<grid name>/operations/configureExternalStorage
Payload is an external_storage_nfs record.
Returns the HTTP return code 202 and updates the volume storage to the values that are specified in the external_storage_nfs record. Returns an HTTP error code and the associated fault information on error.
Use this operation to update the external volume storage of a grid to the values that are specified in the external_storage_nfs record. This operation also reboots the grid as necessary. When changing external storage from one NFS share to another, the stopGrid query parameter may be used to stop the grid as part of the update after which volumes can be copied manually from the old NFS share to the new NFS share.
Example POST
POST BFC/grids/mygrid/operations/configureExternalStorage
Example JSON Payload
{"external_storage_nfs"{"host":NFSserverhost,"path":/NFSpath/export}}
POST BFC/grids/<grid name>/operations/configureLocalStorage
None.
Returns the HTTP return code 202 and sets the volume storage of the grid to local. Returns an HTTP error code and the associated fault information on error.
Use this operation to set the volume storage as local. If you specify keepExternalVolumes, the volumes on the external storage remain in tact. If you specify ignoreExternalVolumes, the operation does not fail when volumes are found on the NFS share currently associated with the grid. Otherwise, the operation to switch to local storage fails and the grid remains in an UCTL breached state.
Example POST
POST BFC/grids/mygrid/operations/configureLocalStorage
|
Copyright © 2013 CA Technologies.
All rights reserved.
|
|