BIG-IQ API Reference Guide

(1)

Reference Guide

version 4.3.0

(2)

(3)

This manual applies to version 4.3.0 of BIG-IQ™ system.

Publication Date

This document was published on February 25, 2014.

Publication Number

PUB-0281-03

Copyright

F5 Networks, Inc. (F5) believes the information it furnishes to be accurate and reliable. However, F5 assumes no responsibility for the use of this information, nor any infringement of patents or other rights of third parties which may result from its use. No license is granted by implication or otherwise under any patent, copyright, or other intellectual property right of F5 except as specifically described by applicable user licenses. F5 reserves the right to change specifications at any time without notice.

Trademarks

AAM, Access Policy Manager, Advanced Client Authentication, Advanced Firewall

Manager, Advanced Routing,

AFM, Application Acceleration Manager, Application Security Manager, APM, ARX, AskF5, ASM, BIG-IP, BIGIQ, Cloud Extender, CloudFucious, Cloud Manager, Clustered Multiprocessing, CMP, COHESION, Data Manager, DevCentral, DevCentral [DESIGN], DNS Express, DSC, DSI, Edge Client, Edge Gateway, Edge Portal, ELEVATE, EM, Enterprise Manager, ENGAGE, F5, F5 [DESIGN], F5 Certified [DESIGN], F5 Networks, F5 SalesXchange [DESIGN], F5 Synthesis, f5 Synthesis, F5 Synthesis [DESIGN], F5 TechXchange [DESIGN], Fast Application Proxy, Fast Cache, FirePass, Global Traffic Manager, GTM, GUARDIAN, iApps, IBR, Intelligent Browser Referencing, Intelligent Compression, IPv6 Gateway, iControl, iHealth, iQuery, iRules, iRules OnDemand, iSession, L7 Rate Shaping, LC, Link Controller, Local Traffic Manager, LTM, LineRate, LineRate Systems [DESIGN], LROS, LTM, Message Security Manager, MobileSafe, MSM, OneConnect, Packet Velocity, PEM, Policy Enforcement Manager, Protocol Security Manager, PSM, Real Traffic Policy Builder, SalesXchange, ScaleN, Signalling Delivery Controller, SDC, SSL Acceleration, Software Designed Applications Services, SDAC (except in Japan), StrongBox, SuperVIP, SYN Check, TCP Express, TDR, TechXchange, TMOS, TotALL, Traffic Management Operating System, Traffix Systems, Traffix Systems [DESIGN], Transparent Data Reduction, UNITY, VAULT, vCMP, VE F5 [DESIGN], Versafe, Versafe [DESIGN], VIPRION, Virtual Clustered Multiprocessing, WebSafe, and ZoneRunner, are trademarks or service marks of F5 Networks, Inc., in the U.S. and other countries, and may not be used without

F5's express written consent.

All other product and company names herein may be trademarks of their respective owners.

Patents

This product may be protected by one or more patents indicated at: http://www.f5.com/about/guidelines-policies/patents

Export Regulation Notice

This product may include cryptographic software. Under the Export Administration Act, the United States government may consider it a criminal offense to export this product from the United States.

RF Interference Warning

This is a Class A product. In a domestic environment this product may cause radio interference, in which case the user may be required to take adequate measures.

(4)

can radiate radio frequency energy and, if not installed and used in accordance with the instruction manual, may cause harmful interference to radio communications. Operation of this equipment in a residential area is likely to cause harmful interference, in which case the user, at his own expense, will be required to take whatever measures may be required to correct the interference.

Any modifications to this device, unless expressly approved by the manufacturer, can void the user's authority to operate this equipment under part 15 of the FCC rules.

Canadian Regulatory Compliance

This Class A digital apparatus complies with Canadian ICES-003.

Standards Compliance

This product conforms to the IEC, European Union, ANSI/UL and Canadian CSA standards applicable to Information Technology products at the time of manufacture.

(5)

(6)

1 F5 BIG-IQ REST APIs

Introduction to cloud service APIs ...1-1

BIG-IQ Cloud overview ...1-2

BIG-IQ Cloud API conventions ...1-3

Ports required for F5 Cloud service REST API ...1-4

Uncharacteristic return codes ...1-5

Bad Gateway ...1-5

Service Temporarily Unavailable ...1-5

2 Central Management APIs

Central management APIs ...2-1

Templates iApp collection worker APIs ...2-1

Get templates ...2-1

Update template item ...2-3

Create new template item ...2-5

Delete template item ...2-7

Provider iApp template APIs ...2-8

What is an iApp template? ...2-8

What is a provider iApp template? ...2-8

How does a provider make an iApp template? ...2-8

The structure of a provider template ...2-9

Tenant templates ... 2-11

Variables ... 2-11

Properties ... 2-12

Get provider iApp templates ... 2-13

Create provider iApp template ... 2-15

Get customized provider template parameters ... 2-17

Delete provider iApp template ... 2-19

Sample provider template APIs ... 2-20

Get example provider template for a corresponding iApp template ... 2-20

Get example provider template for a corresponding iApp template ... 2-21

Find all provider template examples ... 2-21

Tenant iApp templates APIs ... 2-23

Variables ... 2-23

Properties ... 2-24

Get all tenant iApp templates ... 2-25

Get tenant iApp template configuration ... 2-28

Tenant APIs ... 2-30

Get all tenants ... 2-31

Get one tenant information ... 2-32

Create tenant ... 2-32

Update tenant information ... 2-34

Delete one tenant ... 2-34

Tenant services APIs ... 2-35

Properties ... 2-35

(7)

Get service health ... 2-46

Tenant virtual servers APIs ... 2-49

Get all virtual servers ... 2-49

Get one virtual server ... 2-50

Get example-stats ... 2-50

Tenant service server tiers APIs ... 2-53

Get server tiers ... 2-53

Get servers in tier ... 2-54

Tenant node APIs ... 2-56

Create node ... 2-56

Query for all tenant nodes ... 2-57

Query example-stats for tenant nodes ... 2-58

Tenant cloud connectors APIs ... 2-60

Get all tenant cloud connectors ... 2-60

Get tenant connector ... 2-61

Cloud connector APIs ... 2-63

Types of cloud connectors ... 2-63

Creating a cloud connector ... 2-63

Deploying an application in the cloud ... 2-64

Cloud connector description ... 2-64

Explanation of fields ... 2-65

Parameters ... 2-65

Parameters for specific cloud types ... 2-66

Discovering a cloud connector's parameters ... 2-66

Create a cloud connector ... 2-68

Change a cloud connector ... 2-68

Get a cloud connector ... 2-70

Get health of a cloud connector ... 2-70

Get all cloud connectors of a given type ... 2-71

Get all cloud connectors of all types (brief) ... 2-72

Get all cloud connectors of all types (detailed) ... 2-72

Delete a cloud connector ... 2-74

Local cloud connector APIs ... 2-75

Parameters ... 2-75

Explanation of fields ... 2-76

Parameters ... 2-76

Parameters for local clouds ... 2-77

Create a local cloud connector ... 2-77

Change a local cloud connector ... 2-78

Get a cloud connector ... 2-79

Get all local cloud connectors ... 2-79

Get health of a local cloud connector ... 2-80

Delete a local cloud connector ... 2-81

EC2 cloud connectors APIs ... 2-82

EC2 Connector Topology ... 2-83

Parameters for EC2 cloud connectors ... 2-84

Create an EC2 cloud connector ... 2-85

Change an EC2 cloud connector ... 2-87

Get an EC2 connector ... 2-90

Get health of an EC2 cloud connector ... 2-92

Get all EC2 cloud connectors ... 2-92

Delete an EC2 cloud connector ... 2-94

OpenStack cloud connector APIs ... 2-97

Parameters for OpenStack cloud connectors ... 2-98

(8)

Get an OpenStack cloud connector ... 2-100

Get health of an OpenStack cloud connector ... 2-101

Get all OpenStack cloud connector ... 2-103

Delete an OpenStack cloud connector ... 2-104

VMware cloud connector APIs ... 2-105

Parameters for VMware cloud connectors ... 2-106

Create a VMware cloud connector ... 2-108

Change a VMware cloud connector ... 2-108

Get a VMware cloud connector ... 2-110

Get health of a VMware cloud connector ... 2-111

Get all VMware cloud connector ... 2-111

Delete a VMware cloud connector ... 2-112

Cloud managed devices APIs ... 2-114

Get managed devices ... 2-115

Add a managed device ... 2-118

Recover a device in the POST_FAILED state ... 2-118

Delete a managed device ... 2-119

Cloud licensing APIs ... 2-121

Get license status ... 2-121

EC2 nodes APIs ... 2-123

Get EC2 node stats ... 2-123

Create node in EC2 ... 2-125

Query for all EC2 nodes ... 2-129

Delete node in EC2 ... 2-131

Modify node secondary and virtual addresses in EC2 ... 2-133

OpenStack nodes APIs ... 2-137

Create a new node ... 2-138

Get node ... 2-138

Get all nodes ... 2-140

Get OpenStack Node Stats ... 2-142

Delete Node ... 2-143

3 Shared APIs

Shared APIs overview ...3-1

Group resolver view worker APIs ...3-2

List all the worker URIs under /shared ...3-2

List all the worker URIs under /tm ...3-5

List all the worker URIs under /cm ...3-7

File transfer worker APIs ...3-9

Get file contents using downloads worker ...3-9

Post file contents using downloads worker ...3-9

Cancel existing upload ... 3-10

In statistics helper worker API ... 3-11

Get worker statistics ... 3-12

Update worker statistics ... 3-14

Delete worker statistics ... 3-14

(9)

Set the URIs that will be traced: white list ... 3-21

Shutdown or restart REST server ... 3-22

Multiple user coordinator APIs ... 3-25

Get all user and resource associations ... 3-25

Create a resource association ... 3-27

Remove a resource association ... 3-29

Device resolver APIs ... 3-30

Get device resolver groups ... 3-30

Get a single group ... 3-31

Get devices within a group ... 3-32

Get a single device ... 3-34

Get a single device’s health statistics ... 3-35

Add a new group ... 3-37

Add a new device ... 3-37

Rediscover a POST_FAILED device ... 3-39

Delete a device ... 3-39

Add an existing device to a group ... 3-41

Modifying device properties ... 3-42

Group resolver APIs ... 3-43

Get resolver groups ... 3-43

Query resolver groups ... 3-44

Create resolver groups ... 3-44

Delete resolver group ... 3-45

Device information API ... 3-46

Get device information ... 3-46

statistics information and metadata API ... 3-49

Create a statistics information item ... 3-50

Retrieve all statistics information items ... 3-51

Change a portion of a statistics information item ... 3-54

Replace a statistics information item ... 3-54

Delete a statistics information item ... 3-56

User authentication API ... 3-56

Verify authentication ... 3-56

Authentication token worker API ... 3-58

Create an authentication token ... 3-59

Get all auth-tokens ... 3-59

Get auth-tokens based on UUID ... 3-61

Delete all auth-tokens ... 3-61

Delete auth-tokens based on UUID ... 3-63

Delete auth-tokens based on state (POJO) ... 3-63

Licensing APIs ... 3-65

Get license ... 3-65

Install license ... 3-68

Revoke license ... 3-71

User authorization APIs ... 3-72

Get all users ... 3-72

Get single user ... 3-74

Create user ... 3-75

Update user ... 3-75

Delete user ... 3-76

Authorization roles APIs ... 3-77

Get all roles ... 3-77

Get role ... 3-79

Create new role ... 3-81

(10)

Authz roles resource groups APIs ... 3-85

Get all resource groups ... 3-85

Create a role resource group ... 3-87

Modify a role resource group ... 3-88

Remove a group of resources ... 3-90

Licensing activation APIs ... 3-90

Automatic activation ... 3-91

Post an automatic base key and add-on keys ... 3-91

Check for automatic activation status and get EULA ... 3-92

Post EULA text ... 3-94

Check for automatic activation status and get license ... 3-94

Install license ... 3-96

Manual activation method ... 3-96

Post manual base key and add-on keys ... 3-97

Check for status and get dossier ... 3-97

Install license ... 3-99

Registration key management APIs ... 3-99

Query registration keys ... 3-99

Create a registration key record ... 3-101

Add User-Accepted EULA text ... 3-101

Assign a key to a device ... 3-103

Delete a registration key record ... 3-104

(11)

F5 BIG-IQ REST APIs

• Introduction to BIG-IQ APIs

• BIG-IQ Cloud overview

• BIG-IQ Cloud API conventions

• Ports required for F5 Cloud service REST API

• Uncharacteristic return codes

(12)

(13)

Introduction to BIG-IQ APIs

This guide provides the basic structure of BIG-IQ

™

APIs. The APIs are

organized into two groups, each in a separate chapter.

The first group is referred to as Shared APIs and the second group is

referred to as Central Management APIs. For each API, we define the basic

function and then outline the expected structure for the Request, and

Success Response.

To use the APIs defined in this guide, install the virtual machine that we

have created to accompany it. Instructions for performing this installation

are in the Virtual Edition Setup Guide specific to your hypervisor.

(14)

BIG-IQ Cloud overview

The Cloud Service is part of what F5 refers to as its North-bound interface

(NBI). The NBI allows third party frameworks and service providers to

interact with our cloud deployment and orchestration framework. This

integration enables providers to offer their tenants a spectrum of web

services that are fully configurable, provide customizable service levels, and

provider initiated service deployment, along with monitoring and

maintenance features.

Cloud/Service Providers are organizations who offer or sell cloud services

provided by F5 equipment and products.

Tenants are customers of these organizations who require specific services.

Tenants can use the Tenant Service to configure and monitor their specific

services. It is this Tenant Service that Cloud/Service Providers can use to

manage all their tenants as well as the offerings they make available to them.

Calls for these APIs are made using standard REST semantics and HTTP

verbs.

(15)

BIG-IQ Cloud API conventions

The top-level namespace for BIG-IQ APIs generally follows these

conventions:

[endpoint]/[sub-endpoint]/[module]

[endpoint]/shared/[common functionality]

The endpoint is /mgmt

All BIG-IP

®

traffic management modules are located under the

sub-endpoint of /tm (which corresponds to traffic management).

All BIG-IQ modules are located under the sub-endpoint /cm (which

corresponds to central management).

APIs and workers that may be common to both tm and cm are located under

the sub-endpoint /shared.

An example of a public URI would be:

https://localhost:443/mgmt/cm/firewall/rule-lists

Sub-endpoint Description

/forwarder Public to internal entry point, authz evaluation,

maps to https://hostname:443/mgmt /mgmt/shared/resolver/group

s

Organizing collection, directory of workers

/mgmt/shared/authz/users authz

/mgmt/shared/diagnostics Diagnostics worker, tracing support, process and node resource use API

/mgmt/shared/authz/roles RBAC

/mgmt/shared/echo Validation/canary worker

/mgmt/cm/firewall big-iq security firewall mgr namespace

/mgmt/cm/cloud big-iq cloud mgr namespace

/mgmt/tm/ltm tmapi ltm

/mgmt/tm/gtm tmapi gtm

/mgmt/tm/asm tmapi asm

/mgmt/tm/... tmapi or new control plane workers for other

(16)

Ports required for F5 Cloud service REST API

The F5 Cloud Service Manager REST API is exposed through HTTPS (port

(17)

Uncharacteristic return codes

Bad Gateway

There are certain rare circumstances in which a return code of

502 Bad Gateway

can result when you submit an API call. If this occurs,

wait a minute and resubmit the API call.

Service Temporarily Unavailable

There are certain rare circumstances in which a return code of

503 Service Temporarily Unavailable

can result when you submit

an API call. If this occurs, wait a minute and resubmit the API call.

(18)

(19)

Central Management APIs

• Central management APIs

• Templates iApp collection worker APIs

• Provider iApp template APIs

• Sample provider template APIs

• Tenant iApp templates APIs

• Tenant APIs

• Tenant services APIs

• Tenant service health APIs

• Tenant virtual servers APIs

• Tenant service server tiers APIs

• Tenant node APIs

• Tenant cloud connectors APIs

• Cloud connector APIs

• Local cloud connector APIs

• EC2 cloud connectors APIs

• OpenStack cloud connector APIs

• VMware cloud connector APIs

• Cloud managed devices APIs

• Cloud licensing APIs

(20)

(21)

Central management APIs

The APIs referred to as central management APIs are documented in this

chapter.

Templates iApp collection worker APIs

These APIs provide an aggregation point for all iApp templates that are

available from the devices managed by the BIG-IQ

™

Cloud. Child URIs are

supported based on the iApp template name.

Get templates

Description _{Gets the set of currently known iApp templates supported by all managed devices.}

URL _{/mgmt/cm/cloud/templates/iapp}

Verb/Method _GET

Query Parameters _N/A

Data Parameters

(22)

Success Response

NOTE: Example is truncated for brevity.

NOTE: Example below is truncated for brevity. { "items": [ { "name": "f5.bea_weblogic", "deviceReferences": [ { "link": "https://10.22.22.2:443" } ], "template": { "vars": [ { "name": "optimizations__policy", "isRequired": false,

"defaultValue": "/Common/Generic Policy - Enhanced" } ], "tables": [ { "name": "basic__snatpool_members", "isRequired": false, "columns": [ { "name": "addr", "isRequired": true } ] }, { "name": "optimizations__hosts", "isRequired": false, "columns": [ { "name": "host", "isRequired": true } ] } ] }, "generation": 2, "lastUpdateMicros": 1361401599050490, "kind": "cm:cloud:templates:iapp:templatesiappitemstate", "selfLink": "https://localhost/mgmt/cm/cloud/templates/iapp/f5.bea_weblogic" } ], "generation": 27, "kind": "cm:cloud:templates:iapp:templatesiappcollectionworkerstate", "lastUpdateMicros": 1361401599622103, "selfLink": "https://localhost/mgmt/cm/cloud/templates/iapp" }

Error Response _{HTTP/1.1 401 Unauthorized}

(23)

Update template item

Description _{Replaces the template item in the collection}

URL _{/mgmt/cm/cloud/templates/iapp/{iapp name}}

Verb/Method _PUT

(24)

Data Parameters /example { "name": "f5.bea_weblogic", "deviceReferences": [ { "link": "https://10.22.22.2:443" } ], "template": { "vars": [ { "name": "optimizations__policy", "isRequired": false,

"defaultValue": "/Common/Generic Policy - Enhanced" } ], "tables": [ { "name": "basic__snatpool_members", "isRequired": false, "columns": [ { "name": "addr", "isRequired": true } ] }, { "name": "optimizations__hosts", "isRequired": false, "columns": [ { "name": "host", "isRequired": true } ] } ] }, "generation": 2, "lastUpdateMicros": 1361401599050490,

(25)

Create new template item

Sample Call

Notes Related URIs

Description _{Creates a new template item.}

URL _{/mgmt/cm/cloud/templates/iapp}

Verb/Method _POST

(26)

Data Parameters /example { "name": "f5.bea_weblogic", "deviceReferences": [ { "link": "https://10.22.22.2:443" } ], "template": { "vars": [ { "name": "optimizations__policy", "isRequired": false,

"defaultValue": "/Common/Generic Policy - Enhanced" } ], "tables": [ { "name": "basic__snatpool_members", "isRequired": false, "columns": [ { "name": "addr", "isRequired": true } ] }, { "name": "optimizations__hosts", "isRequired": false, "columns": [ { "name": "host", "isRequired": true } ] } ] } } Success Response _{HTTP/1.1 200 OK}

(27)

Delete template item

Description _{Deletes an item from a template. Note that this should only be done by the system.}

URL _{/mgmt/cm/cloud/templates/{iapp name}}

Verb/Method _DELETE

Data Parameters /example { "items": [ { "name": "f5.bea_weblogic", "deviceReferences": [ { "link": "https://10.22.22.2:443" } ], "template": null, "generation": 2, "lastUpdateMicros": 1360700356339674, "kind": "cm:cloud:templates:iapp2:templatesiappitemstate", "selfLink": "https://localhost/mgmt/cm/cloud/templates/iapp2/f5.bea_weblogic" } ] } Success Response _{HTTP/1.1 200 OK}

Sample Call

(28)

Provider iApp template APIs

Providers who want to make services available to their tenants need to

construct provider iApp templates. The provider iApp templates are

populated with custom configuration settings that, when applied to a

specific BIG-IP iApp template, define a baseline level of performance to

which a service must conform when deployed. Having these baseline levels

of performance allows the provider to advertise different service levels to

their tenants.

What is an iApp template?

An iApp is a BIG-IP

®

system configuration template that makes it easy to

configure a BIG-IP system for a specific application.

In the BIG-IP user interface, an iApp appears as a set of questions that users

need to answer. Internally, an iApp can be considered as a set of variables

with values: answering a question corresponds to providing a value for a

variable.

What is a provider iApp template?

A provider iApp template (often referred to as just a provider template) is an

iApp template in which some or all of the iApp template variables have been

filled in by the provider. When a tenant wants to deploy an application, he

specifies only the parameters that the provider has not set. A provider iApp

template simplifies the process of deploying an application for a tenant, and

it also allows the provider to clearly specify different ways of deploying an

application. Often this allows different levels of service.

For example, a provider might create a provider template for a web (HTTP)

server that configures the use of the BIG-IP system SSL termination so that

tenants do not need to understand how it works but simply benefit from it.

Or a provider could create multiple provider templates for different levels of

service (that is, templates that permit different numbers of simultaneous

connections).

How does a provider make an iApp template?

(29)

Figure 2.1 Provider template call flows

Conceptually, making a provider template is straightforward: take an iApp

template, set values for variables that tenants cannot edit, and you have a

provider template. In practice it can be more complicated, because doing

this correctly requires a deeper understanding of the underlying iApp

template so that you can make the template correctly.

There is a REST API (documented separately in the Provider Template

Example API) that allows you to start with a working provider template and

make any necessary changes to it. This is the recommended path for creating

provider templates

The structure of a provider template

A provider template specifies several things

• The iApp template that it is based on. Every provider template is based

on exactly one BIG-IP iApp template.

• A set of scalar variables. That is, variables with a single value. For

example, the virtual IP is a scalar variable.

• A set of tables. For example, the set of pool members is a table. Each row

in the table is a single pool member, and (depending on the underlying

(30)

A (shortened) example of a provider template looks like this:

{ "templateName": "HTTP-Bronze", "parentReference": { "link": "https://localhost/mgmt/cm/cloud/templates/iapp/f5.http" }, "overrides": { "vars": [ { "name": "basic__addr", "isRequired": true, "defaultValue": "", "providerType": "NODE", "serverTier": "Servers" }, { "name": "basic__port", "isRequired": true, "provider": "80", "providerType": "PORT", "serverTier": "Servers" } ], "tables": [ { "name": "server_pools__servers", "columns": [ { "name": "addr", "isRequired": true, "defaultValue": "", "providerType": "NODE" }, { "name": "port", "isRequired": true, "provider": "80", "providerType": "PORT" } ], "serverTier": "Servers" }, ] }, "properties": [ { "id": "cloudConnectorReference", "displayName": "Cloud Connector", "isRequired": true

}, {

"id": "deviceImageReference", "displayName": "Device Image", "isRequired": false,

"description": "When connector supports automatic deployment of Devices, Provider will use this property to indicate which Device image is appropriate to use for deployment of this iApp

template. It is expected that reference will point to a Node TEMPLATE.", "provider": "https://localhost/mgmt/cm/connectors/ec2/GUID1234-GUID-1234-GUID-1234GUID1234/nodes/GUID1234-GUID-1234 -GUID-1234GUID1234" } ], "tenantTemplateReference": { "link": "https://localhost/mgmt/cm/cloud/tenant/templates/iapp/HTTP-Bronze" }, "isF5Example": false,

(31)

Tenant templates

When you create a provider template, a tenant template is created for it.

(That is, you do not need to create it.) A tenant template is a provider

template that has had all of the provider variables removed. Tenant

templates can be used to understand which parameters a tenant can specify

when creating a tenant service.

Variables

A variable in the provider template has the following form:

{ "name": "variableName". "displayName": "name", "description": "description", "isRequired": booleanValue, "defaultValue": "someValue", "provider": "someValue",

"providerType": "TYPE" # see below "serverTier": "name"

}

Explanation of variables

Field Description

name The name of the variable. White space is not allowed.

displayName A human-readable version of the variable name (optional)

description A longer description of the purpose of the variable (optional)

isRequired If true, then the value must be supplied when creating an iApp service, unless the provider specified a fixed value using the provider field or a default value.

defaultValue The default value that will be used for the field when a user creates an iApp service based on this template.

provider Also a default value, but indicates that a tenant may not edit this value.

providerType If the value is NODE, then the variable or column is an IP address. If the value is PORT, then the variable or column is a port number. If the value is var, it indicates the virtual IP address for the given server tier. If the value is a table, it indicates a server pool for the given server tier. If the value is SSL_CERT, then variable is an SSL certificate path. If the value is SSL_KEY, then variable is an SSL certificate private key path.

serverTier If specified for a variable, then the variable represents a virtual server interface. At least one virtual server interface must be specified or it is an error. If specified for a table, then the table represents a set of pool members.

(32)

The defaultValue and provider are mutually-exclusive fields: only one can

be specified. A variable is referred to as "tenant-editable" if the provider

field is not set.

Properties

A property in the provider template has the following form:

{

"id": "name",

"displayName": "Descriptive Name",

"description": "Descriptive text about the property", "isRequired": booleanValue,

"value": "someValue", "provider": "someValue", }

Explanation of properties

The value and provider are mutually-exclusive fields: only one can be

specified. You must specify a cloud property when creating a provider

template, but it is okay to have no default value--this will be a

tenant-editable property.

id The name of the property. White space is not allowed.

displayName A user-friendly name for the property. White space is allowed.

description Some longer text describing the purpose of the property.

isRequired A boolean, true or false

value If the tenant does not specify a value, this value will be used.

(33)

Get provider iApp templates

Description _{Gets a list of the created provider iApp templates.}

URL _{/mgmt/cm/cloud/provider/templates/iapp}

Data Parameters

(34)

Success Response _{ "generation": 1, "items": [ { "generation": 1, "templateName": "f5.httpstat.provider", "parentReference": { "link": "/mgmt/cm/cloud/devices/templates/iapp/f5.httpstat" }, "overrides": { "vars": [ { "name": "net__client_mode", "isRequired": true, "provider": "wan" }, { "name": "net__server_mode", "isRequired": true, "provider": "lan" }, { "name": "pool__addr", "displayName": "Virtual IP Address", "description": "The address of the VIP", "isRequired": true, "providerType": "NODE", "serverTier": "default" }, { "name": "pool__port", "isRequired": true, "provider": "80", "providerType": "PORT", "serverTier": "default" } ], "tables": [ { "name": "pool__members", "columns": [ { "name": "addr", "isRequired": false, "providerType": "NODE" }, { "name": "port", "isRequired": true, "provider": "80", "providerType": "PORT" }, { "name": "port_secure", "isRequired": true, "provider": "443" } ], "serverTier": "default" }, { "name": "basic__snatpool_members", "columns": [ { "name": "addr", "isRequired": true, "providerType": "NODE" } ] }, { "name": "server_pools__servers", "columns": [ { "name": "addr", "isRequired": true, "providerType": "NODE" }, { "name": "port", "isRequired": true, "provider": "80", "providerType": "PORT" } ] } ] }, "kind": "cm:cloud:provider:templates:iapp:providerservicetemplateworkerstate", "selfLink": "https://localhost/mgmt/cm/cloud/provider/templates/iapp/f5.httpstat.provider" } ], "properties": [ { "id": "cloudConnectorReference", "displayName": "Cloud Connector", "isRequired": true,

"provider": "http://localhost/mgmt/cm/cloud/connectors/ec2/4bcf6ac5-7e52-48f8-ada2-3fa26103dfdc" },

{

"id": "shoeSize", "displayName": "Shoe Size", "isRequired": true,

(35)

Create provider iApp template

Sample Call

Notes

Related URIs _{Tenant Templates} _{/mgmt/cm/cloud/tenant/templates/iapp}

Description _{Creates a new customized provider template.}

URL _{/mgmt/cm/cloud/provider/templates/iapp}

(36)

Data Parameters

/example { "templateName": "f5.httpstat.provider", "parentReference": { "link": "/mgmt/cm/cloud/devices/templates/iapp/f5.httpstat" }, "overrides": { "vars": [ { "name": "net__client_mode", "isRequired": true, "provider": "wan" }, { "name": "net__server_mode", "isRequired": true, "provider": "lan" }, { "name": "pool__addr", "isRequired": true, "providerType": "NODE", "serverTier": "default" }, { "name": "pool__port", "isRequired": true, "provider": "80", "providerType": "PORT", "serverTier": "default" } ], "tables": [ { "name": "pool__members", "columns": [ { "name": "addr", "isRequired": false, "providerType": "NODE" }, { "name": "port", "isRequired": true, "provider": "80", "providerType": "PORT" }, { "name": "port_secure", "isRequired": true, "provider": "443" } ], "serverTier": "default" }, { "name": "basic__snatpool_members", "columns": [ { "name": "addr", "isRequired": true, "providerType": "NODE" } ] }, { "name": "server_pools__servers", "columns": [ { "name": "addr", "isRequired": true, "providerType": "NODE" }, { "name": "port", "isRequired": true, "provider": "80", "providerType": "PORT" } ] } ] }, "properties": [ { "id": "cloudConnectorReference", "displayName": "Cloud Connector", "isRequired": true,

{

"id": "shoeSize", "displayName": "Shoe Size", "isRequired": true,

(37)

Get customized provider template parameters

Success Response _{HTTP/1.1 200 OK}

Error Response _{HTTP Error code}

Sample Call

Notes

Description _{Gets the customized parameters for a specific provider template.}

URL _{/mgmt/cm/cloud/provider/templates/iapp/<template-id>}

Data Parameters /example

(38)

Success Response _{ "generation": 1, "templateName": "f5.httpstat.provider", "parentReference": { "link": "/mgmt/cm/cloud/devices/templates/iapp/f5.httpstat" }, "overrides": { "vars": [ { "name": "net__client_mode", "isRequired": true, "provider": "wan" }, { "name": "net__server_mode", "isRequired": true, "provider": "lan" }, { "name": "pool__addr", "isRequired": true, "providerType": "NODE", "serverTier": "default" }, { "name": "pool__port", "isRequired": true, "provider": "80", "providerType": "PORT", "serverTier": "default" }, ], "tables": [ { "name": "pool__members", "columns": [ { "name": "addr", "isRequired": false, "providerType": "NODE" }, { "name": "port", "isRequired": true, "provider": "80", "providerType": "PORT" }, { "name": "port_secure", "isRequired": true, "provider": "443" }, ], "serverTier": "default" }, { "name": "basic__snatpool_members", "columns": [ { "name": "addr", "isRequired": true, "providerType": "NODE" } ] }, { "name": "server_pools__servers", "columns": [ { "name": "addr", "isRequired": true, "providerType": "NODE" }, { "name": "port", "isRequired": true, "provider": "80", "providerType": "PORT" } ] } ] }, "properties": [ { "id": "cloudConnectorReference", "displayName": "Cloud Connector", "isRequired": true,

{

"id": "shoeSize", "displayName": "Shoe Size",

(39)

Delete provider iApp template

Sample Call

Notes

Description _{Deletes the specified provider iApp templates}

URL _{/mgmt/cm/cloud/provider/templates/iapp/<template-id>}

Sample Call

Notes

(40)

Sample provider template APIs

It can be challenging to create provider templates from scratch. To aid in

creating provider templates, there is a worker that users can query in order to

get sample provider templates. While you have the option of customizing

them further, these samples can simply be posted to the sample provider

template as-is to make a functioning provider template.

Get example provider template for a corresponding iApp template

This function returns an example provider template based on the underlying

NAME iApp template.

The name is the same as the name of one of the underlying templates. These

names can be discovered by querying the BIG-IQ iApp Template Worker

(

/cm/cloud/templates/iapp

).

Note

There is always an example named example. There may be other examples.

You can get the complete list.

Minimal modification needs to be done in order to post this as an actual

provider template. You will need to edit two fields:

• templateName

• properties: A cloudConnectorReference needs to be provided

Note

This provider template does not exist until you edit it and POST it to the

provider template API. This is merely an example of how to create a

provider template.

Description _{Gets an example provider iApp template for a given iApp template.}

URL _{/mgmt/cm/cloud/templates/iapp/NAME/providers/EXAMPLE-NAME/}

Data Parameters

(41)

Get example provider template for a corresponding iApp template

Find all provider template examples

Notes

Related URIs _{Provider iApp Templates} _{/mgmt/cm/cloud/provider/templates/iapp}

Templates iApp Collection Worker /mgmt/cm/cloud/templates/iapp

Description _{Gets a list of all example provider iApp templates for a given iApp template}

URL _{/mgmt/cm/cloud/templates/iapp/NAME/providers/}

Query Parameters _None

Data Parameters

/example None

Success Response _{A standard provider template: see the provider template API for an example.}

Sample Call

Notes

Related URIs _{Provider iApp Templates} _{/mgmt/cm/cloud/provider/templates/iapp}

Templates iApp Collection Worker /mgmt/cm/cloud/templates/iapp

Description _{Gets a list of all example provider iApp templates for a given iApp template.}

URL _{/mgmt/shared/index/config?$filter=kind eq}

'cm:cloud:provider:templates:iapp:provideriapptemplateworkerstate' and isF5Example eq 'true'

Query Parameters _None

Data Parameters

(42)

Success Response _{ "currentItemCount": 0, "itemsPerPage": 0, "pageIndex": 0, "selfLink": "http://localhost:8100/shared/index/config?$filter=kind%20eq%20%27cm:cloud:provider:temp lates:iapp:provideriapptemplateworkerstate%27%20and%20isF5Example%20eq%20%27true %27", "startIndex": 0, "totalItems": 28, "totalPages": 0, "items": [ { "templateName": "f5.bea_weblogic-example", ... templates trimmed } ] }

Sample Call

(43)

Tenant iApp templates APIs

Tenants can access the template catalog by going to this API. It allows them

to determine what configuration is necessary for each template.

{tenant_id} = "soda2" as particular Tenant instance; {customized_iapp_template_id} = "Exchange-Gold" as particular customized (Provider-specific)

iapp template instance;

{tenant_iapp_service_id} = "my-exchange-gold-service" as particular running instance of Tenant service;

The figure illustrates the call flow for creating a tenant template.

Figure 2.2 Tenant template call flow

Variables

A variable in the tenant template has the following form:

{

"name": "variableName". "isRequired": booleanValue, "defaultValue": "someValue", "providerType": "TYPE" # see below "serverTier": "name"

(44)

Explanation of variables

Note

The variables listed are the same as the ones in the corresponding provider

templates, but without the provider variables.

Properties

A property in the provider template has the following form:

{

"id": "name",

"displayName": "Descriptive Name",

"description": "Descriptive text about the property", "isRequired": booleanValue,

"value": "someValue", }

name The name of the variable. White space is not allowed.

isRequired If true, then the value must be supplied when creating an iApp service, unless the provider specified a fixed value using the provider field or a default value.

defaultValue The default value that will be used for the field when a user creates an iApp service based on this template.

providerType If the value is NODE, then the variable or column is an IP address. If the value is PORT, then the variable or column is a port number. If the value is var, it indicates the virtual IP address for the given server tier. If the value is a table, it indicates a server pool for the given server tier.

serverTier If specified for a variable, then the variable represents a virtual server interface. At least one virtual server interface must be specified or it is an error. If specified for a table, then the table represents a set of pool members.

(45)

Explanation of properties

Note that the variables listed are the same as the ones in the corresponding

provider templates, but without the provider variables.

Get all tenant iApp templates

displayName A user-friendly name for the property. White space is allowed.

description Some longer text describing the purpose of the property.

isRequired A boolean, true or false.

value If the tenant does not specify a value, this value will be used.

Description _{Gets all of the tenant iApp templates from the provider catalog. Note that tenants only see the}

parts of the template that the provider allowed.

URL _{/mgmt/cm/cloud/tenant/templates/iapp}

Data Parameters

(46)

Success Response { "items: [ { "name": "basic.template", "generation": 1, "sections": [ { "displayName": "intro", "description": "Introduction" }, { "displayName": "pool", "description": "Pool Address" ], "vars": [ { "name": "intro__ltm_provisioned", "isRequired": false, "section": "intro", "displayName": "ltm_provisioned", }, { "name": "pool__addr", "isRequired": true, "providerType": "NODE", "serverTier": "default", "section": "pool", "displayName": "addr", "description": "Enter pool address" }, { "name": "basic__addr", "isRequired": true } ], "tables": [ { "name": "pool__members", "serverTier": "default", "isRequired": false, "section": "pool", "displayName": "members",

"description": "Enter pool member addresses" "columns": [ { "name": "addr", "isRequired": false, "providerType": "NODE" } ] }, { "name": "server_pools__servers", "isRequired": false, "columns": [ { "name": "addr", "isRequired": true, "providerType": "NODE" } ] } ], "properties": [ { "id": "shoeSize",

(47)

Sample Call

Notes

(48)

Get tenant iApp template configuration

Description _{Gets the configuration parameters for one tenant iApp template.}

URL _{/mgmt/cm/cloud/tenant/templates/iapp/<template-id>}

Data Parameters

(49)

Success Response _{ "name": "basic.template", "sections": [ { "displayName": "intro", "description": "Introduction" }, { "displayName": "pool", "description": "Pool Address" } ], "vars": [ { "name": "intro__ltm_provisioned", "isRequired": false }, { "name": "pool__addr", "isRequired": true, "providerType": "NODE", "serverTier": "default", "section": "pool", "displayName": "addr",

"description": "Enter pool address" }, { "name": "basic__addr", "isRequired": true } ], "tables": [ { "name": "pool__members", "serverTier": "default", "isRequired": false, "section": "pool", "displayName": "members",

"description": "Enter pool member addresses" "columns": [ { "name": "addr", "isRequired": false, "providerType": "NODE" } ] }, { "name": "server_pools__servers", "isRequired": false, "columns": [ { "name": "addr", "isRequired": true, "providerType": "NODE" } ] } ], "properties": [ { "id": "shoeSize", "displayName": "Shoe Size", "isRequired": true, "value": "7EEEE" } ], "generation": 1 }

(50)

Tenant APIs

Providers advertise what services they make available to their customers.

Customers who make use of the provider’s services are known as tenants.

Providers need a way to track customers who use their services. To do so,

providers track them as tenants. Each tenant is identified using a name and a

description.

• The name is used to refer to the tenant in a URI.

• The description is used to refer to the tenant in conversation.

For example, a tenant can have the name soda2 and the description Soda 2

Tenant.

Notes

(51)

Get all tenants

Description _{Gets all of the tenants}

URL _{/mgmt/cm/cloud/tenants}

Data Parameters /example Success Response _{ "items": [ { "name": "soda2",

"description": "soda2 Tenant", "addressContact": "123 Fake St.", "phone": "(206) 555-1212", "email": "[email protected]",

"userReference": {"link": "http://localhost/mgmt/shared/authz/user/soda2"}, "roleReference": {"link": "http://localhost/mgmt/shared/authz/roles/soda2_12345"}, "cloudConnectorReferences": [ {"link": "http://localhost/mgmt/cm/cloud/connectors/vmware/67890"} ], "generation": 2 }, { "name": "soda1",

"userReference": {"link": "http://localhost/mgmt/shared/authz/user/soda1"}, "roleReference": {"link": "http://localhost/mgmt/shared/authz/roles/soda1_54321"}, "cloudConnectorReferences": [ {"link": "http://localhost/mgmt/cm/cloud/connectors/local/09876"} ], "generation": 1 } ] }

Sample Call

(52)

Get one tenant information

Create tenant

Description _{Retrieves information for one tenant.}

URL _{/mgmt/cm/cloud/tenants/<tenant-id>}

Success Response _{

"name": "soda2",

"userReference": {"link": "http://localhost/mgmt/shared/authz/user/soda2"}, "roleReference": {"link": "http://localhost/mgmt/shared/authz/roles/soda2_12345"}, "cloudConnectorReferences": [ {"link":

"http://localhost/mgmt/cm/cloud/connectors/vmware/67890"} ] }

Sample Call

Description _{Creates one new tenant.}

URL _{/mgmt/cm/cloud/tenants}

(53)

Data Parameters

/example {

"name": "soda2",

"description": "Soda 2 Tenant", "addressContact": "123 Fake St.", "phone": "(206) 555-1212", "email": "[email protected]",

"http://localhost/mgmt/cm/cloud/connectors/vmware/67890"} ] }

Sample Call

(54)

Update tenant information

Delete one tenant

Description _{Changes one tenant's information.}

Verb/Method _PUT

Data Parameters

/example {

"name": "soda2",

"http://localhost/mgmt/cm/cloud/connectors/vmware/67890"} ], "generation": 2

}

Sample Call

Notes _{Specify all fields. Do not change the name. Increment the generation number.}

Related URIs

Description _{Deletes a tenant.}

(55)

Tenant services APIs

These APIs make it possible for a tenant to manage his own application

services.

Properties

A tenant service request contains a list of optional properties, each of which

has the following form:

{

"id": "name",

"value": "someValue", }

Explanation of properties

You can only specify properties if they are also in the tenant template

referenced by the tenant service request.

Sample Call

(56)

Get service instances

Description _{Retrieves the list of service instances that have been deployed by the tenant.}

URL _{/mgmt/cm/cloud/tenants/<tenant-id>/services/iapp}

(57)

Success Response _{ "items": [ { "name": "https-app1", "tenantTemplateReference": { "link": "https://localhost/mgmt/cm/cloud/tenant/templates/iapp/https-gold" }, "tenantReference": { "link": "https://localhost/mgmt/cm/cloud/tenants/TheTenantName" }, "vars": [ { "name": "pool__addr", "value": "10.0.1.210" }, { "name": "ssl__cert", "value": "/Common/https-app1_Servers.crt" }, { "name": "ssl__key", "value": "/Common/https-app1_Servers.key" } ], "tables": [ { "name": "pool__hosts", "columns": [ "name" ], "rows": [ [ "example.com" ] ] }, { "name": "pool__members", "columns": [ "addr", "port" ], "rows": [ [ "10.0.2.94", "80" ] ] } ], "properties": [], "vipProxyAddressByServerTierName": { "Servers": "54.201.90.23" }, "serverTiersWithProvisionedVips": [ "Servers" ], "serverTierSslCerts": [ { "tier": "Servers", "name": "https-app1_Servers" } ],

"error" : "error description if any", "generation": 6,

"lastUpdateMicros": 1391551332270011, "kind": "cm:cloud:tenants:tenantserviceinstance",

"selfLink": "https://localhost/mgmt/cm/cloud/tenants/TheTenantName/services/iapp/https-app1" },

.... Sample response truncated for brevity...

(58)

Get service instance configuration

Description _{Retrieves configuration for a given tenant service.}

URL _{/mgmt/cm/cloud/tenants/<tenant-id>/services/iapp/<service-id>}

(59)

Success Response _{ "name": "https-app1", "tenantTemplateReference": { "link": "https://localhost/mgmt/cm/cloud/tenant/templates/iapp/https-gold" }, "tenantReference": { "link": "https://localhost/mgmt/cm/cloud/tenants/TheTenantName" }, "vars": [ { "name": "pool__addr", "value": "10.0.1.210" }, { "name": "ssl__cert", "value": "/Common/https-app1_Servers.crt" }, { "name": "ssl__key", "value": "/Common/https-app1_Servers.key" } ], "tables": [ { "name": "pool__hosts", "columns": [ "name" ], "rows": [ [ "example.com" ] ] }, { "name": "pool__members", "columns": [ "addr", "port" ], "rows": [ [ "10.0.2.94", "80" ] ] } ], "properties": [], "vipProxyAddressByServerTierName": { "Servers": "54.201.90.23" }, "serverTiersWithProvisionedVips": [ "Servers" ], "serverTierSslCerts": [ { "tier": "Servers", "name": "https-app1_Servers" } ],

"error" : "error description if any", "generation": 6,

"lastUpdateMicros": 1391551332270011, "kind": "cm:cloud:tenants:tenantserviceinstance",

"selfLink": "https://localhost/mgmt/cm/cloud/tenants/TheTenantName/services/iapp/https-app1" }

(60)

Delete service instances

Create service instance

The fields this API uses are described in the table.

Notes _{The information returned only includes the tenant-provided values, and not the provider values}

from the provider template.

Related URIs

Description _{Deletes an active tenant service.}

URL _{/mgmt/cm/cloud/tenants/<tenant-id>/services/iapp/<service-id>}

Sample Call

pool_addr If the connector supportsVirtualServerProvisioning is true, then specifying 0.0.0.0 instructs BIG-IQ Cloud to dynamically assign a virtual server address. Otherwise, specify the exact address to be used.

serverTiersInfo Required only if you are deploying an elastic service. This field provides a list of additional information for the server tiers in the service.

serverTiersInfo[0].name The name of a server tier in a service.

serverTiersInfo[0].nodeTemplateReference A reference to a node template that will be used to create new nodes in the server tier when it expands.