About Cloud API Requests
- Panna .
- Shwetha S
In your cloud environment, the cloud adapter acts as the cloud API client. Only API requests made by admin users who have the correct permissions on the cloud API ACL (Access Control List) are processed by the cloud API service. When the Cloud Platform Appliance receives a cloud API request, it processes the request based on authority delegation of the objects and respective cloud extensible attributes. For information about cloud extensible attributes, see Extensible Attributes for Cloud Objects. If the Cloud Platform Appliance is not authoritative for the referenced objects, it proxies the request to the authoritative appliance that can be another Cloud Platform Appliance or to the Grid Master if no authority delegation is defined. For information about proxying cloud API requests, see Proxying Cloud API Requests below.
Note
For the cloud API service to function properly, configure your networks and firewalls accordingly to allow port 443 HTTPS connectivity between the cloud adapter and Cloud Platform Appliance, between the cloud adapter and the Grid Master (if applicable), between the Grid Master and Cloud Platform members, and between each Cloud Platform member.
If you are using the AWS API Proxy to send API requests, ensure that you understand how to set up and configure the proxy. For detailed information, refer to the Infoblox Installation Guide for vNIOS for AWS.
When implementing Cloud Network Automation in AWS, you can use Elastic Scaling to allocate and deallocate dynamic licenses and automatically spin up vNIOS Grid members and join them to the Grid. You can purchase and install NIOS feature licenses in advance and store them in a license pool container on the Grid Master. You can then decide when and how to automatically provision and configure vNIOS for AWS cloud virtual appliances. When you remove a vNIOS cloud appliance, the licenses on this appliance are released and returned to the license pool and are available for the next deployment.Â
Cloud API Request Process
As described in the below table, all cloud API requests are subject to the following process before responses are returned. The appliance
Cloud API Request Process
Steps | Descriptions | Configuration that affects the outcome of this step |
Authentication and categorization | All cloud API requests are authenticated based on the authentication sources. Once authenticated, the requests are categorized as either a cloud API request or not. All requests that specify user identity as users defined in admin groups with cloud API access are Managing Admin Groups and Admin Roles categorized as cloud API requests. | Define admin user accounts that can be used to send cloud API requests. For information, see Managing Admin Groups and Admin Roles. |
Authorization | All cloud API requests are subject to authorization based on the ACLs (Access Control Lists) defined for the Grid or Cloud Platform Appliance. You can control which admin accounts can be used to send API requests. The ACLs can contain admin users in admin groups with cloud API access or remote authenticated users. | Define ACLs on the Grid Master or Cloud Platform Appliance. |
Proxying Requests | If a Cloud Platform Appliance is not authoritative for a cloud API request, it proxies the request either to the authoritative Cloud Platform Appliance or to the Grid Master for processing. Similarly, if an object has been delegated and the API request is made to the Grid Master, the Grid Master proxies that request to the authoritative Cloud Platform Appliance. | Ensure that HTTPS connectivity between each Cloud Platform member and between each Cloud Platform member and the Grid Master is functioning properly for proxying. |
Validation | NIOS performs a final validation on the cloud API request based on permissions configured for the admin users and restrictions for the applicable objects. If the request is processed within the scope of an explicit delegation, the admin user is considered to have full permissions within the scope, and any permission defined for admin groups with cloud API access is ignored. Otherwise, the request is subject to validation for all permissions defined for admin groups with cloud API access. | Define admin permissions for admin groups with cloud API access. |
Auditing | Cloud API related events are logged to the NIOS syslog of the Grid member that processes the API requests instead of to the NIOS audit log. | Configure syslog server for the cloud member. |
Supported Cloud API Objects
The following table lists all the supported cloud API object types, methods, and functions. In your cloud API requests, you cannot include RESTful API object types, methods, and functions that are not listed in the table, even when the Grid Master supports them for other purposes. Note that the supported types and operations for cloud API requests are sub sets of all types and operations supported on the Grid Master.
Before you send any cloud API requests, ensure that you understand the implications and restrictions for each supported object. NIOS uses extensible attributes to associate specific information with a cloud object. For information about the default cloud extensible attributes and how to use them, see Extensible Attributes for Cloud Objects.
In AWS (Amazon Web Services), you can create a VPC (Virtual Private Cloud) and a subnet using the same network address and subnet mask. For example, you can add 172.29.02.0/24 as the VPC and 172.29.2.0/24 as the subnet and create VMs in the subnet. However, you cannot add a network container and a network using the same network address and subnet mask in NIOS. Therefore, when you send an API request to create such VPC and subnet in AWS, NIOS recognizes only the VPC, not the subnet. As a result, you are not able to create VMs under the subnet. For more information about how to create VPCs and subnets in AWS for NIOS, refer to the Infoblox Installation Guide for vNIOS for AWS.
In addition, when you delegate authority for supported cloud objects, NIOS may process the requests differently based on the following:
How the object was first created.
Whether authority for the object has already been delegated to a Cloud Platform Appliance.
For details about authority delegation and restrictions for each object, see About Authority Delegation.
Note
NIOS does not process cloud API requests that contain unsupported object types or any combination of supported object types with unsupported methods and functions. Although you can use all the fields in a supported object type, some restrictions may apply to supported values for some of these fields. For restrictions, see the Comments field in the below table for the corresponding object.
Supported Cloud API Objects for Cloud API Service
Note
The cloud API service does not support scheduling and workflow approval requests. Objects deleted through a cloud API request are not stored in the Recycle Bin, except for DNS zones and network views. For information about the Recycle Bin, see Using the Recycle Bin .
Â
Supported Object Type | Cloud API Object | Allowed Operations in cloud API Requests | Authority Delegation and Restrictions | Required Extensible Attributes in cloud API Requests (for creations only) |
|---|---|---|---|---|
Network View | networkview | Read, Create, Modify, Delete | See Network Views for information about authority delegation. | Tenant ID Cloud API Owned CMP Type |
IPv4 Network Container | networkcontainer | Read, Create, Modify, Delete Function: next_available_network | Split network, join networks, and RIR related operations are not supported. See IPv4 andIPv6 Networks and Network Containers for information about authority delegation. | Tenant ID Cloud API Owned CMP Type |
IPv6 Network Container | ipv6networkcontainer | Read, Create, Modify, Delete Function: next_available_network | Split network, join networks, and RIR related operations are not supported. See IPv4 andIPv6 Networks and Network Containers for information about authority delegation. | Tenant ID Cloud API Owned CMP Type |
IPv4 Network | network | Read, Create, Modify, Delete Function: next_available_ip | Split network, join networks, and RIR related operations are not supported. See IPv4 andIPv6 Networks and Network Containers for information about authority delegation. | Tenant ID Cloud API Owned CMP Type |
IPv6 Network | ipv6network | Read, Create, Modify, Delete Function: next_available_ip | Split network, join networks, and RIR related operations are not supported. See IPv4 andIPv6 Networks and Network Containers for information about authority delegation. | Tenant ID Cloud API Owned CMP Type |
IPv4 DHCP Range | range | Read, Create, Modify, Delete Function: next_available_ip | See DHCP Ranges for information about authority delegation. | Tenant ID Cloud API Owned CMP Type |
IPv6 DHCP Range | ipv6range | Read, Create, Modify, Delete Function: next_available_ip | See DHCP Ranges for information about authority delegation. | Tenant ID Cloud API Owned CMP Type |
IPv4 Fixed Address (Reservation) | fixedaddress | Read, Create, Modify, Delete Function: next_available_ip You can also create and delete through Grid Manager. All required Cloud EAs are automatically populated in the GUI. | See IPv4 and IPv6 Fixed Addresses for information about authority delegation. | Tenant ID Cloud API Owned CMP Type |
IPv6 Fixed Address (Reservation) | ipv6fixedaddress | Read, Create, Modify, Delete Function: next_available_ip You can also create and delete through Grid Manager. All required Cloud EAs are automatically populated in the GUI. | See IPv4 and IPv6 Fixed Addresses for information about authority delegation. | Tenant ID Cloud API Owned CMP Type |
DNS View | view | Read, Modify | See DNS Views for information about authority delegation. | Tenant ID Cloud API Owned CMP Type |
DNS Zone | zone_auth | Read, Create, Modify, Delete | See DNS Zones for information about authority delegation. | Tenant ID Cloud API Owned CMP Type |
Host Record | record:host | Read, Create, Modify, Delete You can also create and delete through Grid Manager. All required Cloud EAs are automatically populated in the GUI. | See Host Records for information about authority delegation. | Tenant ID Cloud API Owned CMP Type |
record:host_ipv4addr | Read, Create, Modify, Delete Function: next_available_ip You can also create and delete through Grid Manager. All required Cloud EAs are automatically populated in the GUI. | |||
record:host_ipv6addr | Read, Create, Modify, Delete Function: next_available_ip You can also create and delete through Grid Manager. All required Cloud EAs are automatically populated in the GUI. | |||
Resource Record | record:a | Read, Create, Modify, Delete Function: next_available_ip | See DNS Resource Records for information about authority delegation. | Tenant ID Cloud API Owned CMP Type |
record:aaaa | Read, Create, Modify, Delete Function: next_available_ip | |||
record:cname | Read, Create, Modify, Delete | |||
record:ptr | Read, Create, Modify, Delete Function: next_available_ip | |||
record:mx | Read, Create, Modify, Delete | |||
record:naptr | Read, Create, Modify, Delete | |||
record:srv | Read, Create, Modify, Delete | |||
record:txt | Read, Create, Modify, Delete | |||
Grid Member | member | Read only Function: restartservices | API requests calling for service restarts on a Grid member can be processed by the Cloud Platform Appliance only if the member requested is also the Cloud Platform Appliance processing the request. | N/A |
Grid | grid | Read only Function: restartservices | All cloud API requests calling for service restarts are proxied to the Grid Master. | N/A |
Extensible Attribute | extensibleattributedef | Read only | You can use cloud attributes as source objects to obtain the next available IP address or network. When doing so, you must also include the respective network view for the object. | N/A |
Proxying Cloud API Requests
In Cloud Network Automation, the primary Cloud Platform Appliance that receives cloud API requests can act as a proxy for other authoritative Cloud Platform members and for the Grid Master. This proxying mechanism is important when the Cloud Platform Appliance cannot process requests that contain objects for which it is not authoritative, or when objects in the requests do not have authority delegation and must be processed by the Grid Master.
Note that only successfully authenticated and authorized requests that require proxying are sent to the respective appliance for processing. Proxying is limited to one hop within the Grid. Therefore, if the destination appliance cannot process a proxied request, the request will not be forwarded and an error is returned to the client.
To ensure that the proxying mechanism functions properly, configure your systems to allow for the following communication:
Allow all HTTPS connectivity among the Cloud Platform Appliances as well as to the Grid Master based on your organization's firewall requirements.
Ensure that you use the VIP or the MGMT address if it is enabled (including that for the Grid Master) as the destination IP for the HTTPS connectivity. Note that this is a per member setting.
Grant appropriate permissions to admin groups with cloud API access to ensure that tasks for objects outside of the delegation function properly on the Grid Master.
Sample Cloud API Requests
This section includes sample cloud API requests for supported objects:
Adding a network view:
curl -H "Content-Type: application/json" -k1 -u cloud:infoblox -X POST https://10.0.0.2/wapi/v2.0/networkview -d '{"name": "netview1", "extattrs": { "Tenant ID":{"value": "1011"} ,"Cloud API Owned":{"value":"True"},"CMP Type":{"value":"vCO/vCAC"}}}'
Adding a network within the delegated network view in the above example:
curl -H "Content-Type: application/json" -k1 -u cloud:infoblox -X POST https://10.0.0.2/wapi/v2.0/network -d '{ "network": "20.0.0.0/24","network_view":"netwview1","extattrs": { "Tenant ID":{"value": "1011"} ,"Cloud API Owned":{"value":"True"},"CMP Type":{"value":"vCO/vCAC"}}}'
Adding a DHCP range within the network created in the above example:
curl -H "Content-Type: application/json" -k1 -u cloud:infoblox -X POST https://10.0.0.2/wapi/v2.0/range -d '{ "end_addr": "20.0.0.40", "member": {"_struct": "dhcpmember1", "ipv4addr": "10.0.0.2", "name": "corpxyz.com"},"network": "20.0.0.0/24", "network_view": "netview1", "start_addr": "20.0.0.35", "extattrs": {"Tenant ID":{"value": "1011"} ,"CMP Type":{"value":"vCO/vCAC"},"Cloud API Owned":{"value":"True"}}}'
Adding an A Record:
curl -H "Content-Type: application/json" -k1 -u cloud:infoblox -X POST https://10.0.0.2/wapi/v2.0/record:a -d '{"name": "corp200.com", "ipv4addr":"20.0.0.2","view": "default.netview1","extattrs": {"Tenant ID":{"value": "1011"} , "CMP Type":{"value":"vCO/vCAC"},"Cloud API Owned": {"value":"True"},"VM ID":{"value":"12"}}}'
Adding a Fixed address:
curl -H "Content-Type: application/json" -k1 -u cloud:infoblox -X POST https://10.0.0.2/wapi/v2.0/fixedaddress -d '{"ipv4addr": "20.0.0.5", "network_view": "netview1","mac":"15:06:32:16:00:00","extattrs": { "Tenant ID":{"value": "1011"} ,"CMP Type":{"value":"vCO/vCAC"} ,"VM ID":{"value":"352"},"Cloud API Owned":{"value":"True"}}}'
Adding a zone:
curl -H "Content-Type: application/json" -k1 -u cloud:infoblox -X POST https://10.0.0.2/wapi/v2.0/zone_auth -d '{ "fqdn":"test.com","grid_primary": [{"name": "infoblox.localdomain", "stealth": false},{"name": "corpxyz.com", "stealth": false}],"view": "default.netview1","extattrs": { "Tenant ID":{"value": "1011"} , "CMP Type":{"value":"vCO/cCAC"} ,"Cloud API Owned":{"value":"True"}}}'
Adding a network container:
curl -H "Content-Type: application/json" -k1 -u cloud:infoblox -X POST https://10.0.0.2/wapi/v2.0/networkcontainer -d '{ "network": "200.0.0.0/24","network_view": "netview1","extattrs": { "Tenant ID":{"value": "1011"} ,"Cloud API Owned":{"value":"True"},"CMP Type":{"value":"vCO/vCAC"}}}'
Add a host record:
curl -H "Content-Type: application/json" -k1 -u cloud:infoblox -X POST https://10.0.0.2/wapi/v2.0/record:host -d '{ "ipv4addrs": [{ "configure_for_dhcp": false,"ipv4addr": "20.0.0.1", "mac": "11:11:22:22:33:33"}],"ipv6addrs": [{"configure_for_dhcp": false,"duid": "11:22", "ipv6addr": "13::1"},{"configure_for_dhcp": false,"duid": "21:22", "ipv6addr": "13::2"}],"name": "host.corpxyz.com", "view": "default.netview1"}'
Adding an MX Record:
curl -H "Content-Type: application/json" -k1 -u cloud:infoblox -X POST https://10.0.0.2/wapi/v2.0/record:mx -d '{ "mail_exchanger": "abc.com","name":"def.corpxyz.com", "preference": 10,"view":"default.netview1","extattrs": { "Tenant ID":{"value": "1011"} , "CMP Type":{"value":"vCO/vCAC"}, "Cloud API Owned":{"value":"False"},"VM ID":{"value":"230"}}}
Sample Cloud API Requests for Elastic Scaling
Creating a Member:
curl -H "Content-Type: application/json" -k1 -u cloud:cloud -X POST https://10.40.240.88/wapi/v2.2/member -d '{"platform": "VNIOS", "host_name": "test1.com", "vip_setting": {"address": "1.1.1.1", "gateway": "1.1.0.2", "subnet_mask": "255.255.0.0"}}'
Getting a Member:
curl -H "Content-Type: application/json" -k1 -u cloud:cloud -X GET https://10.40.240.88/wapi/v2.2/member
Adding Pre-Provisioned Information for the Member:
curl -H "Content-Type: application/json" -k1 -u cloud:cloud -X PUT https://10.40.240.101/wapi/v2.2/member/b25lLnZpcnR1YWxfbm9kZSQ3:test1.com -d '{"pre_provisioning": {"hardware_info": [{"hwmodel": "CP-V1405", "hwtype": "IB-VNIOS"}], "licenses": ["cloud_api", "dhcp", "dns", "enterprise", "vnios"]}}'
Creating and Delegating a Network View:
curl -H "Content-Type: application/json" -k1 -u cloud:cloud -X POST https://10.40.240.88/wapi/v2.2/networkview -d '{"name":"testnv", "extattrs":{"Tenant ID":{"value": "1011"} , "CMP Type":{"value":"vm130ctest"}, "Cloud API Owned":{"value":"True"}} }
Creating and Delegating a Network:
curl -H "Content-Type: application/json" -k1 -u cloud:cloud -X POST https://10.40.240.88/wapi/v2.2/network -d '{"network":"21.0.0.0/8", "network_view":"default", "cloud_info":{"delegated_member": {"ipv4addr": "1.1.1.1","name":"test1.com"}},"extattrs":{ "Tenant ID":{"value": "1011"} , "CMP Type":{"value":"vm130ctest"}, "Cloud API Owned":{"value":"True"}} }'
Undelegating a Network:
curl -H "Content-Type: application/json" -k1 -u cloud:cloud -X PUT https://10.40.240.88/wapi/v2.2/network/ZG5zLm5ldHdvcmskMjEuMC4wLjAvOC8w:21.0.0.0/8/ default -d '{"cloud_info": {"delegated_member": null }}'
Creating and Delegating an Authoritative Zone
curl -H "Content-Type: application/json" -k1 -u cloud:cloud -X POST https://10.40.240.88/wapi/v2.2/zone_auth -d '{"fqdn": "test.com", "grid_primary": [{"name": "test1.com", "stealth": false}], "view": "default", "extattrs":{ "Tenant ID":{"value": "1011"} , "CMP Type":{"value":"vm130ctest"}, "Cloud API Owned":{"value":"True"}}}'
Deleting a Member:
curl -H "Content-Type: application/json" -k1 -u cloud:cloud -X DELETE https://10.40.240.88/wapi/v2.2/member/b25lLnZpcnR1YWxfbm9kZSQ3:test1.com
Creating Token for the Pre-Provisioned Member (note that only superuser can create a token; you must configure superusers admin groups with cloud API access):
curl -H "Content-Type: application/json" -k1 -u cloud:cloud -X POST https://10.40.240.88/wapi/v2.2/member/b25lLnZpcnR1YWxfbm9kZSQ3:test1.com?_function=create_token
Reading Token for the Pre-Provisioned Member (note that only superuser can create a token; you must configure superusers admin groups with cloud API access):
curl -H "Content-Type: application/json" -k1 -u cloud:cloud -X POST https://10.40.240.88/wapi/v2.2/member/b25lLnZpcnR1YWxfbm9kZSQ3:test1.com?_function=read_token