BIG-IQ API Reference Guide

Transcription

1 BIG-IQ API Reference Guide version PUB

2

3 Legal Notices Product Version This manual applies to version of BIG-IQ system. Publication Date This document was published on February 25, Publication Number PUB 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: 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. BIG-IQ API Reference Guide i

4 FCC Compliance This equipment has been tested and found to comply with the limits for a Class A digital device pursuant to Part 15 of FCC rules. These limits are designed to provide reasonable protection against harmful interference when the equipment is operated in a commercial environment. This unit generates, uses, and 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. ii

5 Table of Contents

6 Table of Contents 1 F5 BIG-IQ REST APIs Introduction to cloud service APIs BIG-IQ Cloud overview BIG-IQ Cloud API conventions Ports required for F5 Cloud service REST API Uncharacteristic return codes Bad Gateway Service Temporarily Unavailable Central Management APIs Central management APIs Templates iapp collection worker APIs Get templates Update template item Create new template item Delete template item Provider iapp template APIs What is an iapp template? What is a provider iapp template? How does a provider make an iapp template? The structure of a provider template Tenant templates Variables Properties Get provider iapp templates Create provider iapp template Get customized provider template parameters Delete provider iapp template Sample provider template APIs Get example provider template for a corresponding iapp template Get example provider template for a corresponding iapp template Find all provider template examples Tenant iapp templates APIs Variables Properties Get all tenant iapp templates Get tenant iapp template configuration Tenant APIs Get all tenants Get one tenant information Create tenant Update tenant information Delete one tenant Tenant services APIs Properties Get service instances Get service instance configuration Delete service instances Create service instance Update service instance Get example-stats Tenant service health APIs xvi

7 Table of Contents Get service health Tenant virtual servers APIs Get all virtual servers Get one virtual server Get example-stats Tenant service server tiers APIs Get server tiers Get servers in tier Tenant node APIs Create node Query for all tenant nodes Query example-stats for tenant nodes Tenant cloud connectors APIs Get all tenant cloud connectors Get tenant connector Cloud connector APIs Types of cloud connectors Creating a cloud connector Deploying an application in the cloud Cloud connector description Explanation of fields Parameters Parameters for specific cloud types Discovering a cloud connector's parameters Create a cloud connector Change a cloud connector Get a cloud connector Get health of a cloud connector Get all cloud connectors of a given type Get all cloud connectors of all types (brief) Get all cloud connectors of all types (detailed) Delete a cloud connector Local cloud connector APIs Parameters Explanation of fields Parameters Parameters for local clouds Create a local cloud connector Change a local cloud connector Get a cloud connector Get all local cloud connectors Get health of a local cloud connector Delete a local cloud connector EC2 cloud connectors APIs EC2 Connector Topology Parameters for EC2 cloud connectors Create an EC2 cloud connector Change an EC2 cloud connector Get an EC2 connector Get health of an EC2 cloud connector Get all EC2 cloud connectors Delete an EC2 cloud connector OpenStack cloud connector APIs Parameters for OpenStack cloud connectors Create an OpenStack cloud connector Change an OpenStack cloud connector BIG-IQ API Reference Guide xvii

8 Table of Contents Get an OpenStack cloud connector Get health of an OpenStack cloud connector Get all OpenStack cloud connector Delete an OpenStack cloud connector VMware cloud connector APIs Parameters for VMware cloud connectors Create a VMware cloud connector Change a VMware cloud connector Get a VMware cloud connector Get health of a VMware cloud connector Get all VMware cloud connector Delete a VMware cloud connector Cloud managed devices APIs Get managed devices Add a managed device Recover a device in the POST_FAILED state Delete a managed device Cloud licensing APIs Get license status EC2 nodes APIs Get EC2 node stats Create node in EC Query for all EC2 nodes Delete node in EC Modify node secondary and virtual addresses in EC OpenStack nodes APIs Create a new node Get node Get all nodes Get OpenStack Node Stats Delete Node Shared APIs Shared APIs overview Group resolver view worker APIs List all the worker URIs under /shared List all the worker URIs under /tm List all the worker URIs under /cm File transfer worker APIs Get file contents using downloads worker Post file contents using downloads worker Cancel existing upload In statistics helper worker API Get worker statistics Update worker statistics Delete worker statistics REST worker availability APIs Get worker availability REST worker subscriber s list APIs Get worker availability Rest diagnostics worker APIs Get diagnostics Get device statistics diagnostics Set the tracing and logging levels xviii

9 Table of Contents Set the URIs that will be traced: white list Shutdown or restart REST server Multiple user coordinator APIs Get all user and resource associations Create a resource association Remove a resource association Device resolver APIs Get device resolver groups Get a single group Get devices within a group Get a single device Get a single device s health statistics Add a new group Add a new device Rediscover a POST_FAILED device Delete a device Add an existing device to a group Modifying device properties Group resolver APIs Get resolver groups Query resolver groups Create resolver groups Delete resolver group Device information API Get device information statistics information and metadata API Create a statistics information item Retrieve all statistics information items Change a portion of a statistics information item Replace a statistics information item Delete a statistics information item User authentication API Verify authentication Authentication token worker API Create an authentication token Get all auth-tokens Get auth-tokens based on UUID Delete all auth-tokens Delete auth-tokens based on UUID Delete auth-tokens based on state (POJO) Licensing APIs Get license Install license Revoke license User authorization APIs Get all users Get single user Create user Update user Delete user Authorization roles APIs Get all roles Get role Create new role Update a role Delete role BIG-IQ API Reference Guide xix

10 Table of Contents Authz roles resource groups APIs Get all resource groups Create a role resource group Modify a role resource group Remove a group of resources Licensing activation APIs Automatic activation Post an automatic base key and add-on keys Check for automatic activation status and get EULA Post EULA text Check for automatic activation status and get license Install license Manual activation method Post manual base key and add-on keys Check for status and get dossier Install license Registration key management APIs Query registration keys Create a registration key record Add User-Accepted EULA text Assign a key to a device Delete a registration key record xx

11 1 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 F5 BIG-IQ REST APIs 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. 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. BIG-IQ API Reference Guide 1-1

14 Chapter 1 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. 1-2

15 F5 BIG-IQ REST APIs 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. Sub-endpoint /forwarder /mgmt/shared/resolver/group s /mgmt/shared/authz/users /mgmt/shared/diagnostics /mgmt/shared/authz/roles /mgmt/shared/echo /mgmt/cm/firewall /mgmt/cm/cloud /mgmt/tm/ltm /mgmt/tm/gtm /mgmt/tm/asm /mgmt/tm/... Public to internal entry point, authz evaluation, maps to Organizing collection, directory of workers authz Diagnostics worker, tracing support, process and node resource use API RBAC Validation/canary worker big-iq security firewall mgr namespace big-iq cloud mgr namespace tmapi ltm tmapi gtm tmapi asm tmapi or new control plane workers for other modules/functionality An example of a public URI would be: BIG-IQ API Reference Guide 1-3

16 Chapter 1 Ports required for F5 Cloud service REST API The F5 Cloud Service Manager REST API is exposed through HTTPS (port 443). 1-4

17 F5 BIG-IQ REST APIs 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. BIG-IQ API Reference Guide 1-5

18 Chapter 1 1-6

19 2 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 EC2 nodes APIs OpenStack nodes APIs

20

21 Central Management APIs 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 Gets the set of currently known iapp templates supported by all managed devices. /mgmt/cm/cloud/templates/iapp GET N/A None BIG-IQ API Reference Guide 2-1

22 Chapter 2 NOTE: Example is truncated for brevity. NOTE: Example below is truncated for brevity. "items": [ "name": "f5.bea_weblogic", "devicereferences": [ "link": " "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": , "kind": "cm:cloud:templates:iapp:templatesiappitemstate", "selflink": " "generation": 27, "kind": "cm:cloud:templates:iapp:templatesiappcollectionworkerstate", "lastupdatemicros": , "selflink": " 2-2

23 Central Management APIs Update template item Replaces the template item in the collection /mgmt/cm/cloud/templates/iapp/iapp name PUT N/A BIG-IQ API Reference Guide 2-3

24 Chapter 2 "name": "f5.bea_weblogic", "devicereferences": [ "link": " "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": , "kind": "cm:cloud:templates:iapp:templatesiappitemstate", "selflink": " HTTP/ OK 2-4

25 Central Management APIs Create new template item Creates a new template item. /mgmt/cm/cloud/templates/iapp POST N/A BIG-IQ API Reference Guide 2-5

26 Chapter 2 "name": "f5.bea_weblogic", "devicereferences": [ "link": " "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 ] ] HTTP/ OK 2-6

27 Central Management APIs Delete template item Deletes an item from a template. Note that this should only be done by the system. /mgmt/cm/cloud/templates/iapp name DELETE N/A "items": [ "name": "f5.bea_weblogic", "devicereferences": [ "link": " "template": null, "generation": 2, "lastupdatemicros": , "kind": "cm:cloud:templates:iapp2:templatesiappitemstate", "selflink": " ] HTTP/ OK BIG-IQ API Reference Guide 2-7

28 Chapter 2 Provider iapp template APIs What is an iapp template? What is a provider iapp template? 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. 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. 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? There are two ways to make a provider template. 2-8

29 Central Management APIs Figure 2.1 Provider template call flows The structure of a provider template 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 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 iapp template) describes things such as the IP address and port of the pool member. BIG-IQ API Reference Guide 2-9

30 Chapter 2 A (shortened) example of a provider template looks like this: "templatename": "HTTP-Bronze", "parentreference": "link": " "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": " -GUID-1234GUID1234" "tenanttemplatereference": "link": " "isf5example": false, "generation": 1, "lastupdatemicros": , "kind": "cm:cloud:provider:templates:iapp:provideriapptemplateworkerstate", "selflink": " An actual provider template would have many more variables and tables: this example is shortened for clarity. 2-10

31 Central Management APIs 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 "name": "variablename". "displayname": "name", "description": "description", "isrequired": booleanvalue, "defaultvalue": "somevalue", "provider": "somevalue", "providertype": "TYPE" # see below "servertier": "name" Explanation of variables A variable in the provider template has the following form: Field name displayname description isrequired defaultvalue provider providertype servertier The name of the variable. White space is not allowed. A human-readable version of the variable name (optional) A longer description of the purpose of the variable (optional) 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. The default value that will be used for the field when a user creates an iapp service based on this template. Also a default value, but indicates that a tenant may not edit this value. 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. 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. BIG-IQ API Reference Guide 2-11

32 Chapter 2 Properties 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. 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 Field id The name of the property. White space is not allowed. displayname description A user-friendly name for the property. White space is allowed. Some longer text describing the purpose of the property. isrequired A boolean, true or false value provider If the tenant does not specify a value, this value will be used. Also a default value, but indicates that a tenant can not edit this value. 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. 2-12

33 Central Management APIs Get provider iapp templates Gets a list of the created provider iapp templates. /mgmt/cm/cloud/provider/templates/iapp GET N/A None BIG-IQ API Reference Guide 2-13

34 Chapter 2 "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": " "properties": [ "id": "cloudconnectorreference", "displayname": "Cloud Connector", "isrequired": true, "provider": " "id": "shoesize", "displayname": "Shoe Size", "isrequired": true, "value": "7EEEE" "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": " "kind": "cm:cloud:provider:templates:iapp:providerservicetemplatecollectionworkerstate", "selflink": " 2-14

35 Central Management APIs Tenant Templates /mgmt/cm/cloud/tenant/templates/iapp Create provider iapp template Creates a new customized provider template. /mgmt/cm/cloud/provider/templates/iapp POST N/A BIG-IQ API Reference Guide 2-15

36 Chapter 2 "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, "provider": " "id": "shoesize", "displayname": "Shoe Size", "isrequired": true, "value": "7EEEE" "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": " 1234" ] 2-16

37 Central Management APIs HTTP/ OK HTTP Error code Tenant Templates /mgmt/cm/cloud/tenant/templates/iapp Get customized provider template parameters Gets the customized parameters for a specific provider template. /mgmt/cm/cloud/provider/templates/iapp/<template-id> GET N/A BIG-IQ API Reference Guide 2-17

38 Chapter 2 "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, "provider": " "id": "shoesize", "displayname": "Shoe Size", "isrequired": true, "value": "7EEEE" "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": " D1234" "kind": "cm:cloud:provider:templates:iapp:providerservicetemplateworkerstate", "selflink": " 2-18

39 Central Management APIs Tenant Templates /mgmt/cm/cloud/tenant/templates/iapp Delete provider iapp template Deletes the specified provider iapp templates /mgmt/cm/cloud/provider/templates/iapp/<template-id> DELETE N/A HTTP/ OK Tenant Templates /mgmt/cm/cloud/tenant/templates/iapp BIG-IQ API Reference Guide 2-19

40 Chapter 2 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. Gets an example provider iapp template for a given iapp template. /mgmt/cm/cloud/templates/iapp/name/providers/example-name/ GET N/A None A standard provider template: see the provider template API for an example. 2-20

41 Central Management APIs Provider iapp Templates Templates iapp Collection Worker /mgmt/cm/cloud/provider/templates/iapp /mgmt/cm/cloud/templates/iapp Get example provider template for a corresponding iapp template Gets a list of all example provider iapp templates for a given iapp template /mgmt/cm/cloud/templates/iapp/name/providers/ GET None None A standard provider template: see the provider template API for an example. Provider iapp Templates Templates iapp Collection Worker /mgmt/cm/cloud/provider/templates/iapp /mgmt/cm/cloud/templates/iapp Find all provider template examples Gets a list of all example provider iapp templates for a given iapp template. /mgmt/shared/index/config?$filter=kind eq 'cm:cloud:provider:templates:iapp:provideriapptemplateworkerstate' and isf5example eq 'true' GET None None BIG-IQ API Reference Guide 2-21

42 Chapter 2 "currentitemcount": 0, "itemsperpage": 0, "pageindex": 0, "selflink": " lates:iapp:provideriapptemplateworkerstate%27%20and%20isf5example%20eq%20%27true %27", "startindex": 0, "totalitems": 28, "totalpages": 0, "items": [ "templatename": "f5.bea_weblogic-example",... templates trimmed ] 2-22

43 Central Management APIs 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 "name": "variablename". "isrequired": booleanvalue, "defaultvalue": "somevalue", "providertype": "TYPE" # see below "servertier": "name" A variable in the tenant template has the following form: BIG-IQ API Reference Guide 2-23

44 Chapter 2 Explanation of variables Field name isrequired defaultvalue providertype servertier The name of the variable. White space is not allowed. 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. The default value that will be used for the field when a user creates an iapp service based on this template. 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 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. Properties Note The variables listed are the same as the ones in the corresponding provider templates, but without the provider variables. 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", 2-24

45 Central Management APIs Explanation of properties Field id displayname description isrequired value The name of the property. White space is not allowed. A user-friendly name for the property. White space is allowed. Some longer text describing the purpose of the property. A boolean, true or false. If the tenant does not specify a value, this value will be used. 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 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. /mgmt/cm/cloud/tenant/templates/iapp GET N/A None BIG-IQ API Reference Guide 2-25

46 Chapter 2 "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", "displayname": "Shoe Size", "isrequired": true, "value": "7EEEE" "generation": 1 "generation":

47 Central Management APIs BIG-IQ API Reference Guide 2-27

48 Chapter 2 Get tenant iapp template configuration Gets the configuration parameters for one tenant iapp template. /mgmt/cm/cloud/tenant/templates/iapp/<template-id> GET N/A None 2-28

49 Central Management APIs "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 BIG-IQ API Reference Guide 2-29

50 Chapter 2 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. 2-30

51 Central Management APIs Get all tenants Gets all of the tenants /mgmt/cm/cloud/tenants GET N/A "items": [ "name": "soda2", "description": "soda2 Tenant", "addresscontact": "123 Fake St.", "phone": "(206) ", " ": "soda2-it@f5.com", "userreference": "link": " "rolereference": "link": " "cloudconnectorreferences": [ "link": " "generation": 2 "name": "soda1", "description": "soda1 Tenant", "addresscontact": "321 Fake St.", "phone": "(206) ", " ": "soda1-it@f5.com", "userreference": "link": " "rolereference": "link": " "cloudconnectorreferences": [ "link": " "generation": 1 ] BIG-IQ API Reference Guide 2-31

52 Chapter 2 Get one tenant information Retrieves information for one tenant. /mgmt/cm/cloud/tenants/<tenant-id> GET N/A "name": "soda2", "description": "soda2 Tenant", "addresscontact": "123 Fake St.", "phone": "(206) ", " ": "soda2-it@f5.com", "userreference": "link": " "rolereference": "link": " "cloudconnectorreferences": [ "link": " ] Create tenant Creates one new tenant. /mgmt/cm/cloud/tenants POST N/A 2-32

53 Central Management APIs "name": "soda2", "description": "Soda 2 Tenant", "addresscontact": "123 Fake St.", "phone": "(206) ", " ": "soda2-it@f5.com", "userreference": "link": " "rolereference": "link": " "cloudconnectorreferences": [ "link": " ] HTTP/ OK BIG-IQ API Reference Guide 2-33

54 Chapter 2 Update tenant information Changes one tenant's information. /mgmt/cm/cloud/tenants/<tenant-id> PUT N/A "name": "soda2", "description": "soda2 Tenant", "addresscontact": "123 Fake St.", "phone": "(206) ", " ": "soda2-it@f5.com", "userreference": "link": " "rolereference": "link": " "cloudconnectorreferences": [ "link": " "generation": 2 HTTP/ OK Specify all fields. Do not change the name. Increment the generation number. Delete one tenant Deletes a tenant. /mgmt/cm/cloud/tenants/<tenant-id> DELETE N/A HTTP/ OK 2-34

55 Central Management APIs Tenant services APIs Properties "id": "name", "value": "somevalue", Explanation of properties These APIs make it possible for a tenant to manage his own application services. A tenant service request contains a list of optional properties, each of which has the following form: Field id The name of the property. White space is not allowed. value If the tenant does not specify a value, this value will be used. You can only specify properties if they are also in the tenant template referenced by the tenant service request. BIG-IQ API Reference Guide 2-35

56 Chapter 2 Get service instances Retrieves the list of service instances that have been deployed by the tenant. /mgmt/cm/cloud/tenants/<tenant-id>/services/iapp GET N/A 2-36

57 Central Management APIs "items": [ "name": "https-app1", "tenanttemplatereference": "link": " "tenantreference": "link": " "vars": [ "name": "pool addr", "value": " " "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": [ [ " ", "80" ] ] "properties": [ "vipproxyaddressbyservertiername": "Servers": " " "servertierswithprovisionedvips": [ "Servers" "servertiersslcerts": [ "tier": "Servers", "name": "https-app1_servers" "error" : "error description if any", "generation": 6, "lastupdatemicros": , "kind": "cm:cloud:tenants:tenantserviceinstance", "selflink": " Sample response truncated for brevity... BIG-IQ API Reference Guide 2-37

58 Chapter 2 Get service instance configuration Retrieves configuration for a given tenant service. /mgmt/cm/cloud/tenants/<tenant-id>/services/iapp/<service-id> GET N/A 2-38

59 Central Management APIs "name": "https-app1", "tenanttemplatereference": "link": " "tenantreference": "link": " "vars": [ "name": "pool addr", "value": " " "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": [ [ " ", "80" ] ] "properties": [ "vipproxyaddressbyservertiername": "Servers": " " "servertierswithprovisionedvips": [ "Servers" "servertiersslcerts": [ "tier": "Servers", "name": "https-app1_servers" "error" : "error description if any", "generation": 6, "lastupdatemicros": , "kind": "cm:cloud:tenants:tenantserviceinstance", "selflink": " BIG-IQ API Reference Guide 2-39

60 Chapter 2 The information returned only includes the tenant-provided values, and not the provider values from the provider template. Delete service instances Deletes an active tenant service. /mgmt/cm/cloud/tenants/<tenant-id>/services/iapp/<service-id> DELETE N/A HTTP/ OK Create service instance The fields this API uses are described in the table. Field pool_addr If the connector supportsvirtualserverprovisioning is true, then specifying 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. elasticitypolicy Required only if you are deploying an elastic service. Contains information used to support the expansion and contraction of server tiers in a service. elasticitypolicy.servertierpolicies A list of policies that are unique to the server tiers in a service. elasticitypolicy.servertierpolicies[0].associatedservertier The name of the server tier in the service to which the elasticity policy will be applied. 2-40