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) ", " ": "[email protected]", "userreference": "link": " "rolereference": "link": " "cloudconnectorreferences": [ "link": " "generation": 2 "name": "soda1", "description": "soda1 Tenant", "addresscontact": "321 Fake St.", "phone": "(206) ", " ": "[email protected]", "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) ", " ": "[email protected]", "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) ", " ": "[email protected]", "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) ", " ": "[email protected]", "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

61 Central Management APIs elasticitypolicy.servertierpolicies[0].minnumberofnodes The minimum number of nodes that should be running in the server tier at any given time. elasticitypolicy.servertierpolicies[0].maxnumberofnodes The maximum number of nodes that should be running in the server tier at any given time. elasticitypolicy.servertierpolicies[0].thresholds A list of thresholds that trigger either an expansion or contraction of a server tier when they are crossed. elasticitypolicy.servertierpolicies[0].thresholds[0].thresholdname The name of the threshold. elasticitypolicy.servertierpolicies[0].thresholds[0].stattype The type of statistics that should be monitored to determine whether a threshold was crossed or not. Valid values are VirtualServers and Application. elasticitypolicy.servertierpolicies[0].thresholds[0].statname The name of the stat to monitor. elasticitypolicy.servertierpolicies[0].thresholds[0].thresholdoperator The OData operator used to determine whether the threshold has been crossed or not. Valid values are gt, ge, eq, le, and lt. elasticitypolicy.servertierpolicies[0].thresholds[0].thresholdlevel The level of the threshold at which it is deemed to be crossed or not. elasticitypolicy.servertierpolicies[0].thresholds[0].thresholdfactor How much to expand or contract the threshold. elasticitypolicy.servertierpolicies[0].thresholds[0].thresholdcheckfrequencymicros Specifies how often to check whether the threshold has been crossed or not. servertiersslcerts The collection of client SSL certificates for each relevant server tier that uses SSL encryption. servertiersslcerts[0].tier The name of tier with which the client SSL cert will be associated. servertiersslcerts[0].certificatetext SSL certificate in base64 encoded PEM format. The text should begin with PEM sentinel -----BEGIN CERTIFICATE----- and end with ----END CERTIFICATE Line feeds can be either \n or \r\n. servertiersslcerts[0].privatekeytext SSL certificate's private key in base64 encoded PEM format. The text should begin with PEM sentinel -----BEGIN PRIVATE KEY----- and end with ----END PRIVATE KEY Line feeds can be either \n or \r\n. Create a new tenant service instance. mgmt/cm/cloud/tenants/<tenant-id>/services/iapp POST N/A BIG-IQ API Reference Guide 2-41

62 Chapter 2 "name": "https-app1", "tenanttemplatereference": "link": " "tenantreference": "link": " "vars": [ "name": "pool addr", "value": " " "tables": [ "name": "pool hosts", "columns": [ "name" "rows": [ [ "example.com" ] ] "name": "pool members", "columns": [ "addr", "port" "rows": [ [ " ", "80" ] ] "properties": [ "id": "shoesize", "value": "7EEEE" "servertiersinfo": [ "name" : "Servers", "nodetemplatereference" : "link" : " 04-b5a5-4bd8-ac40-808eeef5815f"... Sample response truncated for brevity... HTTP/ OK 2-42

63 Central Management APIs Update service instance Updates an existing tenant service instance. /mgmt/cm/cloud/tenants/<tenant-id>/services/iapp/<service instance id> PUT N/A "name": "TheTenantName.dns", "tenanttemplatereference": "link": "/mgmt/cm/cloud/tenant/templates/iapp/dns.silver" "vars": [ "name": "vs_pool vs_addr", "value": " " "tables": [ "name": "vs_pool members", "columns": [ "addr", "port" "rows": [ [ " ", "53" ] ] "properties": [ "id": "shoesize", "value": "7EEEE" ] HTTP/ OK HTTP/ Unavailable An HTTP 503 status code indicates you should retry later. This occurs when the asynchronous work of finishing the work from a previous POST or PUT is still in progress. BIG-IQ API Reference Guide 2-43

64 Chapter 2 Get example-stats Gets the list of stat names available on the iapp service category. /mgmt/cm/cloud/tenants/<tenant-id>/services/iapp-stats GET N/A

65 Central Management APIs "name": "TheTenantName.dns", "tenanttemplatereference": "link": "/mgmt/cm/cloud/tenant/templates/iapp/dns.silver" "vars": [ "name": "vs_pool vs_addr", "value": " " "tables": [ "name": "vs_pool members", "columns": [ "addr", "port" "rows": [ [ " ", "53" ] ] "properties": [ "id": "shoesize", "value": "7EEEE" ] 200 OK 401 Unauthorized 503 Unavailable JavaScript Java An HTTP 503 status code indicates you should retry later. This occurs when the asynchronous work of finishing the work from a previous POST or PUT is still in progress. Get example-stats Get the list of stat names available on the iapp service category /mgmt/cm/cloud/tenants/<tenant-id>/services/iapp-stats GET N/A HTTP/ OK "entries": "health.stats.total-member-cnt": "value": 1, "description": "", "lastupdatemicros": "health.stats.serverside.pkts-out": "value": 1, "description": "", "lastupdatemicros": "health.stats.serverside.tot-conns": "value": 1, "description": "", "lastupdatemicros": Sample response truncated for brevity... BIG-IQ API Reference Guide 2-45

66 Chapter 2 Tenant service health APIs Get service health Gets the health of a single service that has been deployed with the BIG-IQ system. health.summary is the overall health of the application. health.placement is the status of the placement, and the description is a string version of the Health POJO health.app is the status from the application directly. Currently not all applications support this. health.service.stats.* are stats provided by the iapp itself. Other stats are supplied by other processes or the infrastructure. /mgmt/cm/cloud/tenants/<tenant-id>/services/iapp/<service-id>/stats GET N/A 2-46

67 Central Management APIs HTTP/ OK "entries": "health.placement": "value":1.0, "description":"application Placement is placed and stable." "com.f5.rest.common.restworker.isreplicated": "value":0.0 "com.f5.rest.common.restworkerstate.lastupdatemicros": "value": e15 "GET": "value":1220.0, "description":"counter for GET" "com.f5.rest.common.restworkerstate.generation": "value":1.0 "health.summary": "value":1.0, "description":"application is healthy." "com.f5.rest.common.restworker.ispersisted": "value":0.0 "com.f5.rest.common.restworker.isindexed": "value":1.0 "PUT": "value":1.0, "description":"counter for PUT" "health.app": "value":1.0, "description":"application is healthy." "com.f5.rest.common.restworker.issynchronized": "value":0.0 "generation":3045, "lastupdatemicros": , "kind":"cm:cloud:tenants:scotttenant:services:iapp:gold3:stats:restworkerstats", "selflink":" BIG-IQ API Reference Guide 2-47

68 Chapter 2 Example Health PODO "description":"application Placement failed with an error.", "status":"error", "error":"placement on remote device: 01cfd failed with error:java.net.protocolexception: Status code:400, uri: _ip= &em_server_auth_token=<token> at com.f5.rest.common.restrequestsender.finish(restrequestsender.java:403) at com.f5.rest.common.restrequestsender.processnext(restrequestsender.java:389) at com.f5.rest.common.resthelper$2.run(resthelper.java:1425) at java.util.concurrent.threadpoolexecutor$worker.runtask(unknown Source) at java.util.concurrent.threadpoolexecutor$worker.run(unknown Source) at java.lang.thread.run(unknown Source)" 2-48

69 Central Management APIs Tenant virtual servers APIs These APIs allow clients to retrieve all the virtual servers for any tenant services owned by a given tenant. It is the combination of all the server tiers owned by the tenant. Get all virtual servers Gets all application servers tiers that are associated with a given tenant. /mgmt/cm/cloud/tenants/<tenant-id>/virtual-servers GET N/A "items":[ "id":"tenant:app:servers", "name":"servers", "virtualserver": "address":" ", "proxyaddress":" " "poolservers":[ "address":" ", "port":"80" "servicereference": "link":" "generation":1, "lastupdatemicros": , "kind":"cm:cloud:tenants:services:iapp:servertiers:servertierstate", "selflink":" "generation":1, "kind":"cm:cloud:tenants:services:iapp:servertiers:servertiercollectionstate", "lastupdatemicros": , "selflink":" BIG-IQ API Reference Guide 2-49

70 Chapter 2 Get one virtual server Gets a single virtual server. Indexed by ID. /mgmt/cm/cloud/tenants/<tenant-id>/virtual-servers/id GET N/A "id":"tenant:app:servers", "name":"servers", "virtualserver": "address":" " "poolservers":[ "address":" ", "port":"80" "servicereference": "link":" "generation":1, "lastupdatemicros": , "kind":"cm:cloud:tenants:services:iapp:servertiers:servertierstate", "selflink":" Get example-stats Gets a list of stat names available at the virtual server category /mgmt/cm/cloud/tenants/<tenant-id>/virtual-servers-stats 2-50

71 Central Management APIs GET N/A BIG-IQ API Reference Guide 2-51

72 Chapter 2 "entries": "health.stats.clientside.connections-max": "value": 1, "description": "", "lastupdatemicros": "health.stats.clientside.packets-out": "value": 1, "description": "", "lastupdatemicros": "health.stats.serverside.packets-in": "value": 1, "description": "", "lastupdatemicros": "health.stats.clientside.connections-total": "value": 1, "description": "", "lastupdatemicros": "health.stats.serverside.connections-total": "value": 1, "description": "", "lastupdatemicros": "health.stats.clientside.packets-in": "value": 1, "description": "", "lastupdatemicros": "health.stats.serverside.connections-max": "value": 1, "description": "", "lastupdatemicros": "health.stats.clientside.connections-current": "value": 1, "description": "", "lastupdatemicros": "health.stats.serverside.connections-current": "value": 1, "description": "", "lastupdatemicros": "health.stats.serverside.packets-out": "value": 1, "description": "", "lastupdatemicros": "generation": 10, "lastupdatemicros": , "kind": "cm:cloud:tenants:t90:virtual-servers:stats:restworkerstats", "selflink": " 2-52

73 Central Management APIs Tenant service server tiers APIs These APIs retrieve the application server tiers and servers for a given tenant service. Get server tiers Gets all application servers tiers that are associated with a given tenant service. /mgmt/cm/cloud/tenants/<tenant-id>/services/iapp/<service-id>/servertiers GET N/A BIG-IQ API Reference Guide 2-53

74 Chapter 2 HTTP/ "items":[ "name":"default", "virtualserver": "address":" ", "proxyaddress":" " "poolservers":[ "address":" ", "port":"80" "tenantreference": "link": " "servicereference": "link":" "cloudconnectorreference" : "link" : " "generation":1, "lastupdatemicros": , "kind":"cm:cloud:tenants:services:iapp:servertiers:servertierstate", "selflink":" "generation":1, "kind":"cm:cloud:tenants:services:iapp:servertiers:servertiercollectionstate", "lastupdatemicros": , "selflink":" Get servers in tier Gets a particular application server tier that is associated with a given tenant service. /mgmt/cm/cloud/tenants/<tenant-id>/services/iapp/<service-id>/servertiers/<server-tier> GET N/A 2-54

75 Central Management APIs HTTP/ OK "name":"default", "virtualserver": "address":" ", "proxyaddress":" " "poolservers":[ "address":" ", "port":"80" "tenantreference": "link": " "servicereference": "link":" "cloudconnectorreference" : "link" : " "generation":1, "lastupdatemicros": , "kind":"cm:cloud:tenants:services:iapp:servertiers:servertierstate", "selflink":" fault" BIG-IQ API Reference Guide 2-55

76 Chapter 2 Tenant node APIs The tenant node aggregator API shows which unique nodes are running which services deployed for a tenant, as well as the data center/cloud in which they live. Create node Sends a request to the nodes worker for the connector using the tenant nodes worker. /cm/cloud/tenants/<tenant-id>/nodes POST None N/A "cloudconnectorreference" : " "properties" : [ "id" : "ImageId", "value" : "ami-abcd1234" "id" : "InstanceType", "value" : "m1.large" "networkinterfaces" : [ "localaddress" : " ", "virtualaddress" : " ", "subnetaddress" : " /24" "subnetaddress" : " /24" "subnetaddress" : " /24" "state" : "PENDING", "provider" : false 2-56

77 Central Management APIs Query for all tenant nodes Gets all the tenant nodes associated with a specific tenant. /cm/cloud/tenants/<tenant-id>/nodes GET None N/A HTTP/ OK "items" : [ "nodeid" : "73120fcb-5be0-4ea5-a0ab abf18e", "cloudreference" : "link" : " "nodereference" : "link" : " /7edbea73-b431-4c0b-8f71-f554eb6db824" "ipaddress" : " ", "services" : [ "serviceport" : "80", "servicereference" : "link" : " ] BIG-IQ API Reference Guide 2-57

78 Chapter 2 Query example-stats for tenant nodes Queries example-stats for nodes. /cm/cloud/tenants/<tenant-id>/nodes-stats GET CloudConnectorReference since stats availability may be different for different cloud connector. -stats?cloudconnectorreference= 21f436-9ca2-4f39-b33c-29918e78840e 2-58

79 Central Management APIs HTTP/ OK "entries": "health.stats.cloud.min.diskreadops": "value": 1, "description": "", "lastupdatemicros": "health.stats.cloud.samplecount.networkout": "value": 1, "description": "", "lastupdatemicros": "health.stats.cloud.sum.diskwritebytes": "value": 1, "description": "", "lastupdatemicros": "health.stats.cloud.avg.networkin": "value": 1, "description": "", "lastupdatemicros": "health.stats.cloud.sum.diskreadops": "value": 1, "description": "", "lastupdatemicros": "health.stats.cloud.max.diskwritebytes": "value": 1, "description": "", "lastupdatemicros": "health.stats.cloud.max.diskreadops": "value": 1, "description": "", "lastupdatemicros": Sample response truncated for brevity... BIG-IQ API Reference Guide 2-59

80 Chapter 2 Tenant cloud connectors APIs Tenants can access cloud connector instances that they can target for application deployments. Providers can give access to specific connectors, and control access to specific fields, including providing default values. Tenant cloud connectors links can be provided during tenant service deployment to specify which cloud should be targeted for the application. Get all tenant cloud connectors Lists all of the cloud connectors to which the specified tenant has access. /mgmt/cm/cloud/tenants/<tenant-name>/connectors GET N/A "items": [ "cloudreference": "link":" "displayname": "Amazon EC2", "connectorid":"149e629f-4f a347-1c1d924741d0", "name":"north Virginian EC2 Connector", "devicereferences":[ "link": " EC1" "tenantinternalnetworks":[ "networkaddress":" ", "subnetaddress":" " "tenantexternalnetworks":[ "networkaddress":" ", "subnetaddress":" " "parameters":[ '"id": "ec2-id", "value": "some-id" ] "generation":1, "lastupdatemicros": , "kind":"cm:cloud:connectors:local:cloudconnectorstate", "selflink":" d0" ] 2-60

81 Central Management APIs Get tenant connector Gets the description for one specific tenant cloud connector instance. /mgmt/cm/cloud/tenants/<tenant-name>/connectors/<connector-id> GET N/A "cloudreference": "link":" "displayname": "Amazon EC2", "connectorid":"149e629f-4f a347-1c1d924741d0", "name":"north Virginia EC2 Connector", "devicereferences":[ "link": " EC1" "tenantinternalnetworks":[ "subnetaddress":" /24", "gatewayaddress":" " "tenantexternalnetworks":[ "subnetaddress":" /24", "gatewayaddress":" " "managementnetworks":[ "subnetaddress":" /16", "gatewayaddress":" " "parameters":[ '"id": "ec2-id", "value": "some-id" ] "generation":1, "lastupdatemicros": , "kind":"cm:cloud:connectors:local:cloudconnectorstate", "selflink":" 4741d0" BIG-IQ API Reference Guide 2-61

82 Chapter 2 Explanation of the fields: connectorid: The unique ID of this connector. name: A human-readable name for display in the UI. tenantinternalnetworks: The private network addresses within the cloud tenantextenalnetworks: The public network connecting this cloud to the Internet parameters: Property bag for the custom configuration properties for this connector instance. 2-62

83 Central Management APIs Cloud connector APIs Types of cloud connectors Creating a cloud connector The cloud connector API allows you to create and manipulate cloud connectors. A cloud connector is an association with a specific cloud. Tenant services are targeted to a given cloud connector. Here are some examples. A local cloud connector allows you to describe a private cloud. An EC2 cloud connector allows you to describe a specific EC2 configuration. For example, you might have a set of virtual machines in the EC2 Oregon data center, and these would be described by a single cloud connector. A VMware cloud connector allows you to describe a specific VMware vshield configuration. There are four types of cloud connectors: local: for a private cloud ec2: for accessing Amazon's EC2 vmware: for accessing private clouds maintained by VMware vshield Manager openstack: for accessing OpenStack deployments The diagram details the call sequence for creating a cloud connector. Figure 2.3 Cloud connector call flow BIG-IQ API Reference Guide 2-63

84 Chapter 2 Deploying an application in the cloud The diagram details the call sequence for deploying an application in the cloud. Figure 2.4 Application deployment call flow Cloud connector description All clouds share a common description. Each cloud may have extra parameters unique to that type of cloud. The code sample illustrates a typical cloud connector description. "cloudreference": "link: " "displayname": "Local", "connectorid": "unique-id", "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.254" "tenantexternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "managementnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "parameters": [] # A list of parameters: see below 2-64

85 Central Management APIs Explanation of fields Field Output only cloudreference Yes A URI for the cloud connector collection in which this connector is contained. displayname Yes The name of the type of the cloud connector this is contained in. Used for UI display purposes. connectorid Yes The unique identifier of the cloud connector. White space is not allowed. Internally assigned; can not be chosen by the client. supportsserverprovisioning Yes This cloud connector allows you to create new servers (virtual machines). supportsdeviceprovisioning Yes This cloud connector allows you to create new F5 BIG-IP devices. supportsdevicediscovery Yes This cloud connector automatically discovers F5 BIG-IP devices and associates them with the connector. supportsvirtualserverprovisioning Yes This cloud connector is able to automatically provision a dynamic virtual server address for each tier of an application. name No A user-friendly name for the property. White space is allowed. description No A user-friendly description for the property. devicereferences No A set of devices (ADCs) contained within this cloud tenantinternalnetworks No A description of the private network(s) within the cloud. The ADCs will be on these networks. tenantexternalnetworks No A description of the public network(s) to enter this cloud. The virtual servers will be on these networks. managementnetworks No A description of the management network(s) in this cloud. The BIG-IP management interfaces will be on these networks. Parameters Extra parameters for each cloud take the form illustrated in the sample. "id": "name", "displayname": "Descriptive Name", "description": "Descriptive text about the property", "isrequired": booleanvalue, "value": "somevalue", "provider": "somevalue", BIG-IQ API Reference Guide 2-65

86 Chapter 2 Explanation of parameters Field id displayname description isrequired value provider 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. A value for the property that is viewable by a tenant. Also a default value, but indicates that a tenant may not view this value. Parameters for specific cloud types The value and provider fields are mutually exclusive. There are no extra parameters for local cloud connectors.this cloud connector is able to automatically provision a dynamic Virtual Server address for each tier of an Application For VMware and EC2 cloud connectors, refer to the documentation for those connector types. Discovering a cloud connector's parameters This is an example input you can use as a guide in creating your own inputs to a cloud connector. Find the parameters for a given cloud connector /mgmt/cm/cloud/connectors/type GET N/A N/A 2-66

87 Central Management APIs "items": [ "name": "Human-readable name of connector", "description": "A longer description of the connector", "supportsserverprovisioning": true, "supportsdeviceprovisioning": true, "supportsdevicediscovery": true, "supportsvirtualserverprovisioning": true, "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "tenantexternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "managementnetworks": [ "subnetaddress": " /16", "gatewayaddress": " " "parameters": [ "id": "vshieldaddress", "displayname": "vshield Manager Address", "isrequired": true, "description": "The IP Address or name of the VMware vshield Manager", "value": " " "id": "vshieldusername", "displayname": "vshield Manager User Name", "isrequired": true, "description": "The user name used to authenticate to the VMware vshield Manager", "value": "username" "id": "vshieldpassword", "displayname": "vshield Manager Password", "isrequired": true, "description": "The password used to authenticate to the VMware vshield Manager", "value": "passw0rd" "id": "bigiqcallbackuser", "displayname": "BIG-IQ User Name", "isrequired": true, "description": "The username used by vshield to communicate with the BIG-IQ", "value": "username" "id": "bigiqcallbackpassword", "displayname": "BIG-IQ Password", "isrequired": true, "description": "The password used by vshield to communicate with the BIG-IQ","value": "passw0rd" BIG-IQ API Reference Guide 2-67

88 Chapter 2 Create a cloud connector Creates a new cloud connector for a given type of cloud. /mgmt/cm/cloud/connectors/type POST N/A "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.254" "tenantexternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "managementnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "parameters": [] HTTP/ Created You only specify the name. The cloudreference and connectorid are assigned for you. Change a cloud connector Make changes to a cloud connector. /mgmt/cm/cloud/connectors/type/id PUT N/A 2-68

89 Central Management APIs "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.254" "tenantexternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "managementnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "parameters": [] "generation": 1 HTTP/ Created You only specify the name. The cloudreference and connectorid are assigned for you. The generation you specify must be the same as that returned by the most recent GET on the cloud connector. BIG-IQ API Reference Guide 2-69

90 Chapter 2 Get a cloud connector Gets a single cloud connector from a given cloud type. /mgmt/cm/cloud/connectors/type/id GET N/A N/A "cloudreference": "link: " "displayname": "Local", "connectorid": "unique-id", "supportsserverprovisioning": true, "supportsdeviceprovisioning": true, "supportsdevicediscovery": true, "supportsvirtualserverprovisioning": true, "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.254" "tenantexternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "managementnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "parameters": [] "generation": 1 You only specify the name. The cloudreference and connectorid are assigned for you. The generation you specify must be the same as that returned by the most recent GET on the cloud connector. Get health of a cloud connector Gets the health for a single cloud connector. /mgmt/cm/cloud/connectors/type/id/stata GET N/A N/A 2-70

91 Central Management APIs "entries": "health.summary": "value": 1, "description": "vshield is configured and ready to use" "generation": 3, Get all cloud connectors of a given type Gets a single cloud connector from a given type. /mgmt/cm/cloud/connectors/type/ GET "items": [ "cloudreference": "link: " "displayname": "Local", "connectorid": "unique-id", "supportsserverprovisioning": true, "supportsdeviceprovisioning": true, "supportsdevicediscovery": true, "supportsvirtualserverprovisioning": true, "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.254" "tenantexternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "managementnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "parameters": [ "generation": 1 ] BIG-IQ API Reference Guide 2-71

92 Chapter 2 Get all cloud connectors of all types (brief) Gets all cloud connectors of all types (brief). /mgmt/shared/resolver/groups?$filter=groupname eq cm:cloud:connectors:cloudconnectorstate GET "issubscriptionrequired": false, "groupname": "cm:cloud:connectors:cloudconnectorstate", "references": [ "link": " "generation": 0, "lastupdatemicros": 0 Get all cloud connectors of all types (detailed) Gets all cloud connectors of all types (detailed). /mgmt/shared/resolver/groups?$filter=groupname eq cm:cloud:connectors:cloudconnectorstate&$expand=references GET 2-72

93 Central Management APIs "groupname": "cm:cloud:connectors:cloudconnectorstate", "issubscriptionrequired": false, "references": [ "cloudreference": "link: " "displayname": "Amazon EC2", "connectorid": "unique-id", "supportsserverprovisioning": true, "supportsdeviceprovisioning": true, "supportsdevicediscovery": true, "supportsvirtualserverprovisioning": true, "name": "human-friendly-name", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.254" "tenantexternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "managementnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "parameters": [] "generation": 0, "lastupdatemicros": 0 BIG-IQ API Reference Guide 2-73

94 Chapter 2 Delete a cloud connector Deletes a cloud connector. /mgmt/cm/cloud/connectors/type/id DELETE None 2-74

95 Central Management APIs Local cloud connector APIs Parameters A local cloud connector allows you to describe a private cloud: a set of BIG-IP devices and the networks to which they are connected. A local Cloud Connector is similar to other cloud connectors, except that it has no extra parameters. The code sample provides an example description. "displayname": "Local", "name": "Human-readable name of connector", "description": "A longer description of the connector", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "tenantexternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "managementnetworks": [ "subnetaddress": " /16", "gatewayaddress": " " "parameters": [] BIG-IQ API Reference Guide 2-75

96 Chapter 2 Explanation of fields Field Output only cloudreference Yes A URI for the cloud connector collection in which this connector is contained. displayname Yes The name of the type of the cloud connector this is contained in. For UI display purposes. connectorid Yes The unique identifier of the cloud connector. White space is not allowed. Internally assigned; can not be chosen by the client. name No A user-friendly name for the property. White space is allowed. description No A user-friendly description for the property. devicereferences No A set of devices (ADCs) contained within this cloud. tenantinternalnetworks No A description of the private network(s) within the cloud. The ADCs will be on these networks. tenantexternalnetworks No A description of the public network(s) to enter this cloud. The virtual servers will be on these networks. managementnetworks No A description of the management network(s) in this cloud. The BIG-IP management interfaces will be on these networks. Parameters Extra parameters for each cloud take the form illustrated in the sample. "id": "name", "displayname": "Descriptive Name", "description": "Descriptive text about the property", "isrequired": booleanvalue, "value": "somevalue", "provider": "somevalue", 2-76

97 Central Management APIs Explanation of parameters Field id displayname description isrequired value provider 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. A value for the property that is viewable by a tenant. Also a default value, but indicates that a tenant may not view this value. Parameters for local clouds The value and provider fields are mutually exclusive. There are no extra parameters for local cloud connectors. Create a local cloud connector Creates a new local cloud connector. /mgmt/cm/cloud/connectors/local POST "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.254" "tenantexternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "managementnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "parameters": [] HTTP/ Created BIG-IQ API Reference Guide 2-77

98 Chapter 2 Note that you only specify the name. The cloudreference and connectorid are assigned for you. Change a local cloud connector Changes a cloud connector. /mgmt/cm/cloud/connectors/local/id PUT "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.254" "tenantexternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "managementnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "parameters": [ "generation": 1 HTTP/ Created Note that you only specify the name. The cloudreference and connectorid are assigned for you. 2-78

99 Central Management APIs Get a cloud connector Gets a single local cloud connector. /mgmt/cm/cloud/connectors/local/id GET "cloudreference": "link: " "displayname": "Local", "connectorid": "unique-id", "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.254" "tenantexternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "managementnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "parameters": [ "generation": 1 Get all local cloud connectors Gets all local cloud connectors. /mgmt/cm/cloud/connectors/local GET BIG-IQ API Reference Guide 2-79

100 Chapter 2 "items": [ "cloudreference": "link: " "displayname": "Local", "connectorid": "unique-id", "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.254" "tenantexternalnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "managementnetworks": [ "subnetaddress": "x.y.x.y/z", "gatewayaddress": "x.y.x.1" "parameters": [] "generation": 1 ] Get health of a local cloud connector Gets health of a local cloud connector. /mgmt/cm/cloud/connectors/local/id/stats GET "entries": "health.summary": "value": 1, "description": "" "generation": 3, 2-80

101 Central Management APIs The health value is 1 if it is healthy and 0 if it is unhealthy. Currently local cloud connectors will always report that they are healthy. Delete a local cloud connector Deletes a local cloud connector. /mgmt/cm/cloud/connectors/local/id DELETE HTTP/ OK BIG-IQ API Reference Guide 2-81

102 Chapter 2 EC2 cloud connectors APIs The EC2 cloud connector API allows you to create and manipulate EC2 cloud connectors. The BIG-IQ EC2 connector is designed to be a single network topology that contains one or more BIG-IP devices. In AWS terms, it is a single VPC completely contained inside a single Availability Zone that is inside a single EC2 Region. The VPC network topology is expected to have three types of subnets. Management - BIG-IP VE eth0 interface sits on this subnet. BIG-IQ Cloud only supports one management subnet. Tenant External - BIG-IP application virtual servers are provisioned on this subnet. The first subnet specified of this type is considered the external VLAN of the BIG-IP device. Subsequent subnets are labeled external1, external2, and so on. Tenant Internal - BIG-IQ manages BIG-IP devices across this subnet. BIG-IP LTM nodes are expected to appear on this subnet. The first subnet specified of this type is considered the internal VLAN of the BIG-IP device. Subsequent subnets are labeled internal1, internal2, and so on. 2-82

103 Central Management APIs EC2 Connector Topology Figure 2.5 EC2 Connector Topology BIG-IQ API Reference Guide 2-83

104 Chapter 2 Parameters for EC2 cloud connectors Name Required Value regionendpoint yes The EC2 region endpoint that BIG-IQ system will connect to. This represents a choice of the EC2 geography that is being utilized. See possible values at awsaccesskeyid yes The AWS Access Key ID associated with AWS user account that BIG-IQ system will impersonate. EC2 uses this to authenticate source of requests sent to the EC2 endpoint. secretaccesskey yes The AWS Secret Access Key associated with AWS user account that BIG-IQ system will impersonate. EC2 uses this to authenticate source of requests sent to the EC2 endpoint. availabilityzone yes The EC2 availability zone that connector's resources are contained within. An availability zone is a compartment of resources inside a region. Example is us-west-2c. For more information, see y-zones.html vpcid no The EC2 Virtual Private Cloud (VPC) that connector's resources are contained within. A VPC is a network topology inside an availability zone. Example is vpc f. If none is specified then the BIG-IQ system will use the first VPC discovered in availability zone. autodeploydevices no Preference as to whether Devices will be auto-deployed when required to support tenant application deployment. If true, then tenantinternalnetworks and tenantexternalnetworks must be populated appropriately. Defaults to false. It is important that the owner of the AWS account create a less-privileged account that does not have access to the credit card used with the AWS account and use its credentials for the awsaccesskeyid and secretaccesskey. The less-privileged account permissions should be set up to so that it can be used to create, delete, or modify EC2 instances as well as perform any other activities related to creating, deleting, or modifying EC2 instances. 2-84

105 Central Management APIs Create an EC2 cloud connector Creates a new EC2 cloud connector. /mgmt/cm/cloud/connectors/ec2 POST "name" : "EC2 Connector Name", "parameters" : [ "description" : "Required parameter. The EC2 region endpoint that BIG-IQ will connect to. This represents a choice of the EC2 geography that is being utilized. See "displayname" : "Region Endpoint", "id" : "regionendpoint", "isrequired" : true, "value" : "ec2.us-west-2.amazonaws.com" "description" : "Required parameter. The AWS Access Key ID associated with AWS user account that BIG-IQ will impersonate. EC2 uses this to authenticate source of requests sent to the EC2 endpoint.", "displayname" : "Key ID", "id" : "awsaccesskeyid", "isrequired" : true, "value" : "AKIAJ7GRU4S4D6NYQYUA" "description" : "Required parameter. The AWS Secret Access Key associated with AWS user account that BIG-IQ will impersonate. EC2 uses this to authenticate source of requests sent to the EC2 endpoint.", "displayname" : "Secret Key", "id" : "secretaccesskey", "isrequired" : true, "value" : "wg1dx+sl/4ae9xgqtogrvunmlqekdphqfbygvhas" "description" : "Required parameter. The EC2 availability zone that connector's resources are contained within. An availability zone is a compartment of resources inside a region. For more info, see "displayname" : "Availability Zone", "id" : "availabilityzone", "isrequired" : true, "value" : "us-west-2c" "licensereference": "link": " "dnsserveraddresses": [ " ", " " "dnssuffixes": [ "example.net", "example.com" ] BIG-IQ API Reference Guide 2-85

106 Chapter 2 "cloudconnectorreference": "link": " "displayname": "Amazon EC2", "connectorid": "GUID1234-GUID-1234-GUID-1234GUID1234", "name": "EC2 Connector Name", "devicereferences": [ "link": " "link": " "managementnetworks": [ "subnetaddress": " /24", "name": "mgmt" "tenantinternalnetworks": [ "subnetaddress": " /24", "name": "internal" "tenantexternalnetworks": [ "subnetaddress": " /24", "name": "external" "parameters": [ "description" : "Required parameter. The EC2 region endpoint that BIG-IQ will connect to. This represents a choice of the EC2 geography that is being utilized. See "displayname" : "Region Endpoint", "id" : "regionendpoint", "isrequired" : true, "value" : "ec2.us-west-2.amazonaws.com" "description" : "Required parameter. The AWS Access Key ID associated with AWS user account that BIG-IQ will impersonate. EC2 uses this to authenticate source of requests sent to the EC2 endpoint.", "displayname" : "Key ID", "id" : "awsaccesskeyid", "isrequired" : true, "value" : "AKIAJ7GRU4S4D6NYQYUA" "description" : "Required parameter. The AWS Secret Access Key associated with AWS user account that BIG-IQ will impersonate. EC2 uses this to authenticate source of requests sent to the EC2 endpoint.", "displayname" : "Secret Key", "id" : "secretaccesskey", "isrequired" : true, "value" : "wg1dx+sl/4ae9xgqtogrvunmlqekdphqfbygvhas" "description" : "Required parameter. The EC2 availability zone that connector's resources are contained within. An availability zone is a compartment of resources inside a region. For more info, see "displayname" : "Availability Zone", "id" : "availabilityzone", "isrequired" : true, "value" : "us-west-2c" "id": "autodeploydevices", "displayname": "Device Elasticity", "isrequired": false, "description": "Preference as to whether Device will be auto-deployed when required to support tenant application deployment. Defaults to true.", "provider": "true" "id": "autodeployservers", "displayname": "Server Elasticity", "isrequired": false, "description": "Preference as to whether Server pool elasticity policies will be offered to tenant. Defaults to true.", "value": "true" "id": "vpcid", "displayname": "Virtual Private Cloud", "isrequired": false, "description": "The EC2 Virtual Private Cloud (VPC) that connector's resources are contained within. A VPC is a network topology inside an availability zone. If none is specified then BIG-IQ will utilize the first VPC discovered in availability zone.", "value": "vpc-cb8f1ba0" "licensereference": "link": " "timezone": "UTC", "ntpservers": [ "nist.time.gov" "dnsserveraddresses": [ " ", " " "dnssuffixes": [ "example.net", "example.com" "supportsserverprovisioning": true, "supportsdeviceprovisioning": true, "supportsdevicediscovery": true, "supportsvirtualserverprovisioning": true, "generation": 2, "lastupdatemicros": , "kind": "cm:cloud:connectors:cloudconnectorstate", "selflink": " 2-86

107 Central Management APIs You only specify the name. The cloudreference and connectorid are assigned for you. On successful connection to EC2, it will add all BIG-IP devices in EC2 to the managed devices and all non BIG-IP devices to the node worker. When adding BIG-IP devices to managed devices it uses a dummy user name and password. The cloud administrator will need to correct user name and password field in the managed devices before the EC2 BIG-IP devices are used. Change an EC2 cloud connector Changes a cloud connector. /mgmt/cm/cloud/connectors/ec2/id PUT BIG-IQ API Reference Guide 2-87

108 Chapter 2 "cloudconnectorreference": "link": " "displayname": "Amazon EC2", "connectorid": "GUID1234-GUID-1234-GUID-1234GUID1234", "name": "EC2 Connector Name Changed", "devicereferences": [ "link": " "link": " "managementnetworks": [ "subnetaddress": " /24", "name": "mgmt" "tenantinternalnetworks": [ "subnetaddress": " /24", "name": "internal" "tenantexternalnetworks": [ "subnetaddress": " /24", "name": "external", "gatewayaddress": " " "parameters": [ "description" : "Required parameter. The EC2 region endpoint that BIG-IQ will connect to. This represents a choice of the EC2 geography that is being utilized. See "displayname" : "Region Endpoint", "id" : "regionendpoint", "isrequired" : true, "value" : "ec2.us-west-2.amazonaws.com" "description" : "Required parameter. The AWS Access Key ID associated with AWS user account that BIG-IQ will impersonate. EC2 uses this to authenticate source of requests sent to the EC2 endpoint.", "displayname" : "Key ID", "id" : "awsaccesskeyid", "isrequired" : true, "value" : "AKIAJ7GRU4S4D6NYQYUA" "description" : "Required parameter. The AWS Secret Access Key associated with AWS user account that BIG-IQ will impersonate. EC2 uses this to authenticate source of requests sent to the EC2 endpoint.", "displayname" : "Secret Key", "id" : "secretaccesskey", "isrequired" : true, "value" : "wg1dx+sl/4ae9xgqtogrvunmlqekdphqfbygvhas" "description" : "Required parameter. The EC2 availability zone that connector's resources are contained within. An availability zone is a compartment of resources inside a region. For more info, see "displayname" : "Availability Zone", "id" : "availabilityzone", "isrequired" : true, "value" : "us-west-2c" "id": "autodeploydevices", "displayname": "Device Elasticity", "isrequired": false, "description": "Preference as to whether Device will be auto-deployed when required to support tenant application deployment. Defaults to true.", "provider": "true" "id": "autodeployservers", "displayname": "Server Elasticity", "isrequired": false, "description": "Preference as to whether Server pool elasticity policies will be offered to tenant. Defaults to true.", "value": "true" "id": "vpcid", "displayname": "Virtual Private Cloud", "isrequired": false, "description": "The EC2 Virtual Private Cloud (VPC) that connector's resources are contained within. A VPC is a network topology inside an availability zone. If none is specified then BIG-IQ will utilize the first VPC discovered in availability zone.", "value": "vpc-cb8f1ba0" "licensereference": "link": " "timezone": "UTC", "ntpservers": [ "nist.time.gov" "dnsserveraddresses": [ " ", " " "dnssuffixes": [ "example.net", "example.com" "supportsserverprovisioning": true, "supportsdeviceprovisioning": true, "supportsdevicediscovery": true, "supportsvirtualserverprovisioning": true, "generation": 3, "lastupdatemicros": , "kind": "cm:cloud:connectors:cloudconnectorstate", "selflink": " 2-88

109 Central Management APIs HTTP/ Created You only specify the name. The cloudreference and connectorid are assigned for you. The generation you specify must be the same as that returned by the most recent GET on the cloud connector. BIG-IQ API Reference Guide 2-89

110 Chapter 2 Get an EC2 connector Gets a single EC2 cloud connector. /mgmt/cm/cloud/connectors/ec2/id GET 2-90

111 Central Management APIs "cloudconnectorreference": "link": " "displayname": "Amazon EC2", "connectorid": "GUID1234-GUID-1234-GUID-1234GUID1234", "name": "EC2 Connector Name Changed", "devicereferences": [ "link": " "link": " "managementnetworks": [ "subnetaddress": " /24", "name": "mgmt" "tenantinternalnetworks": [ "subnetaddress": " /24", "name": "internal" "tenantexternalnetworks": [ "subnetaddress": " /24", "name": "external" "parameters": [ "description" : "Required parameter. The EC2 region endpoint that BIG-IQ will connect to. This represents a choice of the EC2 geography that is being utilized. See "displayname" : "Region Endpoint", "id" : "regionendpoint", "isrequired" : true, "value" : "ec2.us-west-2.amazonaws.com" "description" : "Required parameter. The AWS Access Key ID associated with AWS user account that BIG-IQ will impersonate. EC2 uses this to authenticate source of requests sent to the EC2 endpoint.", "displayname" : "Key ID", "id" : "awsaccesskeyid", "isrequired" : true, "value" : "AKIAJ7GRU4S4D6NYQYUA" "description" : "Required parameter. The AWS Secret Access Key associated with AWS user account that BIG-IQ will impersonate. EC2 uses this to authenticate source of requests sent to the EC2 endpoint.", "displayname" : "Secret Key", "id" : "secretaccesskey", "isrequired" : true, "value" : "wg1dx+sl/4ae9xgqtogrvunmlqekdphqfbygvhas" "description" : "Required parameter. The EC2 availability zone that connector's resources are contained within. An availability zone is a compartment of resources inside a region. For more info, see "displayname" : "Availability Zone", "id" : "availabilityzone", "isrequired" : true, "value" : "us-west-2c" "id": "autodeploydevices", "displayname": "Device Elasticity", "isrequired": false, "description": "Preference as to whether Device will be auto-deployed when required to support tenant application deployment. Defaults to true.", "provider": "true" "id": "autodeployservers", "displayname": "Server Elasticity", "isrequired": false, "description": "Preference as to whether Server pool elasticity policies will be offered to tenant. Defaults to true.", "value": "true" "id": "vpcid", "displayname": "Virtual Private Cloud", "isrequired": false, "description": "The EC2 Virtual Private Cloud (VPC) that connector's resources are contained within. A VPC is a network topology inside an availability zone. If none is specified then BIG-IQ will utilize the first VPC discovered in availability zone.", "value": "vpc-cb8f1ba0" "licensereference": "link": " "timezone": "UTC", "ntpservers": [ "nist.time.gov" "dnsserveraddresses": [ " ", " " "dnssuffixes": [ "example.net", "example.com" "supportsserverprovisioning": true, "supportsdeviceprovisioning": true, "supportsdevicediscovery": true, "generation": 3, "lastupdatemicros": , "kind": "cm:cloud:connectors:cloudconnectorstate", "selflink": " BIG-IQ API Reference Guide 2-91

112 Chapter 2 Get health of an EC2 cloud connector Gets health of an EC2 cloud connector. /mgmt/cm/cloud/connectors/ec2/id/stats GET "entries": "health.summary": "value": 1, "description": "Connected" "generation": 3, Get all EC2 cloud connectors Gets all EC2 cloud connectors. /mgmt/cm/cloud/connectors/ec2/ GET 2-92

113 Central Management APIs "items": [ "cloudconnectorreference": "link": " "displayname": "Amazon EC2", "connectorid": "GUID1234-GUID-1234-GUID-1234GUID1234", "name": "EC2 Connector Name Changed", "devicereferences": [ "link": " "link": " "managementnetworks": [ "subnetaddress": " /24", "name": "mgmt" "tenantinternalnetworks": [ "subnetaddress": " /24", "name": "internal" "tenantexternalnetworks": [ "subnetaddress": " /24", "name": "external", "gatewayaddress": " " "parameters": [ "description" : "Required parameter. The EC2 region endpoint that BIG-IQ will connect to. This represents a choice of the EC2 geography that is being utilized. See "displayname" : "Region Endpoint", "id" : "regionendpoint", "isrequired" : true, "value" : "ec2.us-west-2.amazonaws.com" "description" : "Required parameter. The AWS Access Key ID associated with AWS user account that BIG-IQ will impersonate. EC2 uses this to authenticate source of requests sent to the EC2 endpoint.", "displayname" : "Key ID", "id" : "awsaccesskeyid", "isrequired" : true, "value" : "AKIAJ7GRU4S4D6NYQYUA" "description" : "Required parameter. The AWS Secret Access Key associated with AWS user account that BIG-IQ will impersonate. EC2 uses this to authenticate source of requests sent to the EC2 endpoint.", "displayname" : "Secret Key", "id" : "secretaccesskey", "isrequired" : true, "value" : "wg1dx+sl/4ae9xgqtogrvunmlqekdphqfbygvhas" "description" : "Required parameter. The EC2 availability zone that connector's resources are contained within. An availability zone is a compartment of resources inside a region. For more info, see "displayname" : "Availability Zone", "id" : "availabilityzone", "isrequired" : true, "value" : "us-west-2c" "id": "autodeploydevices", "displayname": "Device Elasticity", "isrequired": false, "description": "Preference as to whether Device will be auto-deployed when required to support tenant application deployment. Defaults to true.", "provider": "true" "id": "autodeployservers", "displayname": "Server Elasticity", "isrequired": false, "description": "Preference as to whether Server pool elasticity policies will be offered to tenant. Defaults to true.", "value": "true" "id": "vpcid", "displayname": "Virtual Private Cloud", "isrequired": false, "description": "The EC2 Virtual Private Cloud (VPC) that connector's resources are contained within. A VPC is a network topology inside an availability zone. If none is specified then BIG-IQ will utilize the first VPC discovered in availability zone.", "value": "vpc-cb8f1ba0" "licensereference": "link": " "timezone": "UTC", "ntpservers": [ "nist.time.gov" "dnsserveraddresses": [ " ", " " "dnssuffixes": [ "example.net", "example.com" "supportsserverprovisioning": true, "supportsdeviceprovisioning": true, "supportsdevicediscovery": true, "supportsvirtualserverprovisioning": true, "generation": 3, "lastupdatemicros": , "kind": "cm:cloud:connectors:cloudconnectorstate", "selflink": " "generation": 0, "lastupdatemicros": 0, "kind": "cm:cloud:connectors:genericconnectorcollectionworkerstate", "selflink": " BIG-IQ API Reference Guide 2-93

114 Chapter 2 Delete an EC2 cloud connector Deletes an EC2 cloud connector. /mgmt/cm/cloud/connectors/ec2/1816a046-b7ad-424c-8af e940f93 DELETE 2-94

115 Central Management APIs "cloudconnectorreference": "link": " "displayname": "Amazon EC2", "connectorid": "1816a046-b7ad-424c-8af e940f93", "name": "EC2 Connector Name Changed", "devicereferences": [ "link": " "link": " "managementnetworks": [ "subnetaddress": " /24", "name": "mgmt" "tenantinternalnetworks": [ "subnetaddress": " /24", "name": "internal" "tenantexternalnetworks": [ "subnetaddress": " /24", "name": "external" "parameters": [ "description" : "Required parameter. The EC2 region endpoint that BIG-IQ will connect to. This represents a choice of the EC2 geography that is being utilized. See "displayname" : "Region Endpoint", "id" : "regionendpoint", "isrequired" : true, "value" : "ec2.us-west-2.amazonaws.com" "description" : "Required parameter. The AWS Access Key ID associated with AWS user account that BIG-IQ will impersonate. EC2 uses this to authenticate source of requests sent to the EC2 endpoint.", "displayname" : "Key ID", "id" : "awsaccesskeyid", "isrequired" : true, "value" : "AKIAJ7GRU4S4D6NYQYUA" "description" : "Required parameter. The AWS Secret Access Key associated with AWS user account that BIG-IQ will impersonate. EC2 uses this to authenticate source of requests sent to the EC2 endpoint.", "displayname" : "Secret Key", "id" : "secretaccesskey", "isrequired" : true, "value" : "wg1dx+sl/4ae9xgqtogrvunmlqekdphqfbygvhas" "description" : "Required parameter. The EC2 availability zone that connector's resources are contained within. An availability zone is a compartment of resources inside a region. For more info, see "displayname" : "Availability Zone", "id" : "availabilityzone", "isrequired" : true, "value" : "us-west-2c" "id": "autodeploydevices", "displayname": "Device Elasticity", "isrequired": false, "description": "Preference as to whether Device will be auto-deployed when required to support tenant application deployment. Defaults to true.", "provider": "true" "id": "autodeployservers", "displayname": "Server Elasticity", "isrequired": false, "description": "Preference as to whether Server pool elasticity policies will be offered to tenant. Defaults to true.", "value": "true" "id": "vpcid", "displayname": "Virtual Private Cloud", "isrequired": false, "description": "The EC2 Virtual Private Cloud (VPC) that connector's resources are contained within. A VPC is a network topology inside an availability zone. If none is specified then BIG-IQ will utilize the first VPC discovered in availability zone.", "value": "vpc-cb8f1ba0" "licensereference": "link": " "timezone": "UTC", "ntpservers": [ "nist.time.gov" "dnsserveraddresses": [ " ", " " "dnssuffixes": [ "example.net", "example.com" "supportsserverprovisioning": true, "supportsdeviceprovisioning": true, "supportsdevicediscovery": true, "supportsvirtualserverprovisioning": true, "generation": 3, "lastupdatemicros": , "kind": "cm:cloud:connectors:cloudconnectorstate", "selflink": " BIG-IQ API Reference Guide 2-95

116 Chapter

117 Central Management APIs OpenStack cloud connector APIs This API allows you to create and manipulate OpenStack cloud connectors. For more information about cloud connectors, see the cloud connector documentation. This API communicates directly with OpenStack and requires version (Grizzly) or later. The OpenStack cloud connector is similar to other cloud connectors, except for the OpenStack-specific parameters. An example description is provided below. "displayname": "OpenStack", "name": "Human-readable name of connector", "description": "A longer description of the connector", "devicereferences": [ ] "parameters": [ "id": "OpenStackUri", "value": " "id": "OpenStackUserName", "value": "admin" "id": "OpenStackTenantName", "value": "admin" "id": "OpenStackPassword", "value": "Passw0rd" ] Note While the connector documentation describes tenantinternalnetworks, tenantexternalnetworks, and managementnetworks, you should not pass these: they are discovered when querying OpenStack. See the section on Networks, in the properties explanation. Explanation of Properties Field Output only cloudreference Yes A URI for the cloud connector collection in which this connector is contained. displayname Yes The name of the type of the cloud connector in which this is contained. Used for UI display purposes. connectorid Yes The unique identifier of the cloud connector. White space is not allowed. Internally assigned; can not be chosen by the client. supportsserverprovisioning Yes This cloud connector allows you to create new servers (virtual machines). supportsdeviceprovisioning Yes This cloud connector allows you to create new F5 BIG-IP devices. name No A user-friendly name for the property. White space is allowed BIG-IQ API Reference Guide 2-97

118 Chapter 2 description No A user-friendly description for the property. devicereferences No A set of devices (ADCs) contained within this cloud. Normally you should specify an empty list: devices will be discovered when you connect to OpenStack Parameters for OpenStack cloud connectors Extra parameters for each cloud take the form illustrated in the sample text: "id": "name", "displayname": "Descriptive Name", "description": "Descriptive text about the property", "isrequired": booleanvalue, "value": "somevalue", "provider": "somevalue", Explanation of variables Field id displayname description The name of the property. White space is not allowed. A human-readable version of the property. White space is not allowed. A longer description of the purpose of the property. isrequired A boolean, true or false. value provider A value for the property that is viewable by a tenant. Also a default value, but indicates that a tenant can not edit this value. The value and provider fields are mutually exclusive. Field OpenStackUri OpenStackUserName OpenStackTenantName OpenStackPassword The IP Address or name of the OpenStack Controller. If you do not specify a port, it defaults to If you not specify a scheme (that is, http or https) it defaults to https. The user name used to authenticate to OpenStack. The tenant name used to authenticate to OpenStack. The password used to authenticate to OpenStack. 2-98

119 Central Management APIs Create an OpenStack cloud connector Creates a new OpenStack cloud connector. /mgmt/cm/cloud/connectors/openstack POST "name": "human-friendly-name", "description": "some friendly description", "devicereferences":[ "parameters": [ "id": "OpenStackUri", "value": " "id": "OpenStackUserName", "value": "admin" "id": "OpenStackTenantName", "value": "admin" "id": "OpenStackPassword", "value": "Passw0rd" HTTP/ Created You only specify the name. The cloudreference and connectorid are assigned for you. Change an OpenStack cloud connector Changes an OpenStack cloud connector. /mgmt/cm/cloud/connectors/openstack/id PUT BIG-IQ API Reference Guide 2-99

120 Chapter 2 "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "parameters": [ "id": "OpenStackUri", "value": " "id": "OpenStackUserName", "value": "admin" "id": "OpenStackTenantName", "value": "admin" "id": "OpenStackPassword", "value": "Passw0rd" "generation": 1 HTTP/ Created You only specify the name. The cloudreference and connectorid are assigned for you. The generation you specify must be the same as that returned by the most recent GET on the cloud connector. Get an OpenStack cloud connector Gets a single OpenStack cloud connector. /mgmt/cm/cloud/connectors/openstack/id GET 2-100

121 Central Management APIs "cloudreference": "link: " "displayname": "OpenStack", "connectorid": "ca5cd4f7-e3ac f12-11ec0a6c9a0e", "supportsserverprovisioning": true, "supportsdeviceprovisioning": false, "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "tenantexternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "managementnetworks": [ "subnetaddress": " /24", "gatewayaddress": " /24" "parameters": [ "id": "OpenStackUri", "value": " "id": "OpenStackUserName", "value": "admin" "id": "OpenStackTenantName", "value": "admin" "id": "OpenStackPassword", "value": "Passw0rd" "generation": 1 Get health of an OpenStack cloud connector Gets health of an OpenStack cloud connector. /mgmt/cm/cloud/connectors/openstack/id/stats GET BIG-IQ API Reference Guide 2-101

122 Chapter 2 "entries": "health.summary": "value": 1, "description": "OpenStack setup is healthy: Successfully connected" "generation": 3, 2-102

123 Central Management APIs Get all OpenStack cloud connector Gets all OpenStack cloud connectors. /mgmt/cm/cloud/connectors/openstack/ GET "items": [ "cloudreference": "link: " "displayname": "OpenStack", "connectorid": "ca5cd4f7-e3ac f12-11ec0a6c9a0e", "supportsserverprovisioning": true, "supportsdeviceprovisioning": false, "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "tenantexternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "managementnetworks": [ "subnetaddress": " /24", "gatewayaddress": " /24" "parameters": [ "id": "OpenStackUri", "value": " "id": "OpenStackUserName", "value": "admin" "id": "OpenStackTenantName", "value": "admin" "id": "OpenStackPassword", "value": "Passw0rd" "generation": 1 ] BIG-IQ API Reference Guide 2-103

124 Chapter 2 Delete an OpenStack cloud connector Deletes an OpenStack cloud connector. /mgmt/cm/cloud/connectors/openstack/id DELETE HTTP/ OK 2-104

125 Central Management APIs VMware cloud connector APIs With the VMware cloud connector API, you can create and manipulate VMware cloud connectors. For more information about cloud connectors, see the cloud connector documentation. The VMware cloud connector API communicates directly with VMware vshield Manager version 5.1.1, or NSX version 6.0 or later. You can create tenant services within VMware after a VMware cloud connector has been created. You can use either the vshield service insertion interface or the NSX Edge Gateway Services to create the connector. Normally you specify the tenant in VMware when inserting a service profile. The vshield has a user interface for this, but VMware NSX does not. When using NSX, give only one tenant access to a specific VMware connector, and BIG-IQ system then selects that tenant when it receives the service insertion request. You can also create tenant services using the vcloud Director interface for Edge Gateways. If you use vcloud Director, you still need vshield Manager. In this document, the term vshield, means vshield or vcloud or NSX.A VMware cloud connector is similar to other cloud connectors, except for the VMware-specific parameters. An example description is provided below: "displayname": "VMware vshieldmanager", "name": "Human-readable name of connector", "description": "A longer description of the connector", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "tenantexternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "managementnetworks": [ "subnetaddress": " /16", "gatewayaddress": " " "parameters": [ "id": "vshieldaddress", "value": " " "id": "vshieldusername", "value": "username" "id": "vshieldpassword", "value": "passw0rd" "id": "bigiqcallbackuser", "value": "username" "id": "bigiqcallbackpassword", "value": "passw0rd" BIG-IQ API Reference Guide 2-105

126 Chapter 2 Explanation of Properties Field Output only cloudreference Yes A URI for the cloud connector collection in which this connector is contained. displayname Yes The name of the type of the cloud connector in which this is contained. Used for UI display purposes. connectorid Yes The unique identifier of the cloud connector. White space is not allowed. Internally assigned--may not be chosen by the client. name No A user-friendly name for the property. White space is allowed description No A user-friendly description for the property. devicereferences No A set of devices (ADCs) contained within this cloud. tenantinternalnetworks No A description of the private network(s) within the cloud. The ADCs will be on these networks. tenantexternalnetworks No A description of the public network(s) that can enter this cloud. The virtual servers will be on these networks. managementnetworks A description of the management network(s) used to access this cloud. The BIG-IP system management interfaces reside on these networks Parameters for VMware cloud connectors Extra parameters for each cloud take the form illustrated in the sample text: "id": "name", "displayname": "Descriptive Name", "description": "Descriptive text about the property", "isrequired": booleanvalue, "value": "somevalue", "provider": "somevalue", 2-106

127 Central Management APIs Explanation of variables Field id displayname description The name of the property. White space is not allowed. A human-readable version of the property. White space is not allowed. A longer description of the purpose of the property. isrequired A boolean, true or false. value provider A value for the property that is viewable by a tenant. Also a default value, but indicates that a tenant can not edit this value. The value and provider fields are mutually exclusive. Field vshieldaddress vshieldusername vshieldpassword bigiqcallbackuser bigiqcallbackpassword The IP Address or name of the VMware vshield Manager. The user name used to authenticate to the VMware vshield Manager. The password used to authenticate to the VMware vshield Manager. The username used by vshield to communicate with the BIG-IQ Cloud. The password used by vshield to communicate with the BIG-IQ Cloud. BIG-IQ API Reference Guide 2-107

128 Chapter 2 Create a VMware cloud connector Creates a new VMware cloud connector. /mgmt/cm/cloud/connectors/vmware POST "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "tenantexternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "managementnetworks": [ "subnetaddress": " /16", "gatewayaddress": " " "parameters": [ "id": "vshieldaddress", "value": " " "id": "vshieldusername", "value": "username" "id": "vshieldpassword", "value": "passw0rd" "id": "bigiqcallbackuser", "value": "username" "id": "bigiqcallbackpassword", "value": "passw0rd" HTTP/ Created You only specify the name. The cloudreference and connectorid are assigned for you. Change a VMware cloud connector Changes a cloud connector. /mgmt/cm/cloud/connectors/vmware/id PUT 2-108

129 Central Management APIs "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "tenantexternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "managementnetworks": [ "subnetaddress": " /16", "gatewayaddress": " " "parameters": [ "id": "vshieldaddress", "value": " " "id": "vshieldusername", "value": "username" "id": "vshieldpassword", "value": "passw0rd" "id": "bigiqcallbackuser", "value": "username" "id": "bigiqcallbackpassword", "value": "passw0rd" "generation": 1 HTTP/ Created You only specify the name. The cloudreference and connectorid are assigned for you. The generation you specify must be the same as that returned by the most recent GET on the cloud connector. You cannot update a VMware cloud connector's address after the connection has been successfully created and configured. BIG-IQ API Reference Guide 2-109

130 Chapter 2 Get a VMware cloud connector Gets a single VMware cloud connector. /mgmt/cm/cloud/connectors/vmware/id GET "cloudreference": "link: " "displayname": "VMware vshield Manager", "connectorid": "unique-id", "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "tenantexternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "managementnetworks": [ "subnetaddress": " /16", "gatewayaddress": " " "parameters": [ "id": "vshieldaddress", "value": " " "id": "vshieldusername", "value": "username" "id": "vshieldpassword", "value": "passw0rd" "id": "bigiqcallbackuser", "value": "username" "id": "bigiqcallbackpassword", "value": "passw0rd" "generation":

131 Central Management APIs Get health of a VMware cloud connector Gets health of a VMware cloud connector. /mgmt/cm/cloud/connectors/vmware/id/stats GET "entries": "health.summary": "value": 1, "description": "vshield is configured and ready to use" "generation": 3, Get all VMware cloud connector Gets all VMware cloud connectors. /mgmt/cm/cloud/connectors/vmware/ GET BIG-IQ API Reference Guide 2-111

132 Chapter 2 "items": [ "cloudreference": "link: " "displayname": "VMware vshield Manager", "connectorid": "unique-id", "name": "human-friendly-name", "description": "some friendly description", "devicereferences": [ "link": " "tenantinternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "tenantexternalnetworks": [ "subnetaddress": " /24", "gatewayaddress": " " "managementnetworks": [ "subnetaddress": " /16", "gatewayaddress": " " "parameters": [ "id": "vshieldaddress", "value": " " "id": "vshieldusername", "value": "username" "id": "vshieldpassword", "value": "passw0rd" "id": "bigiqcallbackuser", "value": "username" "id": "bigiqcallbackpassword", "value": "passw0rd" "generation": 1 Delete a VMware cloud connector Deletes a VMware cloud connector. /mgmt/cm/cloud/connectors/vmware/id DELETE 2-112

133 Central Management APIs HTTP/ OK BIG-IQ API Reference Guide 2-113

134 Chapter 2 Cloud managed devices APIs These APIs add, delete, and view the list of managed devices. Devices are added and deleted in an asynchronous manner. Initial POSTs respond with a 202 ACCEPTED and the device state is set to PENDING. Eventually the device state changes to ACTIVE or POST_FAILED. DELETE is similar, and responds with 202 ACCEPTED if the device cannot be immediately deleted (state is changed to PENDING_DELETE). States Devices have a state field to indicate whether the device is ready for use or in some transitional state. State PENDING POST_FAILED ACTIVE PENDING_DELETE DELETED After the initial POST but before the device is ready for use; discovery task is in progress. Some error occurred during discovery, check error field for details. Device is ready for use. Device is currently being deleted and will be removed in the near future (set on delete or if you PATCH the device to the DELETED state). This state is only used when you do a you PATCH to delete a device or when you publish to subscribers when the device is finally deleted; it is never persisted

135 Central Management APIs Get managed devices Gets the list of managed devices /cm/cloud/managed-devices GET N/A N/A BIG-IQ API Reference Guide 2-115

136 Chapter 2 "selflink" : " "kind" : "cm:cloud:managed-devices:manageddevicecollectionstate", "generation" : 4, "lastupdatemicros" : , "items" : [ "clockskewsecondscount" : -65, "version" : "11.3.0", "defaultfirewallaction" : "accept", "lastupdatemicros" : , "hostname" : "<hostname>", "build" : "3016.0", "restframeworkversion": " ", "state" : "ACTIVE", "selflink" : " "kind" : "cm:cloud:managed-devices:manageddevicestate", "generation" : 1, "edition" : "Hotfix HF2", "product" : "BIG-IP", "id" : "670236b650064b61803bb0592e64aa19", "address" : " ", "systemid" : "39DA5FD F062-E843-8D6CBEBAF3F6" "clockskewsecondscount" : 13, "version" : "11.4.0", "defaultfirewallaction" : "accept", "lastupdatemicros" : , "hostname" : "<hostname>", "build" : "354.0", "restframeworkversion": " ", "state" : "ACTIVE", "selflink" : " "kind" : "cm:cloud:managed-devices:manageddevicestate", "generation" : 1, "edition" : "Final", "product" : "BIG-IP", "id" : "a3dadffe649f4d6dab4a8a834c6adff5", "address" : " ", "systemid" : "4580C AFF-4F48-7F17AC105870" ] 2-116

137 Central Management APIs Field islocal version lastupdatemicros hostname selflink kind generation clockskewseconds id address product systemid True if this device is localhost. Product version. Last time this device state was updated. Host name of the devices. URI of this managed device object. Kind value. Generation of this state object. Clock skew between the managed device and the local device. ID of this device. Address of the device. Product code (typically, EM or BIG-IP). ID as reported by managed device. BIG-IQ API Reference Guide 2-117

138 Chapter 2 Add a managed device Adds a managed device. /mgmt/cm/cloud/managed-devices POST N/A "deviceaddress" : " ", "username" : "admin", "password" : "adminpassword", "automaticallyupdateframework" : "true" HTTP/ ACCEPTED "selflink" : " "kind" : "cm:cloud:managed-devices:manageddevicestate", "generation" : 0, "lastupdatemicros" : 0, "address" : " ", "automaticallyupdateframework" : "true", "id" : "a3dadffe649f4d6dab4a8a834c6adff5", "state" : "PENDING" Device setup takes place asynchronously and GET requests can be used to POLL the state of discovery. Recover a device in the POST_FAILED state If the device POST fails, the state will be POST_FAILED) discovery can be restarted by doing a device PATCH with a new password and optionally a new user name. The device discovery will be restarted with the new parameters. /mgmt/cm/cloud/managed-devices/<device-id> PATCH 2-118

139 Central Management APIs N/A "state" : "ACTIVE", "username" : "admin", "password" : "adminpassword" HTTP/ ACCEPTED "selflink" : " "kind" : "cm:cloud:managed-devices:manageddevicestate", "generation" : 0, "lastupdatemicros" : 0, "address" : " ", "id" : "a3dadffe649f4d6dab4a8a834c6adff5", "state" : "PENDING" Device setup takes place asynchronously and GETs can be used to POLL the state of discovery. Delete a managed device Deletes the specified managed device. /mgmt/cm/cloud/managed-devices/<device-id> DELETE N/A BIG-IQ API Reference Guide 2-119

140 Chapter 2 HTTP/ ACCEPTED "clockskewsecondscount" : 13, "hostname" : "<hostname>", "state" : "PENDING_DELETE", "selflink" : " "kind" : "cm:cloud:managed-devices:manageddevicestate", "edition" : "Final", "adminuser" : "admin", "icontrolkeyfile" : "/config/bigiq/ssl.key/bigiq-a7790cec-4d eb-2344cbabe60c.key", "id" : "a3dadffe649f4d6dab4a8a834c6adff5", "address" : " ", "emserverip" : " ", "icontrolcertfile" : "/config/bigiq/ssl.crt/bigiq-a7790cec-4d eb-2344cbabe60c.crt", "version" : "11.4.0", "lastupdatemicros" : , "build" : "354.0", "restframeworkversion": " ", "icontrolcertid" : " ", "generation" : 2, "systemid" : "4580C AFF-4F48-7F17AC105870", "product" : "BIG-IP" Note the PENDING_DELETE state. Eventually the device will be removed from the list (10-20 seconds). This allows internal cleanup to take place before removing the device

141 Central Management APIs Cloud licensing APIs This read-only worker responds to GET requests with the cloud's license status. Get license status Gets the current status of the cloud license. /mgmt/cm/cloud/license GET N/A BIG-IQ API Reference Guide 2-121

142 Chapter 2 A successful response will look similar to one of these three. "islicensed":true, "licensingmessage":"cloud license active. ", "maximumnodecount": , "currentnodecount":0, "generation":0, "lastupdatemicros":0, "kind":"cm:cloud:license:cloudlicensestate", "selflink":" "islicensed":true, "licensingmessage":"cloud license active. 0 out of 1000 nodes being used. ", "maximumnodecount":1000, "currentnodecount":0, "generation":0, "lastupdatemicros":0, "kind":"cm:cloud:license:cloudlicensestate", "selflink":" "islicensed":false, "licensingmessage":"cloud license missing. ", "maximumnodecount":0, "currentnodecount":0, "generation":0, "lastupdatemicros":0, "kind":"cm:cloud:license:cloudlicensestate", "selflink":" Note the PENDING_DELETE state, eventually the device will be removed from the list (10-20s). This allows internal cleanup to take place before removing the device

143 Central Management APIs EC2 nodes APIs Use these APIs to get, create, or delete EC2 nodes. Get EC2 node stats Gets statistics of a node that is managed in EC2. /cm/cloud/connectors/ec2/<connector-id>/nodes/<node-id>/stats GET N/A N/A BIG-IQ API Reference Guide 2-123

144 Chapter 2 HTTP/ OK "entries" : "health.summary.80" : "value" : 0, "description" : "availability_state: AVAIL_BLUE", "lastupdatemicros" : "health.stats.serverside.bytes-in" : "value" : 0, "description" : "SERVERSIDE: bytes-in", "lastupdatemicros" : "health.stats.80.serverside.bytes-in" : "value" : 0, "description" : "SERVERSIDE: bytes-in" "generation" : 16, "lastupdatemicros" : "kind" : "cm:cloud:connectors:ec2:72d5df3b-5e89-4c22-a7f cd28e83:nodes:3cd97f c bd-acbd-73a5942fbb40:stats:restworkerstats", "selflink" : " des/3cd97f cbd-acbd-73a5942fbb40/stats" 2-124

145 Central Management APIs Create node in EC2 Creates a node in EC2. /cm/cloud/connectors/ec2/<connector-id>/nodes POST N/A BIG-IQ API Reference Guide 2-125

146 Chapter 2 "properties" : [ "id" : "ImageId", "value" : "ami-abcd1234", "isrequired" : true "id" : "InstanceType", "value" : "m1.large", "isrequired" : false "id" : "DeviceMgmtUser", "value" : "admin" "isrequired": false, "description": "User account to use for managing this device - this is only relevant when node represents a managed device. If unspecified then it will default to admin", "id" : "DeviceMgmtPassword", "value" : "Str)ngP@ssw0rd", "isrequired": false, "description": "Password to use for managing this device - this is only relevant when node represents a managed device. If unspecified then it will be auto-generated for BIG-IQ Cloud provisioned BIG-IP devices and otherwise set to default admin password", "networkinterfaces" : [ "localaddress" : " ", "virtualaddress" : " ", "subnetaddress" : " /24" "virtualaddress": " ", "subnetaddress" : " /24" "subnetaddress" : " /24" "provideronly" : true, "devicediscoveryinterface":

147 Central Management APIs HTTP/ Created "items" : [ "nodeid" : "73120fcb-5be0-4ea5-a0ab abf18e", "cloudconnectorreference" : "link" : " "properties" : [ "id" : "ImageId", "isrequired": true, "value" : "ami-abcd1234" "id" : "InstanceType", "isrequired": false, "value" : "m1.large" "id" : "InstanceId", "isrequired": false, "value" : "i-2693bd3d" "id" : "KeyName", "isrequired": false, "value" : "f5-bigiq-keypair-8b2a8663-f4c1-4b88-9a1c-63fe214d7273" "id" : "KeyPrivate", "isrequired": false, "value" : "-----BEGIN RSA PRIVATE KEY-----MIIEpAIBAAKCAQEAnOkNn+y3A3j6RJg6Wp+pE+fmkE73eEn5akdhoe+n1oUrmESt7n9u5FRXvpiphn5p43hExeQZPSJg9OsLTWbj34k JaZ1mPYXSbkdKOYurhZhFXHhteu1VjdBDtKs8OBGG2AyFsqFMPRhcvCchDDCcpV90F+QkF1sfe2T9SAdJauCwX1LaPcyfG+cb9xOoWzLAvx MT/Stv9M15pkQXVlr4KM19fas2LyxfUXOjkCWOSp+FITYyTAW/G2Z6KpBzuckezm9d/5M75q6D2DmO3u2c9SKdwEZ4OWWQJ8VDk2+dwuJn4 gvuyjqlv3em/ddvwfvqb2+vesfyqypyzrbgaqgfpwidaqabaoibagapuruez904ntwi3vmfrk/bm4x94sncciicwee101nxv9aojdxjg92o95 WASca8WFAzq5hB6PFZyFAuVjvolefltb5QAKUUFKC6flyw25M+HZA8syrXeMVyLN8p0fnAEwii3r0Myz1f8DWXyfUizTEW/FYlbCXMDP7l2tw6zx VI9CWIBA3KJQzeP3H1FuRqwe3LYzsMl53MTGEBoyyCZEQEGgWke6zkEPBUVlNxr26J0oGp7NcRjd7d7GxTQTjsZj3PzUcdgLaRyL715pVoru EvMi/vuqcjnveCVOEMc2xHiGlc/VGb0ap/Qf9fFepo49T5MsTwFrvbCBKsNv7x9cECgYEA0MsC0RQ9yabEj9kPLwcLnsztC3pr5K88QIVVdU9263i vrrx+m4upbwtklgo9ml8kjhvuibiweovmnybihoy8ftnh4dbcrvwnkkizw2qi1krcimsrulmako0rolmzwiw9qifwzrp1disee8pkyvyrvyp98u 14vDAwgF5u54I95qECgYEAwGMP8bN/gYdOfndt5+uRBZRvTnuXAP5R+gG+GX6+tLwRB8/UimqT7K9Ic3XdyQ+ImZrKQiK2BpRXyipMdYTvRz EeWu8EyDwg3PyYZJ1uJag3qylzAQrOza8cKXn7o3iE0AKpdOG5z7MlDD3Tb6NcNdQi7GnpQX0fiSiIAo0wGd8CgYAH42Ob2pPrBm3usVitgiqiO UPLZzikTyqLlX4BDJuFke2xQBb2g1RqA3hT2uDO8qjHba61b7hfsOFlu8Z9wLyQXhQYn/Kgec5U7IFCrMiyJ+jpqdnljH25HdNEzRbFhabewpuw7A r8b+whcqi8ymeo70es2kxzd68faovugzgtgqkbgqcqwmyswicdy3hyoi2ddizbwq3rc1ngmm+js9m0h2rja0cdikp0l6xtpumsoofremse JdYDO1LrfnxBULTEtgFcixxyrgMQ/VSn961EIbV++HTaRGhFOvmkW/HWs+DhfPw0Zrb+/EOXqesa7L+DsSUbsIt/w8O6rfy3aMENaVB3BwKBgQ Czm4tkFf4oaHpmVpRxD5oyz9IkDw+hvqlhTK801/6xyEhJg5nNzp20TVpfPDV3XJ/1FlpRjq37J7FloI37YkBTvINQMTHMH10/lUsG2ws6UqA/1nCI y7r87qgkc1f0/plj8jk1d5slelmhkt6rfic8t0fezo8pq9dsf3kgt0xyha==-----end RSA PRIVATE KEY-----" "id" : "DeviceMgmtUser", "value" : "admin" "isrequired": false, "description": "User account to use for managing this device - this is only relevant when node represents a managed device. If unspecified then it will default to admin", "id" : "DeviceMgmtPassword", "value" : "Str)ngP@ssw0rd", "isrequired": false, "description": "Password to use for managing this device - this is only relevant when node represents a managed device. If unspecified then it will be auto-generated for BIG-IQ Cloud provisioned BIG-IP devices and otherwise set to default admin password", "ipaddress" : " ", "networkinterfaces" : [ "localaddress" : " ", "virtualaddress" : " ", "subnetaddress" : " /24" "localaddress" : " ", "virtualaddress" : " ", "subnetaddress" : " /24" "localaddress" : " ", "subnetaddress" : " /24" "state" : "STARTING", "provider" : false, "services" : [ "devicediscoveryinterface": 1, "devicereference": "link": " ] BIG-IQ API Reference Guide 2-127

148 Chapter

149 Central Management APIs Query for all EC2 nodes Gets all the nodes associated with a specific cloud connector. /cm/cloud/connectors/ec2/<connector-id>/nodes GET N/A N/A BIG-IQ API Reference Guide 2-129

150 Chapter 2 <span style="font-family: Verdana, Arial, Helvetica, sans-serif; color: #000000; font-size: x-small;"><span style="white-space: normal;">http/ OK "items" : [ "nodeid" : "73120fcb-5be0-4ea5-a0ab abf18e", "cloudconnectorreference" : "link" : " "properties" : [ "id" : "ImageId", "value" : "ami-abcd1234" "id" : "InstanceType", "value" : "m1.large" "id" : "InstanceId", "value" : "i-2693bd3d" "id" : "KeyName", "value" : "f5-bigiq-keypair-8b2a8663-f4c1-4b88-9a1c-63fe214d7273" "id" : "KeyPrivate", "value" : "-----BEGIN RSA PRIVATE KEY-----MIIEpAIBAAKCAQEAnOkNn+y3A3j6RJg6Wp+pE+fmkE73eEn5akdhoe+n1oUrmESt7n9u5FRXvpiphn5p43hExeQZPSJg9OsL TWbj34kJaZ1mPYXSbkdKOYurhZhFXHhteu1VjdBDtKs8OBGG2AyFsqFMPRhcvCchDDCcpV90F+QkF1sfe2T9SAdJauCwX1LaPcyfG +cb9xoowzlavxmt/stv9m15pkqxvlr4km19fas2lyxfuxojkcwosp+fityytaw/g2z6kpbzuckezm9d/5m75q6d2dmo3u2c9skdwe Z4OWWQJ8VDk2+dwuJn4gVUYJQlV3EM/DdVWfvqb2+vEsfyqypyZRBGaqGfPwIDAQABAoIBAGaPurUez904NTWi3vmfRK/bM4x94S ncciicwee101nxv9aojdxjg92o95wasca8wfazq5hb6pfzyfauvjvolefltb5qakuufkc6flyw25m+hza8syrxemvyln8p0fnaewii3r 0Myz1f8DWXyfUizTEW/FYlbCXMDP7l2tw6zxVI9CWIBA3KJQzeP3H1FuRqwe3LYzsMl53MTGEBoyyCZEQEGgWke6zkEPBUVlNxr26 J0oGp7NcRjd7d7GxTQTjsZj3PzUcdgLaRyL715pVoruEvMi/vuqcjnveCVOEMc2xHiGlc/VGb0ap/Qf9fFepo49T5MsTwFrvbCBKsNv7x9c ECgYEA0MsC0RQ9yabEj9kPLwcLnsztC3pr5K88QIVVdU9263ivrrX+M4UPBwTKlGO9ML8KjhvuIBiWeovmNyBIHoY8ftNh4dBcrvwnkki Zw2qi1krCimsRuLMAKo0ROlmzWIw9qiFWzRp1disEe8PKyvYRVyP98U14vDAwgF5u54I95qECgYEAwGMP8bN/gYdOfndt5+uRBZRv TnuXAP5R+gG+GX6+tLwRB8/UimqT7K9Ic3XdyQ+ImZrKQiK2BpRXyipMdYTvRzEeWu8EyDwg3PyYZJ1uJag3qylzAQrOza8cKXn7o3i E0AKpdOG5z7MlDD3Tb6NcNdQi7GnpQX0fiSiIAo0wGd8CgYAH42Ob2pPrBm3usVitgiqiOUPLZzikTyqLlX4BDJuFke2xQBb2g1RqA3h T2uDO8qjHba61b7hfsOFlu8Z9wLyQXhQYn/Kgec5U7IFCrMiyJ+jpqdnljH25HdNEzRbFhabewpuw7Ar8B+wHcQI8YMeO70Es2KxzD68 FaovuGzGTgQKBgQCqWMysWiCDY3hYOI2DdizBwQ3Rc1NgmM+jS9m0H2rjA0cdIKP0L6xtPUMsoOfReMSeJdYDO1LrfnxBULTEtgF cixxyrgmq/vsn961eibv++htarghfovmkw/hws+dhfpw0zrb+/eoxqesa7l+dssubsit/w8o6rfy3amenavb3bwkbgqczm4tkff4oah pmvprxd5oyz9ikdw+hvqlhtk801/6xyehjg5nnzp20tvpfpdv3xj/1flprjq37j7floi37ykbtvinqmthmh10/lusg2ws6uqa/1nciy7r87 QGKc1F0/pLJ8jk1d5SLELMHkt6rfIc8T0fEzo8pQ9DSF3Kgt0XyhA==-----END RSA PRIVATE KEY-----" "state" : "RUNNING", "ipaddress" : " ", "networkinterfaces" : [ "localaddress" : " ", "virtualaddress" : " ", "subnetaddress" : " /24"" "localaddress" : " ", "virtualaddress" : " ", "subnetaddress" : " /24" "localaddress" : " ", "subnetaddress" : " /24" "provider" : false, "services" : [ ] ] </span></span> 2-130

151 Central Management APIs networkinterfaces is an ordered list with the first position representing eth0, second position representing eth1, etcetera. Delete node in EC2 Deletes a node in EC2. /cm/cloud/connectors/ec2/<connector-id>/nodes/<node-id> DELETE N/A BIG-IQ API Reference Guide 2-131

152 Chapter 2 HTTP/ OK "items" : [ "nodeid" : "73120fcb-5be0-4ea5-a0ab abf18e", "cloudconnectorreference" : " "properties" : [ "id" : "ImageId", "value" : "ami-abcd1234" "id" : "InstanceType", "value" : "m1.small" "id" : "InstanceId", "value" : "i-2693bd3d" "state" : "DELETED", "ipaddress" : " ", "networkinterfaces" : [ "localaddress" : " ", "virtualaddress" : " ", "subnetaddress" : " /24" "localaddress" : " ", "virtualaddress" : " ", "subnetaddress" : " /24" "localaddress" : " ", "subnetaddress" : " /24" "provider" : false, "services" : [ "serviceport" : "80", "servicereference" : "link" : " ] 2-132

153 Central Management APIs Deleting the Elastic Network Interfaces (ENIs) (Also referred to as NICs) when instances are terminated. Problem: Previously, when we terminate the instance, its ENIs are not deleted. There is a limited number of ENIs allowed. We create and assign the ENIs when an instance is created. Approach: 1. Deletes the ENIs when the instance is deleted. When an instance is deleted, we get a callback. We tried deleting the ENI here but we get an "in-use" error. This is because the instance goes through various state transitions and the ENI is still being in-use. We cannot detach the ENI here because the attachment ID is gone. 2. Mark the delete-on-termination flag in the ENI object during instance creation. We ran into specific issues: a. Set delete-on-termination when RunInstances creates ENIS: this works fine but creates problems with Elastic IP addresses b. Set delete-on-termination when RunInstances attaches existing ENIs: this is not supported by EC2 c. Set delete-on-termination after create ENIS but before calling RunInstances: is not supported since there is no attachment ID 3. Mark delete-on-termination right before TerminateInstances. This approach works. When terminateinstances() is called, BIG-IQ Cloud: a. Retrieves the list of NICs for the specified list of instances b. Marks delete-on-termination flag on each NIC c. Continues with terminating the instance Testing: To verify the NICs are actually deleted, we need to verify on EC2 the NICS are deleted. F5 wrote an EC2 test worker that allows the EC2 integration to call AWS indirectly to get a list of NICs. At the end of the integration test, we make this call and verify that there are no NICs in an "available" state, that is, left hanging around. Modify node secondary and virtual addresses in EC2 Modifies node secondary and virtual addresses in EC2. /cm/cloud/connectors/ec2/<connector-id>/nodes/<node-id> PATCH N/A BIG-IQ API Reference Guide 2-133

154 Chapter 2 "networkinterfaces" : [ "localaddress" : " ", "subnetaddress" : " /24" "localaddress": " ", "virtualaddress": " ", "subnetaddress" : " /24", "secondaryaddresses": [ "virtualaddress": " " "virtualaddress": " ", "localaddress": " " ] "subnetaddress" : " /24" "provideronly" : true 2-134

155 Central Management APIs HTTP/ Created "items" : [ "nodeid" : "73120fcb-5be0-4ea5-a0ab abf18e", "cloudconnectorreference" : "link" : " "properties" : [ "id" : "ImageId", "isrequired": true, "value" : "ami-abcd1234" "id" : "InstanceType", "isrequired": false, "value" : "m1.large" "id" : "InstanceId", "isrequired": false, "value" : "i-2693bd3d" "id" : "KeyName", "isrequired": false, "value" : "f5-bigiq-keypair-8b2a8663-f4c1-4b88-9a1c-63fe214d7273" "id" : "KeyPrivate", "isrequired": false, "value" : "-----BEGIN RSA PRIVATE KEY-----MIIEpAIBAAKCAQEAnOkNn+y3A3j6RJg6Wp+pE+fmkE73eEn5akdhoe+n1oUrmESt7n9u5FRXvpiphn5p43hExeQZPSJg9OsLTWbj34kJaZ1mPYXSbkd KOYurhZhFXHhteu1VjdBDtKs8OBGG2AyFsqFMPRhcvCchDDCcpV90F+QkF1sfe2T9SAdJauCwX1LaPcyfG+cb9xOoWzLAvxMT/Stv9M15pkQXVlr4KM19fas2 LyxfUXOjkCWOSp+FITYyTAW/G2Z6KpBzuckezm9d/5M75q6D2DmO3u2c9SKdwEZ4OWWQJ8VDk2+dwuJn4gVUYJQlV3EM/DdVWfvqb2+vEsfyqypyZRBGaq GfPwIDAQABAoIBAGaPurUez904NTWi3vmfRK/bM4x94SnCCIIcWEe101nXv9AOjDXJG92o95WASca8WFAzq5hB6PFZyFAuVjvolefltb5QAKUUFKC6flyw25M+ HZA8syrXeMVyLN8p0fnAEwii3r0Myz1f8DWXyfUizTEW/FYlbCXMDP7l2tw6zxVI9CWIBA3KJQzeP3H1FuRqwe3LYzsMl53MTGEBoyyCZEQEGgWke6zkEPBU VlNxr26J0oGp7NcRjd7d7GxTQTjsZj3PzUcdgLaRyL715pVoruEvMi/vuqcjnveCVOEMc2xHiGlc/VGb0ap/Qf9fFepo49T5MsTwFrvbCBKsNv7x9cECgYEA0MsC0R Q9yabEj9kPLwcLnsztC3pr5K88QIVVdU9263ivrrX+M4UPBwTKlGO9ML8KjhvuIBiWeovmNyBIHoY8ftNh4dBcrvwnkkiZw2qi1krCimsRuLMAKo0ROlmzWIw9qiF WzRp1disEe8PKyvYRVyP98U14vDAwgF5u54I95qECgYEAwGMP8bN/gYdOfndt5+uRBZRvTnuXAP5R+gG+GX6+tLwRB8/UimqT7K9Ic3XdyQ+ImZrKQiK2BpR XyipMdYTvRzEeWu8EyDwg3PyYZJ1uJag3qylzAQrOza8cKXn7o3iE0AKpdOG5z7MlDD3Tb6NcNdQi7GnpQX0fiSiIAo0wGd8CgYAH42Ob2pPrBm3usVitgiqiOU PLZzikTyqLlX4BDJuFke2xQBb2g1RqA3hT2uDO8qjHba61b7hfsOFlu8Z9wLyQXhQYn/Kgec5U7IFCrMiyJ+jpqdnljH25HdNEzRbFhabewpuw7Ar8B+wHcQI8YMe O70Es2KxzD68FaovuGzGTgQKBgQCqWMysWiCDY3hYOI2DdizBwQ3Rc1NgmM+jS9m0H2rjA0cdIKP0L6xtPUMsoOfReMSeJdYDO1LrfnxBULTEtgFcixxyrgM Q/VSn961EIbV++HTaRGhFOvmkW/HWs+DhfPw0Zrb+/EOXqesa7L+DsSUbsIt/w8O6rfy3aMENaVB3BwKBgQCzm4tkFf4oaHpmVpRxD5oyz9IkDw+hvqlhTK80 1/6xyEhJg5nNzp20TVpfPDV3XJ/1FlpRjq37J7FloI37YkBTvINQMTHMH10/lUsG2ws6UqA/1nCIy7r87QGKc1F0/pLJ8jk1d5SLELMHkt6rfIc8T0fEzo8pQ9DSF3Kgt 0XyhA==-----END RSA PRIVATE KEY-----" "id" : "DeviceMgmtUser", "value" : "admin" "isrequired": false, "description": "User account to use for managing this device - this is only relevant when node represents a managed device. If unspecified then it will default to admin", "id" : "DeviceMgmtPassword", "value" : "Str)ngP@ssw0rd", "isrequired": false, "description": "Password to use for managing this device - this is only relevant when node represents a managed device. If unspecified then it will be auto-generated for BIG-IQ provisioned BIG-IP device and otherwise set to default admin password", "ipaddress" : " ", "networkinterfaces" : [ "localaddress" : " ", "subnetaddress" : " /24" "localaddress" : " ", "virtualaddress" : " ", "subnetaddress" : " /24", "secondaryaddresses": [ "virtualaddress": " ", "localaddress": " " "virtualaddress": " ", "localaddress": " " ] "localaddress" : " ", "subnetaddress" : " /24" "state" : "STARTING", "provider" : false, "services" : [ "devicediscoveryinterface": 1, "devicereference": "link": " ] BIG-IQ API Reference Guide 2-135

156 Chapter 2 Add/remove of secondary addresses is supported. Add/remove of virtual addresses is supported. Static addressing is supported. virtualaddress means Elastic IP. Dynamic virtualaddress is requested by specifying " ". BIG-IP application virtual servers correspond to node secondary addresses

157 Central Management APIs OpenStack nodes APIs Node properties Use these APIs to get, create, or delete OpenStack nodes. A node contains a set of parameters as part of its complete specification. Creating a node requires three parameters. Name NodeName The human-readable name for your node. Not necessarily unique. Flavor The name or ID (from OpenStack) of the flavor to create this node. ImageId The name or ID (from OpenStack) of the image to create this node. The following example illustrates a complete node specification. "properties":[ "id":"nodename", "value":"web-server" "id":"flavor", "value":"m1.small" "id":"imageid", "value":"ubuntu web" ] You may see other properties on nodes when you examine them. They include: Additional properties Name NodeTemplateName BIG-IP For a node template, which corresponds to an OpenStack image. This is the name of the image. If this is present and is true, it is a node or node template BIG-IQ API Reference Guide 2-137

158 Chapter 2 Create a new node Create a new OpenStack node. /cm/cloud/connectors/openstack/<connector-id>/nodes/ POST N/A "properties":[ "id":"nodename", "value":"alain-test" "id":"flavor", "value":"m1.small" "id":"imageid", "value":"myfirstimage" "networkinterfaces": ["localaddress": " /24" "cloudconnectorreference" : "link": " a3d" See Node Properties (preceding) for details on the properties. The network interfaces is a list of subnets on which you wish to create your interfaces: they must correspond with existing subnets that you have access to in OpenStack The cloudconnectorreference is the OpenStack connector that you previously made. You can use its selflink here. Get node Gets an OpenStack node /cm/cloud/connectors/openstack/<connector-id>/nodes/<node-id> GET N/A None 2-138

159 Central Management APIs "selflink": " cf1/nodes/3e780f abc-ba51-eb787b0ec226", "kind": "cm:cloud:nodes:node", "lastupdatemicros": , "generation": 2, "nodeid": "3e780f abc-ba51-eb787b0ec226", "state": "RUNNING", "properties": [ "value": "cf b bf0-c d44", "isrequired": false, "id": "ServerId" "value": "0dc3d041-3ec af-dc994d816649", "isrequired": false, "id": "ImageId" "value": "server1", "isrequired": false, "id": "NodeName" "ipaddress": " ", "networkinterfaces": [ "localaddress": " " "services": [ "provideronly": false, "cloudconnectorreference": "link": " cf1" BIG-IQ API Reference Guide 2-139

160 Chapter 2 Get all nodes Gets all OpenStack nodes. /cm/cloud/connectors/openstack/<connector-id>/nodes GET N/A N/A 2-140

161 Central Management APIs "items": [ "selflink": " cf1/nodes/3e780f abc-ba51-eb787b0ec226", "kind": "cm:cloud:nodes:node", "lastupdatemicros": , "generation": 2, "nodeid": "3e780f abc-ba51-eb787b0ec226", "state": "RUNNING", "properties": [ "value": "cf b bf0-c d44", "isrequired": false, "id": "ServerId" "value": "0dc3d041-3ec af-dc994d816649", "isrequired": false, "id": "ImageId" "value": "server1", "isrequired": false, "id": "NodeName" "ipaddress": " ", "networkinterfaces": [ "localaddress": " " "services": [ "provideronly": false, "cloudconnectorreference": "link": " cf1" ] BIG-IQ API Reference Guide 2-141

162 Chapter 2 Get OpenStack Node Stats Gets the statistics for a specific OpenStack node. /cm/cloud/connectors/openstack/<connector-id>/nodes/<node-id>/stats GET N/A "entries": "health.stats.raw.tap28efd262-b0_rx_drop": "value": 0.0, "description": "tap28efd262-b0_rx_drop", "lastupdatemicros": "itemid": "value": 0.0, "description": "3e780f abc-ba51-eb787b0ec226", "lastupdatemicros": "health.stats.raw.cpu0_time": "value": E12, "description": "cpu0_time", "lastupdatemicros": more stats These are the server diagnostics from OpenStack, unfiltered and raw. Make sure the Nova compute_extension:server_diagnostics policy allows non-administrator access, or these will not be present

163 Central Management APIs Delete Node Deletes a node in OpenStack. /cm/cloud/connectors/openstack/<connector-id>/nodes/<node-id> DELETE N/A BIG-IQ API Reference Guide 2-143

164 Chapter

165 3 Shared APIs Shared APIs overview Group resolver view worker APIs File transfer worker APIs In statistics helper worker API REST worker availability APIs REST worker subscriber s list APIs Rest diagnostics worker APIs Multiple user coordinator APIs Device resolver APIs Group resolver APIs Device information API Statistics information and metadata API User authentication API Authentication token worker API Licensing APIs User authorization APIs Authorization roles APIs Authorization roles resource groups APIs Licensing activation APIs Registration key management APIs Licensing pools APIs

166

167 Shared APIs Shared APIs overview The APIs referred to as shared APIs are documented in this chapter. BIG-IQ API Reference Guide 3-1

168 Chapter 3 Group resolver view worker APIs The group resolver view worker APIs provide a list of all the workers under /shared, /tm, and /cm. On receiving the GET request, it obtains the worker directory listing from the group resolver worker and generates the response by filtering all the worker URIs registered under the requesting URI. List all the worker URIs under /shared Gets the listing of all the public workers listening under URI /shared. /shared GET N/A N/A 3-2

169 Shared APIs "items": [ "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " BIG-IQ API Reference Guide 3-3

170 Chapter 3 3-4

171 Shared APIs List all the worker URIs under /tm Gets the listing of all the public workers listening under URI /tm. /tm GET N/A N/A BIG-IQ API Reference Guide 3-5

172 Chapter 3 "items": [ "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " 3-6

173 Shared APIs List all the worker URIs under /cm Gets the listing of all the public workers listening under URI /cm. /cm GET N/A N/A BIG-IQ API Reference Guide 3-7

174 Chapter 3 "items": [ "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "link": " "generation": 0, "lastupdatemicros": , "kind": "cm:restgroupresolverviewstate", "selflink": " 3-8

175 Shared APIs File transfer worker APIs The file transfer worker allows users to asynchronously upload and download files using a series of POST and GET requests. The file transfer uploads worker listens to URI /shared/file-transfer/uploads. The file transfer downloads worker listens to a set of URIs under /shared/file-transfer/downloads. There is one URI for each directory. Get file contents using downloads worker Optional Request Headers Gets file content for the file in /usr/local/rest/presentation. If the content-range header is not specified, it gives the entire file as a single chunk. Depending on the file type, it sets content-type on the response. /shared/file-transfer/downloads/myrpmfile.rpm GET N/A Content-range: /65536 HTTP/ OK Content-Length: 8192 Content-Range:0.8191/65536 Content-Type: application/octet-stream Response body with file contents Post file contents using downloads worker Upload the file content using series of POST operations (chunked upload). /shared/file-transfer/uploads/myrpmfile.rpm POST N/A BIG-IQ API Reference Guide 3-9

176 Chapter 3 Optional Request Headers Content-range: /65536 Content-length: 8192 HTTP/ OK "remainingbytecount":57344, "totalbytecount":65536, "chunkbytecount":65536, "localfilepath":"/var/config/rest/downloads/tmp/myrpmfile.rpm", "generation":0, "lastupdatemicros": Cancel existing upload An active download can be cancelled if a DELETE is sent to the file name URI suffix (with no body). /shared/file-transfer/uploads/myrpmfile.rpm DELETE N/A Optional Request Headers HTTP/ OK 3-10

177 Shared APIs In statistics helper worker API This API allows for an in-memory only collection of name-to-stat objects that can be used for health, worker state, and statistics to be viewed. The response contains data that does not live in the worker PODOs. Get worker statistics Gets current statistics. *parent worker URI*/stats GET N/A BIG-IQ API Reference Guide 3-11

178 Chapter 3 HTTP/ OK "entries": "com.f5.rest.common.restworker.isfinegrainedcollection": "value": 1, "lastupdatemicros": , "updatetype": "BASIC" "com.f5.rest.common.restworker.issynchronized": "value": 1, "lastupdatemicros": , "updatetype": "BASIC" "com.f5.rest.common.restworker.ispersisted": "value": 1, "lastupdatemicros": , "updatetype": "BASIC" "com.f5.rest.common.restworkerstate.lastupdatemicros": "value": 0, "lastupdatemicros": , "updatetype": "BASIC" "com.f5.rest.common.restworker.isindexed": "value": 1, "lastupdatemicros": , "updatetype": "BASIC" "com.f5.rest.common.restworker.isreplicated": "value": 1, "lastupdatemicros": , "updatetype": "BASIC" "com.f5.rest.common.restworkerstate.generation": "value": 0, "lastupdatemicros": , "updatetype": "BASIC" "com.f5.rest.common.restworker.iseagerlyconsistent": "value": 1, "lastupdatemicros": , "updatetype": "BASIC" "generation": 8, "lastupdatemicros": , "kind": "tm:shared:iapp:blocks:stats:restworkerstats", "selflink": " 3-12

179 Shared APIs Update worker statistics Adds or updates statistical entries. *parent worker URI*/stats POST N/A "stats": [ "name": "stat1", "value": 1.0, "description": "stat1 desc", "lastupdatemicros": 0, "updatetype": "BASIC", "statinforeference": "link": " "name": "stat2", "value": 2.0, "lastupdatemicros": 0, "updatetype": "BASIC" ] HTTP/ OK Delete worker statistics Removes an entry from the statistics map. *parent worker URI*/stats DELETE BIG-IQ API Reference Guide 3-13

180 Chapter 3 N/A "statnames": [ "stat2", "stat1", "stat3" ] HTTP/ OK REST worker availability APIs This API returns the health status of the specified REST worker. Get worker availability A worker responds to this API (<worker>/available) when it has completed the second phase of its start sequence, which means: If the worker had initial state in storage, state has been loaded/verified/optional cached. If the worker had dependencies on other workers, its dependencies are available. If <worker>/available returns 200, the worker is ready to process REST operations. Gets health status of the specified REST worker. worker/available GET N/A 3-14

181 Shared APIs HTTP/ OK BIG-IQ API Reference Guide 3-15

182 Chapter 3 REST worker subscriber s list APIs This API returns the list of the subscribers to the specified REST worker/resource. Get worker availability Gets the list of the subscribers of the specified REST worker/resource. worker/subscriptions GET N/A HTTP/ OK "subscribers":[" 100/188795a fa5d aefd3" "generation":2, "lastupdatemicros":

183 Shared APIs Rest diagnostics worker APIs Use this API to access diagnostic content and statistics. You also can set the tracing and logging levels and shut down or restart the REST server. Get diagnostics Gets logs and stack traces. shared/diagnostics GET HTTP/ OK "hostparameters": "isproductioninstance": true, "port": 8100, "storagedirectory": "/var/config/rest/storage", "configindexdirectory": "/var/config/rest/index" "operationtracinglevel": "OFF", "jvmfreememory": , "jvmtotalmemory": , "jvmmaxmemory": , "jvmavailableprocessors": 2, "jvmthreadcount": 31, "severelogs": [ "warninglogs": [ "[WARNING][1][14 Jan :49:54 UTC][RestServer][bindServerChannel] *** Server binding to all interfaces. Not secure! ***\n\n", "[WARNING][3][14 Jan :49:54 UTC][RestWorkerHost][start] Allowing communication with the outside using HTTP using port 8100",... ******Note: Typical SIGNIFICANTLY truncated for brevity.***** BIG-IQ API Reference Guide 3-17

184 Chapter 3 Get device statistics diagnostics Gets current values of CPU system/user/idle percentage by core, memory (free and total), and mounted file system usage. shared/diagnostics/device-stats GET HTTP/ OK "entries": "cpu.0_1.idle": "value": , "lastupdatemicros": , "updatetype": "MOVING_AVERAGE" "cpu.0_0.usageratio": "value": 0.08, "lastupdatemicros": , "updatetype": "MOVING_AVERAGE" "cpu.0_1.system": "value": , "lastupdatemicros": , "updatetype": "MOVING_AVERAGE" "cpu.0_1.usageratio": "value": 0.06, "lastupdatemicros": , "updatetype": "MOVING_AVERAGE" "cpu.0_0.system": "value": , "lastupdatemicros": , "updatetype": "MOVING_AVERAGE" "cpu.0_0.user": "value": , "lastupdatemicros": , "updatetype": "MOVING_AVERAGE" "cpu.0_0.idle": "value": , "lastupdatemicros": , "updatetype": "MOVING_AVERAGE" "cpu.0_1.user": "value": , "lastupdatemicros": , "updatetype": "MOVING_AVERAGE"... ******Note: Typical truncated for brevity.***** 3-18

185 Shared APIs BIG-IQ API Reference Guide 3-19

186 Chapter 3 Set the tracing and logging levels Sets the tracing level and the logging levels. If the tracing level is FINE, FINER, or FINEST, then operation tracing is enabled and operations are captured in the traces collection available through GET. FINER also collects request/response headers. FINEST also collects request/response bodies. Use these sparingly with narrowed scope using tracelimitperworker, uripathblacklist and uripathwhitelist. /shared/diagnostics PATCH "operationtracinglevel": "FINE" HTTP/ OK "hostparameters": "isproductioninstance":false "operationtracinglevel":"fine", "jvmfreememory":0, "jvmtotalmemory":0, "jvmmaxmemory":0, "jvmavailableprocessors":0, "jvmthreadcount":0, "traces": "tracelimitperworker":1000, "generation":0, "lastupdatemicros":0 Set the URIs that will be traced: white list Sets the tracing level and the logging levels. If the tracing level is FINE, FINER, or FINEST, then operation tracing is enabled and operations are captured in the traces collection available through GET. FINER also collects request/response headers. FINEST also collects request/response bodies. Use these sparingly with narrowed scope using tracelimitperworker, uripathblacklist and uripathwhitelist. /shared/diagnostics 3-20

187 Shared APIs PATCH "operationtracinglevel": "FINER", "uripathwhitelist": [ "/", "/shared/echo" "tracelimitperworker":100 HTTP/ OK "hostparameters": "isproductioninstance":false "uripathwhitelist": [ "/", "/shared/echo" "operationtracinglevel":"finer", "jvmfreememory":0, "jvmtotalmemory":0, "jvmmaxmemory":0, "jvmavailableprocessors":0, "jvmthreadcount":0, "traces": "tracelimitperworker":1000, "generation":0, "lastupdatemicros":0 Shutdown or restart REST server Shuts down REST server. If isrestartrequest is true, restart it also. /shared/diagnostics PATCH BIG-IQ API Reference Guide 3-21

188 Chapter 3 "isrestartrequest": "true" HTTP/ OK "isrestartrequest" : true OR <?xml version="1.0" encoding="iso "?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" " <html xmlns=" lang="en" xml:lang="en"> <head> <title>bad Gateway!</title> <link rev="made" href="mailto:[email protected]" /> <style type="text/css"><!--/*--><![cdata[/*><!--*/ body color: #000000; background-color: #FFFFFF; a:link color: #0000CC; p, address margin-left: 3em; span font-size: smaller; /*]]>*/--></style> <style type="text/css"><!--/*--><![cdata[/*><!--*/ * width: 400px; font-size: 100%; font-style: normal; html text-align: center; body background: #ffffff; text-align: left; font-family: sans-serif; font-size: 70%; color: #333333; a,span width: auto; h1,h2,h3 margin: 20px 0px 20px 0px; font-weight: bold; h1 padding: 5px; border: 1px solid #999999; background: #eeeeee; color: #000000; font-size: 125%; hr height: 1px; border: none; border-top: 1px solid #999999; img border: 0px; p width: 350px; margin: 15px 25px 15px 25px; line-height: 135%; /*]]>*/--></style> </head> <body> <h1>bad Gateway!</h1> <p> The proxy server received an invalid response from an upstream server. </p> <p> The proxy server could not handle the request <em><a href="/mgmt/shared/diagnostics">patch /mgmt/shared/diagnostics</a></em>.<p> Reason: <strong>error reading from remote server</strong></p> </p> <h2>error 502</h2> <address> <a href="/"> </a> <span>tue Jan 14 15:15: </span> </address> </body> </html> 3-22

189 Shared APIs BIG-IQ API Reference Guide 3-23

190 Chapter 3 Multiple user coordinator APIs This API makes it possible to associate specific REST resources with a specific user. Get all user and resource associations Gets all of the associations between users and resources. /shared/multi-user-coordinator GET N/A 3-24

191 Shared APIs HTTP/ OK "items": [ "name": "a highly coordinated user", "description": "Bo knows coordination", "resourcemasks" : [ "/mgmt/testcoordinator/specific-resource-538d", "/mgmt/testcoordinator/another-specific-resource-50e6/specific-resource-538d", "/mgmt/testcoordinator/fancy-resource-f74f/specific-resource-538d" "resourcegroupsreferences" : [ "link" : " a4db346" "link" : " 46d9abb" "lastupdatemicros" : , "userreference" : "link" : " "createdatetime" : " T15:06: ", "uuid" : "5bc1c80f-14cf-47de-b7fe-548c5a03177c", "editorrolereference" : "link" : " "selflink" : " ", "kind" : "shared:multi-user-coordinator:multiusercoordinatorstate", "generation" : 1 "generation": 1, "kind": "shared:multi-user-coordinator:multiusercoordinatorcollection", "lastupdatemicros": , "selflink": " BIG-IQ API Reference Guide 3-25

192 Chapter 3 Create a resource association Associates the specified resources with the specified role. /shared/multi-user-coordinator POST N/A Request Body "name": "a highly coordinated user", "description": "Bo knows coordination", "userreference": "link": " "resourcemasks": [ "/mgmt/shared/scores/touchdown", "/mgmt/shared/scores/homerun" ] 3-26

193 Shared APIs HTTP/ OK "uuid": "deedddb a3b3-0c000714ca16", "name": "a highly coordinated user", "description": "Bo knows coordination", "createdatetime": " T11:21: ", "userreference": "link": " "resourcemasks": [ "/mgmt/shared/scores/touchdown", "/mgmt/shared/scores/homerun" "resourcegroupsreferences" : [ "link" : " a4db346" "link" : " 46d9abb" "editorrolereference" : "link" : " "generation": 1, "lastupdatemicros": , "kind": "shared:multi-user-coordinator:multiusercoordinatorstate", "selflink": " 16" BIG-IQ API Reference Guide 3-27

194 Chapter 3 Remove a resource association Removes the association between resources and the role. /shared/multi-user-coordinator/uuid DELETE N/A 3-28

195 Shared APIs Device resolver APIs Device Resolver allows the discovery of other devices and assigning devices to groups. The device resolver is composed of two RestCollectionWorkers: /shared/resolver/device-groups /shared/resolver/device-groups/<group name>/devices Each of these URIs supports 11 different types of operations. A sampling of these operations is included below, but see the RCW specification for additional options. Get device resolver groups Gets all the device resolver groups. /shared/resolver/device-groups GET N/A HTTP/ OK "items": [ "groupname": "<device_group_name>", "generation": 1, "lastupdatemicros": , "kind": "shared:resolver:device-groups:devicegroupstate", "selflink": " > </pre> " "generation": 1, "kind": "shared:resolver:device-groups:devicegroupcollectionstate", "lastupdatemicros": , "selflink": " BIG-IQ API Reference Guide 3-29

196 Chapter 3 Get a single group Gets details on a single group. /shared/resolver/device-groups/<device_group_name> GET N/A HTTP/ OK "groupname": "<device_group_name>", "generation": 1, "lastupdatemicros": , "kind": "shared:resolver:device-groups:devicegroupstate", "selflink": " 3-30

197 Shared APIs Get devices within a group Gets all devices within a group. /shared/resolver/device-groups/<device_group_name>/devices GET N/A BIG-IQ API Reference Guide 3-31

198 Chapter 3 HTTP/ OK "items": [ "uuid": "5964f b5fc-dde14d4d6cfa", "deviceuri": " "state": "ACTIVE", "address": " ", "clockskewsecondscount": -7, "systemid": "FB B8D4-3FB8-F4E56318D8C2", "hostname": "<hostname>", "version": "11.5.0", "product": "BIG-IP", "edition": "Final", "build": "971.0", "restframeworkversion": " ", "properties": "supportsrulelogging": true, "supportsiruleaction": true, "supportsfwpolicy": true "icontrolkey": "<removed for brevity>", "icontrolcert": "<removed for brevity>", "icontrolcertid": " ", "groupname": "<device_group_name>", "generation": 3, "lastupdatemicros": , "kind": "shared:resolver:device-groups:restdeviceresolverdevicestate", "selflink": " fc-dde14d4d6cfa" "uuid": "83dc1e7b-d4db c8-ea7579a5bc53", "deviceuri": " "state": "ACTIVE", "address": " ", "clockskewsecondscount": 0, "systemid": "31F F13F-37D6-AACCB28FBC86", "hostname": "<hostname>", "version": "4.1.0", "product": "BIG-IQ", "edition": "Final", "build": "1741.0", "restframeworkversion": " ", "icontrolkey": "<removed for brevity>", "icontrolcert": "<removed for brevity>", "icontrolcertid": " ", "groupname": "<device_group_name>", "generation": 3, "lastupdatemicros": , "kind": "shared:resolver:device-groups:restdeviceresolverdevicestate", "selflink": " 9c8-ea7579a5bc53" "generation": 6, "kind": "shared:resolver:device-groups:devicegroupdevicecollectionstate", "lastupdatemicros": , "selflink": " <span style="font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 10px;"> </span> 3-32

199 Shared APIs Get a single device Gets a single device within a group. /shared/resolver/device-groups/<device_group_name>/devices/<uuid> GET N/A HTTP/ OK "uuid": "5964f b5fc-dde14d4d6cfa", "deviceuri": " "state": "ACTIVE", "address": " ", "clockskewsecondscount": -7, "systemid": "FB B8D4-3FB8-F4E56318D8C2", "hostname": "<hostname>", "version": "11.5.0", "product": "BIG-IP", "edition": "Final", "build": "971.0", "restframeworkversion": " ", "properties": "supportsrulelogging": true, "supportsiruleaction": true, "supportsfwpolicy": true "icontrolkey": "<removed for brevity>", "icontrolcert": "<removed for brevity>", "icontrolcertid": " ", "groupname": "<device_group_name>", "generation": 3, "lastupdatemicros": , "kind": "shared:resolver:device-groups:restdeviceresolverdevicestate", "selflink": " 1-b5fc-dde14d4d6cfa" BIG-IQ API Reference Guide 3-33

200 Chapter 3 Get a single device s health statistics Gets a single device's health statistics health.available -- healthy if device can be contacted health.cpu -- healthy if device CPU activity does not exceed threshold value health.memory -- healthy if available storage does not fall below threshold value health.disk -- healthy if free space available on monitored file systems ("/", "/shared", "/var", "/var/log") does not fall below threshold value health.summary -- roll up of all device health statistics values. /shared/resolver/device-groups/<device_group_name>/devices/<uuid>/stats GET N/A 3-34

201 Shared APIs HTTP/ OK "entries": "health.available": "value": 1, "description": "Device is available", "lastupdatemicros": "health.disk": "value": 1, "description": "Disk OK", "lastupdatemicros": "health.summary": "value": 1, "description": "Overall device health", "lastupdatemicros": "health.cpu": "value": 1, "description": "CPU OK", "lastupdatemicros": "health.memory": "value": 1, "description": "Memory OK", "lastupdatemicros": "generation": 7, "lastupdatemicros": , "kind": "shared:resolver:device-groups:foobar:devices:stats:restworkerstats", "selflink": " a68/stats" BIG-IQ API Reference Guide 3-35

202 Chapter 3 Add a new group Adds a new group with group validator URI /shared/resolver/device-groups POST N/A HTTP/ ACCEPT "groupname":"bigip-group", "devicesreference":"link":" "validatoruri":"/shared/resolver/groups/bigip-validator", "generation":1, "lastupdatemicros": , "kind":"shared:resolver:device-groups:devicegroupstate", "selflink":" "automanagelocalhost":true, "description":"ha Peers Group" validatoruri must be validator worker URI designed according to device resolver group validator api. Add a new device Adds a new device, response is a PENDING device, which eventually is successfully discovered (ACTIVE) or discovery fails (POST_FAILED). /shared/resolver/device-groups/<device_group_name>/devices POST N/A 3-36

203 Shared APIs "address":" ", "username" : "admin", "password" : "<password>", "properties" : "prop" : "value" "automaticallyupdateframework": "true" HTTP/ ACCEPT "uuid":"ef3cdbd4-d524-43b6-a3f3-70c d", "deviceuri":" "state":"pending", "address":" ", "groupname":"<device_group_name>", "generation":1,"lastupdatemicros":0, "kind":"shared:resolver:device-groups:restdeviceresolverdevicestate", "selflink":" b6-a3f3-70c d" BIG-IQ API Reference Guide 3-37

204 Chapter 3 Rediscover a POST_FAILED device If a discovery has failed, then a rediscovery can be attempted by PATCHing the device with a new password. Username, address, and automaticallyupdateframework are optional arguments. /shared/resolver/device-groups/<device_group_name>/devices/<uuid> POST N/A "automaticallyupdateframework": "true", "password" : "<password>", "uuid" : "22742c98-b806-46dc-b788-adc21168dad3", "stat HTTP/ ACCEPT "uuid":"ef3cdbd4-d524-43b6-a3f3-70c d", "deviceuri":" "state":"pending", "address":" ", "groupname":"<device_group_name>", "generation":1,"lastupdatemicros":0, "kind":"shared:resolver:device-groups:restdeviceresolverdevicestate", "selflink":" b6-a3f3-70c d" <span style="font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 10px;"> </span> Delete a device Deletes a device, or remove from a group. Returns the device that was deleted/removed from the group. If the device is referenced in multiple groups, it will be removed from each group. If this reference is the last then the device will be removed and undiscovered. In which case the device state will become PENDING_DELETE and eventually the device is removed. /shared/resolver/device-groups/<device_group_name>/devices DELETE 3-38

205 Shared APIs N/A HTTP/ OK "uuid": "5964f b5fc-dde14d4d6cfa", "deviceuri": " "state": "PENDING_DELETE", "address": " ", "clockskewsecondscount": -7, "systemid": "FB B8D4-3FB8-F4E56318D8C2", "hostname": "<hostname>", "version": "11.5.0", "product": "BIG-IP", "edition": "Final", "build": "971.0", "properties": "supportsrulelogging": true, "supportsiruleaction": true, "supportsfwpolicy": true "icontrolkey": "<removed for brevity>", "icontrolcert": "<removed for brevity>", "icontrolcertid": " ", "groupname": "<device_group_name>", "generation": 3, "lastupdatemicros": , "kind": "shared:resolver:device-groups:restdeviceresolverdevicestate", "selflink": " -b5fc-dde14d4d6cfa" BIG-IQ API Reference Guide 3-39

206 Chapter 3 Add an existing device to a group Puts a previously discovered device into another group. /shared/resolver/device-groups/<device_group_name>/devices POST N/A "uuid" : "d86e7246-4d85-460f-a102-c003b97c99e3", "deviceuri" : " HTTP/ OK <pre> "uuid": "5964f b5fc-dde14d4d6cfa", "deviceuri": " "state": "ACTIVE", "address": " ", "clockskewsecondscount": -7, "systemid": "FB B8D4-3FB8-F4E56318D8C2", "hostname": "<hostname>", "version": "11.5.0", "product": "BIG-IP", "edition": "Final", "build": "971.0", "restframeworkversion": " ", "properties": "supportsrulelogging": true, "supportsiruleaction": true, "supportsfwpolicy": true "icontrolkey": "<removed for brevity>", "icontrolcert": "<removed for brevity>", "icontrolcertid": " ", "groupname": "<device_group_name>", "generation": 3, "lastupdatemicros": , "kind": "shared:resolver:device-groups:restdeviceresolverdevicestate", "selflink": " -b5fc-dde14d4d6cfa" </pre> 3-40

207 Shared APIs Modifying device properties Each device has a properties attribute that can be modified through PATCHes. Properties are simple key/value pairs. Any properties specified in the body are added to the device properties. Any blank properties will be removed. /shared/resolver/device-groups/<device_group_name>/devices/<uuid> PATCH N/A "properties" : "my-property":"change-value" HTTP/ OK <pre> "uuid": "5964f b5fc-dde14d4d6cfa", "deviceuri": " "state": "ACTIVE", "address": " ", "clockskewsecondscount": -7, "systemid": "FB B8D4-3FB8-F4E56318D8C2", "hostname": "<hostname>", "version": "11.5.0", "product": "BIG-IP", "edition": "Final", "build": "971.0", "restframeworkversion": " ",</pre> <pre> "properties":"my-property":"change-value"</pre> <pre> "icontrolkey": "<removed for brevity>", "icontrolcert": "<removed for brevity>", "icontrolcertid": " ", "groupname": "<device_group_name>", "generation": 3, "lastupdatemicros": , "kind": "shared:resolver:device-groups:restdeviceresolverdevicestate", "selflink": " -b5fc-dde14d4d6cfa" </pre> BIG-IQ API Reference Guide 3-41

208 Chapter 3 Group resolver APIs The goals of the REST Group resolver are to serve as: an abstraction for collections of REST endpoints a way to group REST endpoints using a hierarchical name and a collection of opaque tags an event model for discovering membership changes in a group A group name is a semi opaque identifier following the URI path convention. A group name must be a valid URI path. An absolute REST URI can only appear once per group, but can exist under multiple group names. To simplify enumeration and naming, group names should re-use the components of worker public URI paths. Each group can have an associated locality, specified as a query parameter when requesting groups and available in the group entry PODO. The Group name scheme is: <URI path segments>/locality where: uri path - URI path segments either shared by REST resources in the group, or specific to the group name locality - an optional opaque name (or tag) for a network locality. All resources within a locality can directly address each other using absolute URIs Note The public URI naming scheme enforces a top level path that indicates whether the group or worker is ADC- or BIG-IQ system-specific. If the worker is ADC-specific, the top level path is /cm. If the worker is BIG-IQ system-specific, the top level path is /tm. Get resolver groups Returns list of groups. /shared/resolver/groups GET N/A "items":["groupname":"/mgmt/cm/cloud/devices/templates","references":["link":" ost/mgmt/cm/cloud/devices/templates/iapp"] "generation": 1, "lastupdatemicros": HTTP/ ACCEPTED 3-42

209 Shared APIs Device Resolver /shared/resolver/devices Query resolver groups Queries for a specific group entry and optional expands contents of each URI in group. /shared/resolver/groups GET $filter=groupname eq /mgmt/cm/cloud/devices/templates $expand=references HTTP/ OK "groupname":"/mgmt/cm/cloud/devices/templates","references":["link":" t/cm/cloud/devices/templates/iapp"] DELETE requires a body Device Resolver /shared/resolver/devices Create resolver groups Adds a new item to the group map. If a group does not exist with this name, it is created. Otherwise, the items in the POST request body are added to the existing group list. Workers can insert other workers into resolver groups. For example, a BIG-IQ node can populate groups per locality since it has awareness of application deployment across data centers. /shared/resolver/groups POST "items":["groupname":"/mgmt/cm/cloud/devices/templates","references":["link":" host/mgmt/cm/cloud/devices/templates/iapp"]] BIG-IQ API Reference Guide 3-43

210 Chapter 3 HTTP/ OK DELETE requires a body Device Resolver /shared/resolver/devices Delete resolver group Removes an entire group, or an entry from a specific group. /shared/resolver/groups DELETE "items":["groupname":"/mgmt/cm/cloud/devices/templates","references":["link":" ost/mgmt/cm/cloud/devices/templates/iapp"]] HTTP/ OK DELETE requires a body Device Resolver /shared/resolver/devices 3-44

211 Shared APIs Device information API This worker provides an API to get basic device properties for discovery. The properties are set at the beginning during startup of the worker. Get device information Retrieves device properties for a particular device. /shared/identified-devices/config/device-info GET BIG-IQ API Reference Guide 3-45

212 Chapter 3 "basemac": "00:50:56:01:3D:AA", "hostmac": "00:50:56:01:3D:AA", "time": , "haluuid": "423150f1-6d12-0a00-cb7b-cb2f1130bc5d", "managementaddress": " ", "physicalmemory": 4096, "platformmarketingname": "BIG-IP Virtual Edition", "platform": "Z100", "chassisserialnumber": "423150f1-6d12-0a00-cb2f1130bc5d", "cpu": "Intel(R) Xeon(R) CPU 2.67GHz", "slots": [ "volume": "HD1.1", "product": "BIG-IP", "version": "11.5.0", "build": " ", "isactive": false "volume": "HD1.2", "product": "BIG-IP", "version": "11.5.0", "build": " ", "isactive": true "license": "licenseenddatetime": " T00:00:00-08:00", "registrationkey": "B ", "activemodules": [ "GTM, VE H IPV6 Gateway Ram Cache STP DNS Express GTM, DNS LB, MAX Routing Bundle, VE DNS Rate Fallback, Unlimited DNS Licensed Objects, Unlimited DNS Rate Limit, Unlimited QPS GTM Rate Fallback, (UNLIMITED) GTM Licensed Objects, Unlimited GTM Rate, Unlimited", "GTM-DNS, RL, BIG-IP (v11.4 & later) X DNS Rate Fallback, 50 DNS Licensed Objects, 0 DNS Rate Limit, 50 QPS GTM Licensed Objects, 0 GTM Rate, 8 GTM Rate Fallback, 8 SSL, Max TPS, VE", "LTM, 5 Gbps, VE O IPV6 Gateway Rate Shaping Ram Cache 50 Mbps Compression SSL, 500 TPS Per Core APM, Limited Recycle, VE Anti-Virus Checks Base Endpoint Security Checks Firewall Checks Machine Certificate Checks Network Access Protected Workspace Secure Virtual Keyboard APM, Web Application App Tunnel Remote Desktop Routing Bundle, VE DNS Rate Fallback, Unlimited DNS Licensed Objects, Unlimited DNS Rate Limit, Unlimited QPS GTM Licensed Objects, Unlimited SSL, Max TPS, VE" "generation": 0, "lastupdatemicros": 0 "interfaces": [ "1.3", "1.2", "1.1", "mgmt" "machineid": " b061-41fc-9716-a0bd2cefe6e1", "address": " ", "hostname": "<hostname>", "version": "11.5.0", "product": "BIG-IP", "edition": "Final", "build": " ", "restframeworkversion": " ", "isclustered": false, "isvirtual": true, "generation": 0, "lastupdatemicros": 0, "kind": "shared:resolver:device-groups:deviceinfostate", "selflink": " 3-46

213 Shared APIs BIG-IQ API Reference Guide 3-47

214 Chapter 3 Statistics information and metadata API This API is for descriptive information/metadata about statistics that are collected throughout the system. All statistics present in /stats and -stats helpers should be described here. 3-48

215 Shared APIs Create a statistics information item Creates a statistics information item. /shared/stats-information POST Request Body "name": "shared:somekind:thestate-throughput", "displayname": "Throughput in Mbps", "category": [ "cat1", "cat2" "unit": "Megabits", "timeunit": "second" "name": "shared:somekind:thestate-throughput", "displayname": "Throughput in Mbps", "category": [ "cat1", "cat2" "unit": "Megabits", "timeunit": "second", "generation": 1, "lastupdatemicros": , "kind": "shared:stats-information:statinformationstate", "selflink": " HTTP/ Bad Request There are two forms of the name: kind-stat or stat. Stats Example Stats /stats -stats BIG-IQ API Reference Guide 3-49

216 Chapter 3 Retrieve all statistics information items Retrieves the entire collection of statistics information/metadata items. /shared/stats-information GET Request Body 3-50

217 Shared APIs "items": [ "name": "shared:somekind:thestate-throughput", "displayname": "Throughput in Mbps", "category": [ "cat1", "cat2" "unit": "Megabits", "timeunit": "second", "generation": 1, "lastupdatemicros": , "kind": "shared:stats-information:statinformationstate", "selflink": " "name": "cur_conns", "displayname": "Current Connection Count", "category": [ "ltm" "unit": "connections", "generation": 1, "lastupdatemicros": , "kind": "shared:stats-information:statinformationstate", "selflink": " "name": "max_conns", "displayname": "Maximum Connection Count", "category": [ "ltm" "unit": "connections", "generation": 1, "lastupdatemicros": , "kind": "shared:stats-information:statinformationstate", "selflink": " "name": "pkts_in", "displayname": "Incoming Packet Count", "category": [ "ltm" "unit": "packets", "generation": 1, "lastupdatemicros": , "kind": "shared:stats-information:statinformationstate", "selflink": " "name": "pkts_out", "displayname": "Outgoing Packet Count", "category": [ "ltm" "unit": "packets", "generation": 1, "lastupdatemicros": , "kind": "shared:stats-information:statinformationstate", "selflink": " "name": "tot_conns", "displayname": "Total Connection Count", "category": [ "ltm" "unit": "connections", "generation": 1, "lastupdatemicros": , "kind": "shared:stats-information:statinformationstate", "selflink": " "generation": 7, "kind": "shared:stats-information:statinformationcollectionstate", "lastupdatemicros": , "selflink": " BIG-IQ API Reference Guide 3-51

218 Chapter 3 HTTP/ Bad Request There are two forms of the name: kind-stat or stat. Stats Example Stats /stats -stats 3-52

219 Shared APIs Change a portion of a statistics information item Changes a portion of a statistics information item. /shared/stats-information/shared:somekind:thestate-throughput PATCH Request Body "displayname": "Throughput in Megabits per second" "name": "shared:somekind:thestate-throughput", "displayname": "Throughput in Megabits per second", "category": [ "cat1", "cat2" "unit": "Megabits", "timeunit": "second", "generation": 1, "lastupdatemicros": , "kind": "shared:stats-information:statinformationstate", "selflink": " HTTP/ Bad Request There are two forms of the name: kind-stat or stat. Stats Example Stats /stats -stats Replace a statistics information item Replaces a statistics information item. /shared/stats-information/shared:somekind:thestate-throughput PUT BIG-IQ API Reference Guide 3-53

220 Chapter 3 Request Body "name": "shared:somekind:thestate-throughput", "displayname": "Throughput in Mbps - changed", "category": [ "cat1", "cat2", "cat3" "unit": "Megabits - changed"", "timeunit": "second - changed"" "name": "shared:somekind:thestate-throughput", "displayname": "Throughput in Mbps - changed", "category": [ "cat1", "cat2", "cat3" "unit": "Megabits - changed"", "timeunit": "second - changed"" "generation": 3, "lastupdatemicros": , "kind": "shared:stats-information:statinformationstate", "selflink": " HTTP/ Bad Request There are two forms of the name: kind-stat or stat. Stats Example Stats /stats -stats Delete a statistics information item Deletes a statistics information item. /shared/stats-information/shared:somekind:thestate-throughput DELETE Request Body 3-54

221 Shared APIs HTTP/ Bad Request There are two forms of the name: kind-stat or stat. Stats Example Stats /stats -stats BIG-IQ API Reference Guide 3-55

222 Chapter 3 Licensing worker APIs The licensing worker provides the ability to read the current state of the license on the local system. The license information is refreshed once per minute, or upon calling GET. Get license Retrieves the current license for the local system. /tm/shared/licensing/registration GET N/A 3-56

223 Shared APIs (for BIG-IQ Cloud systems) <span style="font-family: Verdana, Arial, Helvetica, sans-serif; color: #000000; font-size: x-small;"><span style="white-space: normal;"> "vendor":"f5 Networks, Inc.", "licenseddatetime":" t00:00:00-08:00", "licensedversion":"4.0.0", "evaluationstartdatetime":" t00:00:00-08:00", "evaluationenddatetime":" t00:00:00-07:00", "licenseenddatetime":" t00:00:00-07:00", "licensestartdatetime":" t00:00:00-08:00", "registrationkey":"h ", "dossier":" bd135e9b0d479a84f7fe1acc1286c57cd91225fa98d12e1fa2e1a70d0a e5a1058fb c4e79c8e7cb8437c8c0dafde5b2001b f9a50f84ee60f8097ff8124d21aa5ca220e154d584cadff4d0a9 e541fe61c675bbf0ccd0f384f377c ace9ccba d848b4ddea98e0a99b321042c8d8f e3e5b7bac ebd683e961eb86a45ec150cf2bccd548ec69eb3f49990f887901d8a2cc e29d f5b7f3838e ab81b71af8b87c58b7f5f9c790c77d276ce535cea89", "authorization":"49efa6bfd2dfd08abc87c3aaacdca9cb4a8afe58ee1f992ef8aedeb05478a9ecb21fe664a28b9985a15 b437b0eee9633a8d71d9fbab2d064b c9df376eb d3f03712bf89b6b6524ccd0322e7dd68 5af7630b888bfb6ef9caf c508779e4d8dc8333a11eeded2b3866e2d500415cf268eb2e0d2423e7e899eca7f3 b73ff75b01bad8c108856a7477b46ebbe4e2046efa5a989afcc3eee2f24c6c474d9a5feacacea9f476e416f4ad d604b6bc0b1f8e71aa7f745d2d12985bc21ce1705c5ccf163604e a0a467f75b7a053edb25c6c2db016b77 bbb146e872f114a718e9ff a7ee6b379c7dd55715fb", "usage":"f5 Internal Product Development", "platformid":"z100", "authvers":"5b", "servicecheckdatetime":" t00:00:00-08:00", "servicestatus":"as of this system has an active service contract.", "exclusiveplatform":[ "Z100", "Z100H", "Z100K", "Z100x" "activemodules":[ "BIG-IQ, AFM, VE, 50 Devices U BIG-IQ, Cloud, VE, Maximum Nodes BIG-IQ, Maximum Devices" "optionalmodules":[ "BIG-IQ, Additional AFM Devices", "BIG-IQ, Cloud, VE, 1000 Nodes", "BIG-IQ, Cloud, VE, Nodes", "BIG-IQ, Cloud, VE, 5000 Nodes" "featureflags":[ "featurename":"biq_firewall_devices", "featurevalue":"50" "featurename":"perf_ve_throughput_mbps", "featurevalue":"unlimited" "featurename":"mod_biq", "featurevalue":"enabled" "featurename":"biq_num_devices", "featurevalue":"unlimited" "featurename":"biq_cloud_objects", "featurevalue":"unlimited" "expiresindays":"25.6", "expiresindaysmessage":"license expires in 25 days, 13 hours.", "generation":0, "lastupdatemicros":0 </span></span> BIG-IQ API Reference Guide 3-57

224 Chapter 3 (for BIG-IP systems) <span style="font-family: Verdana, Arial, Helvetica, sans-serif; color: #000000; font-size: x-small;"><span style="white-space: normal;"> "vendor":"f5 Networks, Inc.", "licenseddatetime":" t00:00:00-07:00", "licensedversion":"11.5.0", "licenseenddatetime":" t00:00:00-07:00", "licensestartdatetime":" t00:00:00-07:00", "registrationkey":"l ", "dossier":"01d049925ce16451e8deae5f569aebce7a1286c57cd91225fa98d12e1fa2e1a70d0a165dd158f63ee b041 b778a c8c0dafde5b2001b f9a50f84ee60f8097ff8124d21aa5ca220e154d584cadff4d0a9e541fe61c675bbf0 ccd0f384f377c ace9ccba d848b4ddea98e0a99b321042c8d8f e3e5b7bac ebd683 e961eb86f c f78f da2ce884dbff318aed0a8ba3ecc10feb8a2a64889f5b7f3838e ab81b 71af8b87c58b7f5f9c790c77d276ce535cea89", "authorization":"12da27c26c1bbaa41ba745ecda5b27b47abf4b6bc42b54fa3f513f0de34ccb5ce50d7c c71e47f89 da886878c51f6ae5d627259cc935ccdd1452bd6b9a3be521abffad36971d70b de6039b4d0c1593e7e1bf47992b0d2e 786d0a65f79397d36a38469d4f9326b81b49bbda2defff8b d3755aaf dee4a2a835efe0d8d46f fa8200 a5df43531c37671e18754f8ca38f0c23e7a2e229eda e3e96909c26529ef722ea83ec2525d40ef23d0b65121c6c048b4 7f24b61d db63930cd6222d d7b67cb703d2c38c80f096f9d2a8fc ef662394ae61e67ccb0088b4e d8498acd1e32", "usage":"f5 Internal Product Development", "platformid":"z100", "authvers":"5b", "servicecheckdatetime":" t00:00:00-07:00", "servicestatus":"as of there is no active service contract. This may inhibit your ability to upgrade your software.", "exclusiveplatform":[ "Z100", "Z100H", "Z100K", "Z100x" "activemodules":[ "GTM, VE D IPV6 Gateway Ram Cache STP DNS Express GTM, DNS LB, MAX Routing Bundle, VE DNS Rate Fallback, Unlimited DNS Licensed Objects, Unlimited DNS Rate Limit, Unlimited QPS GTM Rate Fallback, (UNLIMITED) GTM Licensed Objects, Unlimited GTM Rate, Unlimited", "GTM-DNS, RL, BIG-IP (v11.4 & later) O DNS Rate Fallback, 50 DNS Licensed Objects, 0 DNS Rate Limit, 50 QPS GTM Rate Fallback, 25 GTM Licensed Objects, 0 GTM Rate, 25", "PERF TEST ONLY-VE UNLIMITED (DEV ONLY) T IPV6 Gateway Rate Shaping Ram Cache MSM Client Authentication WBA SSL, Unlimited APM, Limited Compression, Unlimited ASM, VE PSM, VE WBA, VE Recycle, VE AFM, VE WOM, VE 500 Mbps Compression Anti-Virus Checks Base Endpoint Security Checks Firewall Checks Machine Certificate Checks Network Access Protected Workspace Secure Virtual Keyboard APM, Web Application App Tunnel Remote Desktop Max Compression, VE SSL, Max TPS, VE AAM, Upgrade from WAM, (v11.4 & later) Routing Bundle, VE DNS Rate Fallback, Unlimited DNS Licensed Objects, Unlimited DNS Rate Limit, Unlimited QPS" "optionalmodules":[ "Acceleration Manager, BIG-IP", "APM, Base, VE", "APM, Max CCU, VE", "App Mode (TMSH Only, No Root/Bash)", "DNS and GTM (1K QPS), VE", "DNS and GTM (5K QPS), VE", "DNS and GTM (Unlimited), VE", "DNS Services", "DNSSEC", "EA Features", "External Interface and Network HSM", "IPI Subscription, 1Yr, VE", "IPI Subscription, 3Yr, VE", "Routing Bundle, VE", "SDN Services", "SSL, Forward Proxy" "featureflags":[ "featurename":"perf_ssl_mbps", "featurevalue":"4000"...truncated for brevity "expiresindays":"28.5", "expiresindaysmessage":"license expires in 28 days, 11 hours.", "generation":0, "lastupdatemicros":0, "kind":"tm:shared:licensing:registration:licensestate", "selflink":" </span></span> 3-58

225 Shared APIs In case of error the request will fail, and the client provided RestRequestCompletion.failed() method will be invoked, which contains the request as well as an exception. The exception contains information about the following failure cases: - locating and loading of license file has failed - parsing license failed Licenses are read-only, and only accessible to users who have the role of BIG-IP administrator. None Install license The licensing worker provides the ability to install a license on the local system. Installs the specified license on the local BIG-IP system. /tm/shared/licensing/registration PUT "licensetext" : "<LICENSE_TEXT>" BIG-IQ API Reference Guide 3-59

226 Chapter 3 (for BIG-IP systems) <pre> "vendor":"f5 Networks, Inc.", "licenseddatetime":" t00:00:00-08:00", "licensedversion":"4.0.0", "evaluationstartdatetime":" t00:00:00-08:00", "evaluationenddatetime":" t00:00:00-07:00", "licenseenddatetime":" t00:00:00-07:00", "licensestartdatetime":" t00:00:00-08:00", "registrationkey":"h ", "dossier":" bd135e9b0d479a84f7fe1acc1286c57cd91225fa98d12e1fa2e1a70d0a e5a1058fb c4e79c8e7cb8437c8c0dafde5b2001b f9a50f84ee60f8097ff8124d21aa5ca220e154d584cadff4d0a9e5 41fe61c675bbf0ccd0f384f377c ace9ccba d848b4ddea98e0a99b321042c8d8f e3e 5b7bac ebd683e961eb86a45ec150cf2bccd548ec69eb3f49990f887901d8a2cc e29d f5b7f3838e ab81b71af8b87c58b7f5f9c790c77d276ce535cea89", "authorization":"49efa6bfd2dfd08abc87c3aaacdca9cb4a8afe58ee1f992ef8aedeb05478a9ecb21fe664a28b9985a15b 437b0eee9633a8d71d9fbab2d064b c9df376eb d3f03712bf89b6b6524ccd0322e7dd685a f7630b888bfb6ef9caf c508779e4d8dc8333a11eeded2b3866e2d500415cf268eb2e0d2423e7e899eca7f3b73 ff75b01bad8c108856a7477b46ebbe4e2046efa5a989afcc3eee2f24c6c474d9a5feacacea9f476e416f4ad d60 4b6bc0b1f8e71aa7f745d2d12985bc21ce1705c5ccf163604e a0a467f75b7a053edb25c6c2db016b77bbb1 46e872f114a718e9ff a7ee6b379c7dd55715fb", "usage":"f5 Internal Product Development", "platformid":"z100", "authvers":"5b", "servicecheckdatetime":" t00:00:00-08:00", "servicestatus":"as of this system has an active service contract.", "exclusiveplatform":[ "Z100", "Z100H", "Z100K", "Z100x" "activemodules":[ "BIG-IQ, AFM, VE, 50 Devices U BIG-IQ, Cloud, VE, Maximum Nodes BIG-IQ, Maximum Devices" "optionalmodules":[ "BIG-IQ, Additional AFM Devices", "BIG-IQ, Cloud, VE, 1000 Nodes", "BIG-IQ, Cloud, VE, Nodes", "BIG-IQ, Cloud, VE, 5000 Nodes" "featureflags":[ "featurename":"biq_firewall_devices", "featurevalue":"50" "featurename":"perf_ve_throughput_mbps", "featurevalue":"unlimited" "featurename":"mod_biq", "featurevalue":"enabled" "featurename":"biq_num_devices", "featurevalue":"unlimited" "featurename":"biq_cloud_objects", "featurevalue":"unlimited" "expiresindays":"25.6", "expiresindaysmessage":"license expires in 25 days, 13 hours.", "generation":0, "lastupdatemicros":0 3-60

227 Shared APIs (for BIG-IQ Cloud systems) <pre> "vendor":"f5 Networks, Inc.", "licenseddatetime":" t00:00:00-08:00", "licensedversion":"4.0.0", "evaluationstartdatetime":" t00:00:00-08:00", "evaluationenddatetime":" t00:00:00-07:00", "licenseenddatetime":" t00:00:00-07:00", "licensestartdatetime":" t00:00:00-08:00", "registrationkey":"h ", "dossier":" bd135e9b0d479a84f7fe1acc1286c57cd91225fa98d12e1fa2e1a70d0a e5a1058fb719973c4e79c 8e7cb8437c8c0dafde5b2001b f9a50f84ee60f8097ff8124d21aa5ca220e154d584cadff4d0a9e541fe61c675bbf0ccd0f38 4f377c ace9ccba d848b4ddea98e0a99b321042c8d8f e3e5b7bac ebd683e961eb86 a45ec150cf2bccd548ec69eb3f49990f887901d8a2cc e29d f5b7f3838e ab81b71af8b87c5 8b7f5f9c790c77d276ce535cea89", "authorization":"49efa6bfd2dfd08abc87c3aaacdca9cb4a8afe58ee1f992ef8aedeb05478a9ecb21fe664a28b9985a15b437b0eee9 633a8d71d9fbab2d064b c9df376eb d3f03712bf89b6b6524ccd0322e7dd685af7630b888bfb6ef9caf c508779e4d8dc8333a11eeded2b3866e2d500415cf268eb2e0d2423e7e899eca7f3b73ff75b01bad8c108856a7477b46eb be4e2046efa5a989afcc3eee2f24c6c474d9a5feacacea9f476e416f4ad d604b6bc0b1f8e71aa7f745d2d12985bc21ce1705 c5ccf163604e a0a467f75b7a053edb25c6c2db016b77bbb146e872f114a718e9ff a7ee6b379c7dd55715fb", "usage":"f5 Internal Product Development", "platformid":"z100", "authvers":"5b", "servicecheckdatetime":" t00:00:00-08:00", "servicestatus":"as of this system has an active service contract.", "exclusiveplatform":[ "Z100", "Z100H", "Z100K", "Z100x" "activemodules":[ "BIG-IQ, AFM, VE, 50 Devices U BIG-IQ, Cloud, VE, Maximum Nodes BIG-IQ, Maximum Devices" "optionalmodules":[ "BIG-IQ, Additional AFM Devices", "BIG-IQ, Cloud, VE, 1000 Nodes", "BIG-IQ, Cloud, VE, Nodes", "BIG-IQ, Cloud, VE, 5000 Nodes" "featureflags":[ "featurename":"biq_firewall_devices", "featurevalue":"50" "featurename":"perf_ve_throughput_mbps", "featurevalue":"unlimited" "featurename":"mod_biq", "featurevalue":"enabled" "featurename":"biq_num_devices", "featurevalue":"unlimited" "featurename":"biq_cloud_objects", "featurevalue":"unlimited" "expiresindays":"25.6", "expiresindaysmessage":"license expires in 25 days, 13 hours.", "generation":0, "lastupdatemicros":0 </pre> BIG-IQ API Reference Guide 3-61

228 Chapter 3 In case of error the request fails, and the client provided RestRequestCompletion.failed() is invoked, which contains the request as well as an exception. The exception contains information about the following failure cases: - license validation failed - installation of license has failed Licenses are read-only. None Revoke license Removes a license from the local BIG-IP system. /tm/shared/licensing/registration DELETE N/A In case of error, the request will fail, and the client provided RestRequestCompletion.failed() will be invoked, which contains the request as well as an exception. Licenses are read-only. None User authentication API The user authentication API allows clients to authenticate a username and password combination. The user can also obtain a token by specifying needstoken = True. This token can be used in the HTTP header instead of a username and password for repeated requests. 3-62

229 Shared APIs Verify authentication Validate the username and password combination. /mgmt/shared/authn/login POST N/A "username": "player1", "password": "player1spassword", "needstoken":true HTTP/ OK "username": "player1", "password": "player1password", "needstoken": true, "token": "uuid": "b76d8a f6d-bf ce619", "name": "06941EAC72A8BC4EE068F9C2F9DF9CB1A3E07BFE", "token": "06941EAC72A8BC4EE068F9C2F9DF9CB1A3E07BFE", "user": "link": " "timeout": 1200, "starttime": " T17:08: ", "address": " ", "partition": "[All]", "generation": 1, "lastupdatemicros": , "expirationmicros": , "kind": "shared:authz:tokens:authtokenitemstate", "selflink": " "generation": 0, "lastupdatemicros": 0 The parameter needstoken is completely optional and should only be specified if the client wishes to use the token for repeated requests. Stats Example Stats /stats -stats BIG-IQ API Reference Guide 3-63

230 Chapter 3 Authentication token worker API The authentication token worker manages authentication tokens (cookies) that allow password-less interaction with the REST framework. The authentication tokens are issued for a specific life-time. They are not limited to the default 20 minute life-span of the Apache PAM module authentication mechanism. Create an authentication token Creates an authentication token. /mgmt/shared/authz/tokens POST N/A "user": "link": " "timeout": 1200, "address": " ", "uuid": "962434dd-febe-475c-b268-a8f6ed057e67", "name": "962434DDFEBE475CB268A8F6ED057E DD", "user": "link": " "timeout": 1200, "starttime": " T09:50: ", "address": " ", "partition": "[All]", "generation": 1, "lastupdatemicros": , "expirationmicros": , "kind": "shared:authz:tokens:authtokenitemstate", "selflink": "

231 Shared APIs Get all auth-tokens Gets all the authentication tokens. /mgmt/shared/authz/tokens GET N/A "items": [ "uuid": "962434dd-febe-475c-b268-a8f6ed057e67", "name": "962434DDFEBE475CB268A8F6ED057E DD", "user": "link": " "timeout": 1200, "starttime": " T09:50: ", "address": " ", "partition": "[All]", "generation": 1, "lastupdatemicros": , "expirationmicros": , "kind": "shared:authz:tokens:authtokenitemstate", "selflink": " "generation": 1, "kind": "shared:authz:tokens:authtokencollectionstate", "lastupdatemicros": , "selflink": " Get auth-tokens based on UUID Gets an the authentication token based on UUID. /mgmt/shared/authz/tokens/uuid GET BIG-IQ API Reference Guide 3-65

232 Chapter 3 None None "uuid": "962434dd-febe-475c-b268-a8f6ed057e67", "name": "962434DDFEBE475CB268A8F6ED057E DD", "user": "link": " "timeout": 1200, "starttime": " T09:50: ", "address": " ", "partition": "[All]", "generation": 1, "lastupdatemicros": , "expirationmicros": , "kind": "shared:authz:tokens:authtokenitemstate", "selflink": "

233 Shared APIs Delete all auth-tokens Deletes all the authentication tokens. /mgmt/shared/authz/tokens DELETE None None "result": "EQUAL", "itemsadded": [ "percollectionitemsadded": "itemsdeleted": [ "percollectionitemsdeleted": "itemschanged": [ "itemschangedfrom": [ "percollectionitemschanged": "generation": 0, "lastupdatemicros": 0 Delete auth-tokens based on UUID Deletes an authentication token based on UUID. /mgmt/shared/authz/tokens DELETE None "uuid": "962434dd-febe-475c-b268-a8f6ed057e67", "kind": "shared:authz:tokens:authtokenitemstate", "selflink": " BIG-IQ API Reference Guide 3-67

234 Chapter 3 "uuid": "962434dd-febe-475c-b268-a8f6ed057e67", "name": "962434DDFEBE475CB268A8F6ED057E DD", "timeout": 0, "generation": 0, "lastupdatemicros": 0, "kind": "shared:authz:tokens:authtokenitemstate", "selflink": " Delete auth-tokens based on state (POJO) Deletes an authentication token based on an AuthTokenItemState. /mgmt/shared/authz/tokens.uuid DELETE None None "uuid": "962434dd-febe-475c-b268-a8f6ed057e67", "name": "D7FDEFA5E8B584F4AB4D305BCF0736F05052E382", "user": "link": " "timeout": 1200, "starttime": " T10:52: ", "address": " ", "partition": "[All]", "generation": 1, "lastupdatemicros": , "expirationmicros": , "kind": "shared:authz:tokens:authtokenitemstate", "selflink": "

235 Shared APIs BIG-IQ API Reference Guide 3-69

236 Chapter 3 User authorization APIs The User Authorization API allows administrators to manage users on the system, including adding, removing, updating, and retrieving user information. Get all users Get the complete set of users on the local system. /mgmt/shared/authz/users GET N/A 3-70

237 Shared APIs HTTP/ OK "items": [ "name": "admin", "displayname": "Admin User", "encryptedpassword": "...", "generation": 1, "lastupdatemicros": , "kind": "shared:authz:users:usersworkerstate", "selflink": " "name": "my_user", "displayname": "my user display name", "encryptedpassword": "...", "generation": 1, "lastupdatemicros": , "kind": "shared:authz:users:usersworkerstate", "selflink": " "name": "root", "displayname": "root", "generation": 1, "lastupdatemicros": , "kind": "shared:authz:users:usersworkerstate", "selflink": " "generation": 3, "kind": "shared:authz:users:userscollectionstate", "lastupdatemicros": , "selflink": " BIG-IQ API Reference Guide 3-71

238 Chapter 3 Get single user Get the description of a single local user. /mgmt/shared/authz/users/[username] GET N/A HTTP/ OK "name": "administrator", "displayname": "Administrator Account", "encryptedpassword": "..." The response contains the encrypted (hashed) value of the user's password, even if the user was created by specifying an unencrypted password. 3-72

239 Shared APIs Create user Creates a new user on the system. /mgmt/shared/authz/users POST N/A "name": "administrator", "password": "root", "displayname": "Administrator Account" HTTP/ OK By default, a user will have no access to any resources on a system. The user must be added to system roles. Update user Updates a user on the system. /mgmt/shared/authz/users/[username] PUT N/A "name":"my_user", "displayname":"my new display name", "password":"mynewpassword", "generation":1 HTTP/ OK "name": "my_user", "displayname": "my new display name", "encryptedpassword": "...", "generation": 2, "lastupdatemicros": , "kind": "shared:authz:users:usersworkerstate", "selflink": " BIG-IQ API Reference Guide 3-73

240 Chapter 3 At this time, the name field is required and cannot be updated. The password and the displayname field are optional, and will not be changed if left blank. Delete user Deletes a user from the system. /mgmt/shared/authz/user/[username] DELETE N/A HTTP/ OK 3-74

241 Shared APIs Authorization roles APIs This API can be used to manage roles and the users within the roles. Each role has a name and a set of users that are assigned to the role. Each role also has a set of URIs to which the role can be granted access, based on the access type (that is, read, write, delete, all). There is one built-in role, the administrator, which can be given access to every resource on the local system. GET on the roles collection returns the expanded role items. Get all roles Retrieves the roles that have been configured on the local system. /mgmt/shared/authz/roles GET N/A BIG-IQ API Reference Guide 3-75

242 Chapter 3 HTTP/ OK "items": [ "name": "Administrator", "userreferences": [ "link": " "link": " "resources": [ "resourcemask": "*", "restmethod": "GET" "resourcemask": "*", "restmethod": "POST" "resourcemask": "*", "restmethod": "PUT" "resourcemask": "*", "restmethod": "DELETE" "resourcemask": "*", "restmethod": "PATCH" "generation": 2, "lastupdatemicros": , "kind": "shared:authz:roles:rolesworkerstate", "selflink": " "name": "my_users_admin_role", "userreferences": [ "link": " "link": " "resources": [ "resourcemask": "*", "restmethod": "GET" "resourcemask": "*", "restmethod": "POST" "resourcemask": "*", "restmethod": "PUT" "resourcemask": "*", "restmethod": "DELETE" "resourcemask": "*", "restmethod": "PATCH" "resourcegroupreferences":[ "link":" "generation": 1, "lastupdatemicros": , "kind": "shared:authz:roles:rolesworkerstate", "selflink": " "generation": 2, "kind": "shared:authz:roles:rolescollectionstate", "lastupdatemicros": , "selflink": " 3-76

243 Shared APIs Get role Retrieves the roles that have been configured on the local system. /mgmt/shared/authz/roles/[rolename] GET N/A BIG-IQ API Reference Guide 3-77

244 Chapter 3 HTTP/ OK "name": "my_users_admin_role", "userreferences": [ "link": " "link": " "resources": [ "resourcemask": "mgmt/shared/authz/users/*", "restmethod": "GET" "resourcemask": "mgmt/shared/authz/users/*", "restmethod": "PUT" "resourcemask": "mgmt/shared/authz/users/*", "restmethod": "POST" "resourcemask": "mgmt/shared/authz/users/*", "restmethod": "DELETE" "generation": 1, "lastupdatemicros": , "kind": "shared:authz:roles:rolesworkerstate", "selflink": " 3-78

245 Shared APIs Create new role Creates a new role on the system. /mgmt/shared/authz/roles POST N/A "name": "Administrator", "userreferences": [ "link": " "link": " "resources": [ "resourcemask": "*", "restmethod": "GET" "resourcemask": "*", "restmethod": "POST" "resourcemask": "*", "restmethod": "PUT" "resourcemask": "*", "restmethod": "DELETE" "resourcemask": "*", "restmethod": "PATCH" "generation": 2, "lastupdatemicros": , "kind": "shared:authz:roles:rolesworkerstate", "selflink": " BIG-IQ API Reference Guide 3-79

246 Chapter 3 HTTP/ OK "name": "my_users_admin_role", "userreferences": [ "link": " "link": " "resources": [ "resourcemask": "mgmt/shared/authz/users/*", "restmethod": "GET" "resourcemask": "mgmt/shared/authz/users/*", "restmethod": "PUT" "resourcemask": "mgmt/shared/authz/users/*", "restmethod": "POST" "resourcemask": "mgmt/shared/authz/users/*", "restmethod": "DELETE" "generation": 1, "lastupdatemicros": , "kind": "shared:authz:roles:rolesworkerstate", "selflink": " 3-80

247 Shared APIs Update a role Updates an existing role on the system. /mgmt/shared/authz/roles/<role_name> PUT N/A "name": "my_users_admin_role", "userreferences": [ "link": " "resources": [ "resourcemask": "mgmt/shared/authz/users/*", "restmethod": "GET" "generation": 1 HTTP/ OK "name": "my_users_admin_role", "userreferences": [ "link": " "resources": [ "resourcemask": "mgmt/shared/authz/users/*", "restmethod": "GET" "generation": 2, "lastupdatemicros": 0 BIG-IQ API Reference Guide 3-81

248 Chapter 3 Delete role Removes the specified role. /mgmt/shared/authz/roles/<rolename> DELETE N/A HTTP/ OK 3-82

249 Shared APIs Authorization roles resource groups APIs Get all resource groups This API makes it possible to create groups of resources to be associated with a role. Gets all of the groups of resources. /shared/authz/roles/resource-groups GET N/A BIG-IQ API Reference Guide 3-83

250 Chapter 3 HTTP/ OK "items": [ "id": "35859a24-606c-4970-bf63-dd1c194f2ac2", "name": "user editor", "resources": [ "resourcemask": "/mgmt/shared/authz/users", "restmethod": "POST" "resourcemask": "/mgmt/shared/authz/users", "restmethod": "DELETE" "resourcemask": "/mgmt/shared/authz/users", "restmethod": "PUT" "generation": 2, "lastupdatemicros": , "kind": "shared:authz:roles:resource-groups:roleresourcegroupstate", "selflink": " c2" "generation": 2, "kind": "shared:authz:roles:resource-groups:roleresourcegroupcollection", "lastupdatemicros": , "selflink": " 3-84

251 Shared APIs Create a role resource group Creates a group of role resources. /shared/authz/roles/resource-groups POST N/A Request Body "name": "user creator", "resources": [ "resourcemask": "/mgmt/shared/authz/users", "restmethod": "POST" ] HTTP/ OK "id": "35859a24-606c-4970-bf63-dd1c194f2ac2", "name": "user creator", "resources": [ "resourcemask": "/mgmt/shared/authz/users", "restmethod": "POST" "generation": 1, "lastupdatemicros": , "kind": "shared:authz:roles:resource-groups:roleresourcegroupstate", "selflink": " c2" BIG-IQ API Reference Guide 3-85

252 Chapter 3 Modify a role resource group Changes a group of role resources. /shared/authz/roles/resource-groups PUT N/A Request Body "id": "35859a24-606c-4970-bf63-dd1c194f2ac2", "name": "user editor", "resources": [ "resourcemask": "/mgmt/shared/authz/users", "restmethod": "POST" "resourcemask": "/mgmt/shared/authz/users", "restmethod": "DELETE" "resourcemask": "/mgmt/shared/authz/users", "restmethod": "PUT" "generation":

253 Shared APIs HTTP/ OK "id": "35859a24-606c-4970-bf63-dd1c194f2ac2", "name": "user editor", "resources": [ "resourcemask": "/mgmt/shared/authz/users", "restmethod": "POST" "resourcemask": "/mgmt/shared/authz/users", "restmethod": "DELETE" "resourcemask": "/mgmt/shared/authz/users", "restmethod": "PUT" "generation": 2, "lastupdatemicros": , "kind": "shared:authz:roles:resource-groups:roleresourcegroupstate", "selflink": " c2" BIG-IQ API Reference Guide 3-87

254 Chapter 3 Remove a group of resources Removes the group of resources. /shared/authz/roles/resource-groups/[uuid] DELETE N/A Request Body Licensing activation APIs These APIs are used to activate F5 licenses by interacting with the F5 license activation server. It can also install the activated license on the local device. There are two work flows for the licensing activation API; one for automatic activation and the other for manual activation. In this context, automatic refers to scenarios in which the BIG-IQ system has Internet access to the F5 license activation server. The manual workflow relies on less direct access (a thumb drive, for example). 3-88

255 Shared APIs Automatic activation The API workflow for automatic activation uses the following sequence. 1. Post an automatic base key and add-on keys (or if using as a proxy, post the base key and a dossier). 2. Check for automatic activation status and get EULA. 3. Post EULA text. 4. Check for automatic activation status and get license. 5. Install license. Note When you use the automatic method to re-activate a license, you do not perform steps 2 or 3. Post an automatic base key and add-on keys Data Parameters This is the first step in requesting an automatic license request. The first time you send this verb and data parameter combination, you either get a EULA to acknowledge, or an error. /tm/shared/licensing/activation POST "baseregkey" : "XXXXX-XXXXX-XXXXX-XXXX-XXXXXXX", "addonkeys" : [ "XXXXXXX-XXXXXXX", "YYYYYYYY-YYYYYYY" "isautomaticactivation": "true" OR "baseregkey" : "XXXXX-XXXXX-XXXXX-XXXX-XXXXXXX", "dossier" : "<DOSSIER_TEXT_FROM_MANAGED_DEVICE>", "isautomaticactivation": "true" Request Body Response 1: HTTP/ OK "status" : "LICENSING_ACTIVATION_IN_PROGRESS" BIG-IQ API Reference Guide 3-89

256 Chapter 3 This call returns the EULA if the EULA needs to be accepted before licensing. License /tm/shared/licensing/registration Check for automatic activation status and get EULA Checks for the status of an automatic activation request. If you have not yet posted the EULA acceptance, you will get the EULA acceptance text. /tm/shared/licensing/activation GET Data Parameters Request Body 3-90

257 Shared APIs Response 1: HTTP/ OK "status" : "LICENSING_ACTIVATION_IN_PROGRESS", Response 2: HTTP/ OK "status" : "LICENSING_COMPLETE", "licensetext" : "<LICENSE_TEXT>" Response 3: HTTP/ OK "status" : "LICENSING_FAILED", "errortext":"..." Response 4: HTTP/ OK "status" : "NEED_EULA_ACCEPT", "eulatext" : "<EULA_TEXT>" This call returns the EULA if the EULA needs to be accepted before licensing. License /tm/shared/licensing/registration BIG-IQ API Reference Guide 3-91

258 Chapter 3 Post EULA text Once you receive the EULA text to acknowledge, include the text in the data parameter to trigger the license activation. This sends acceptance of the EULA that was returned in response to the activation request. /tm/shared/licensing/activation POST "baseregkey" : "XXXXX-XXXXX-XXXXX-XXXX-XXXXXXX", "addonkeys" : [ "XXXXXXX-XXXXXXX", "YYYYYYYY-YYYYYYY" "eulatext" : "<EULA_TEXT>", "isautomaticactivation": "true" Request Body HTTP/ OK "status" : "LICENSING_ACTIVATION_IN_PROGRESS" Check for automatic activation status and get license After you have accepted the EULA, request activation status and get a license. /tm/shared/licensing/activation POST Request Body 3-92

259 Shared APIs Response 1: HTTP/ OK "status" : "LICENSING_ACTIVATION_IN_PROGRESS", Response 2: HTTP/ OK "status" : "LICENSING_COMPLETE", "licensetext" : "<LICENSE_TEXT>" Response 4: HTTP/ OK "status" : "LICENSING_FAILED", "errortext":"..." This call returns the EULA if the EULA needs to be accepted before licensing. License /tm/shared/licensing/registration BIG-IQ API Reference Guide 3-93

260 Chapter 3 Install license Installs the license obtained from the activate server web page. /tm/shared/licensing/activation PUT "licensetext" : "<LICENSE_TEXT>" Request Body HTTP/ OK LicenseState object Manual activation method The API workflow for manual activation uses the following sequence. 1. Post manual base key and add-on keys. 2. Check for status and get dossier. 3. Install license. 3-94

261 Shared APIs Post manual base key and add-on keys Use this verb and data parameter combination to request a manual license activation. You will receive a dossier to send to the licensing activate server. /tm/shared/licensing/activation POST "baseregkey" : "XXXXX-XXXXX-XXXXX-XXXX-XXXXXXX", "addonkeys" : [ "XXXXXXX-XXXXXXX", "YYYYYYYY-YYYYYYY" "automaticactivation": "false" Request Body HTTP/ OK "status" : "LICENSING_ACTIVATION_IN_PROGRESS" Check for status and get dossier Generates and sends a dossier to the licensing server, which results in a license activation if all conditions are met. /tm/shared/licensing/activation GET Request Body BIG-IQ API Reference Guide 3-95

262 Chapter 3 Response 1: HTTP/ OK "status" : "LICENSING_ACTIVATION_IN_PROGRESS", Response 2: HTTP/ OK "status" : "DOSSIER_GENERATION_FAILED", "errortext":"..." Response 3: HTTP/ OK "status" : "DOSSIER_GENERATED", "dossier" : "<DOSSIER>" Does not involve any contact with the F5 licensing server. License /tm/shared/licensing/registration 3-96

263 Shared APIs Install license Install the license obtained from the activate server web page. /tm/shared/licensing/activation PUT "licensetext" : "<LICENSE_TEXT>" Request Body HTTP/ OK LicenseState object Registration key management APIs These APIs provide a means for storing registration keys for provisioning BIG-IP devices. With these APIs, you can create, delete, and modify registration keys. Query registration keys Gets all of the registration keys. /cm/shared/licensing/registrations GET Param 1 Name Status Values For getting only the keys available for activation NEED_EULA_ACCEPTANCE, AVAILABLE, ASSIGNED BIG-IQ API Reference Guide 3-97

264 Chapter 3 HTTP/ OK "items": [ "id": "76c43691-db ea-21eea10b45c9", "registrationkey": "IWQXC-PGBAMF-VQJ-JUZXXHK-HRVWEJN", "eulatext": "<pre-accepted eula text>", "unlimited": false, "status": "AVAILABLE", "generation": 1, "lastupdatemicros": , "kind": "cm:shared:licensing:registrations:registrationkeystate", "selflink": " 10b45c9" "generation": 6, "kind": "cm:shared:licensing:registrations:registrationkeycollectionstate", "lastupdatemicros": , "selflink": " 3-98

265 Shared APIs Create a registration key record Creates a new registration key with the provided values. /cm/shared/licensing/registrations POST registrationkey : "IWQXC-PGBAMF-VQJ-JUZXXHK-HRVWEJN", unlimited : "false", status : "NEED_EULA_ACCEPTANCE" HTTP/ OK "id": " b-eceb dce-ada7d6cf9ae2", "registrationkey": "IWQXC-PGBAMF-VQJ-JUZXXHK-HRVWEJN", "unlimited": false, "status": "NEED_EULA_ACCEPTANCE", "generation": 1, "lastupdatemicros": , "kind": "cm:shared:licensing:registrations:registrationkeystate", "selflink": " 6cf9ae2" If the key is not unlimited, then the status should be set to assigned after the first activation. Add User-Accepted EULA text Adds EULA text to a record that can be used when activating the key. This modifies the key record to show that it has been activated for a device. /cm/shared/licensing/registrations/id PATCH BIG-IQ API Reference Guide 3-99

266 Chapter 3 "eulatext" : "<pre-accepted eula text>", "status" : "AVAILABLE" HTTP/ OK "id": " b-eceb dce-ada7d6cf9ae2", "registrationkey": "IWQXC-PGBAMF-VQJ-JUZXXHK-HRVWEJN", "eulatext" : "<pre-accepted eula text>" "unlimited": false, "status": "AVAILABLE", "generation": 2, "lastupdatemicros": , "kind": "cm:shared:licensing:registrations:registrationkeystate", "selflink": " cf9ae2" 3-100

267 Shared APIs Assign a key to a device Links an existing key to a new device by modifying the key record to show it has been activated for a device. /cm/shared/licensing/registrations/id PATCH "devices": [ "link": " "status": "ASSIGNED" HTTP/ OK "id": " b-eceb dce-ada7d6cf9ae2", "registrationkey": "IWQXC-PGBAMF-VQJ-JUZXXHK-HRVWEJN", "devices": [ "link": " "eulatext" : "<pre-accepted eula text>" "unlimited": false, "status": "ASSIGNED", "generation": 3, "lastupdatemicros": , "kind": "cm:shared:licensing:registrations:registrationkeystate", "selflink": " 6cf9ae2" If the key is not unlimited, then status should be set to assigned after the first activation. BIG-IQ API Reference Guide 3-101

268 Chapter 3 Delete a registration key record Deletes a key. /cm/shared/licensing/registrations/id DELETE HTTP/ OK Licensing pools APIs The licensing pool APIs are used to manage pools licenses. These APIs can be used to add, delete, and update license pool keys, and activate, update, or deactivate licenses for devices and groups of devices. There is an automatic method and a manual activation method. The automatic method requires the ability to contact the F5 licensing server. There are four steps in this process, Steps 1 and 4 are the same for both methods. Create a license pool Creates a license pool, this is the first step in the sequence. /cm/shared/licensing/pools POST N/A "name" : "pool name", "baseregkey" : "ABC-XYZ", "addonkeys":["def-uvw" method:"automatic" 3-102

269 Shared APIs HTTP/ Created "name" : "pool name", "baseregkey" : "ABC-XYZ", "addonkeys":["def-uvw" method:"automatic", "uuid":"123", "selflink":" addonkeys is optional, method field can be AUTOMATIC or MANUAL, defaults to AUTOMATIC. Get the EULA (automatic method) This is step two when you use the automatic method. Gets the EULA, so it can be accepted. /cm/shared/licensing/pools/<uuid> GET N/A N/A HTTP/ Created "name" : "pool name", "baseregkey" : "ABC-XYZ", "addonkeys":["def-uvw" "method":"automatic", "eulatext":"...", "uuid":"123", "selflink":" The EULA might not appear immediately, but you can poll or subscribe for changes. BIG-IQ API Reference Guide 3-103

270 Chapter 3 Get the dossier (manual method) This is step two when you use the manual method. Gets the dossier. /cm/shared/licensing/pools/<uuid> GET N/A N/A HTTP/ Created "name" : "pool name", "baseregkey" : "ABC-XYZ", "addonkeys":["def-uvw" "method":"manual", "dossier":"...", "uuid":"123", "selflink":" The dossier might not appear immediately, but you can poll or subscribe for changes. Submit the dossier through the normal manual license activation method at activate.f5.com

271 Shared APIs Accept the EULA (automatic method) This is step three when you use the automatic method. Agree to the EULA, proceed with the licensing activation. /cm/shared/licensing/pools/<uuid> PATCH N/A "eulatext": "...", "state":"accepted_eula" HTTP/ Created The eulatext must match the text provided by the worker in the previous step. If a EULA has been previously accepted for this license, you might not need to accept the EULA. BIG-IQ API Reference Guide 3-105

272 Chapter 3 Patch the license text (manual method) This is step three in the manual activation sequence. Copy the license text from activate.f5.com and submit it here. /cm/shared/licensing/pools/<uuid> PATCH N/A "licensetext": "..." HTTP/ Accepted The licensetext must match exactly what is provided from activate.f5.com, if an inaccurate licensetext is given, pool device activations might fail. Poll to check the status of the pool license with a GET (described above) to verify that the pool is LICENSED

273 Shared APIs Activate a device This is step four in both activation sequences. Adds a device to the license pool and activates it. /cm/shared/licensing/pools/<uuid>/members POST N/A "devicereference":"link":" HTTP/ Created "devicereference":"link":" "uuid":"222", "selflink":" BIG-IQ API Reference Guide 3-107

274 Chapter 3 Re-activate a pool license to add keys or update service check date Re-activates a pool license to include additional add-on keys or update expiration/service check dates. /cm/shared/licensing/pools/<uuid> PATCH N/A "state":"relicense" HTTP/ "devicereference":"link":" "uuid":"333", "selflink":" "state":"install" Re-activate a device or retry license install Reactivates an expired license or retry a failed installation. /cm/shared/licensing/pools/<uuid>/members/<member uuid> PATCH N/A "state":"install" HTTP/ "devicereference":"link":" "uuid":"333", "selflink":" "state":"install" 3-108

275 Shared APIs Deactivate a device or device group Removes a device or device group from the license pool and deactivate the licenses associated with those devices. /cm/shared/licensing/pools/<uuid>/members/<member uuid> DELETE N/A N/A HTTP/ OK BIG-IQ API Reference Guide 3-109

276 Chapter 3 Deactivate a license pool Removes a device pool. /cm/shared/licensing/pools/<pool uuid> DELETE N/A N/A HTTP/ OK 3-110