To import an IPAM package using the IaaS API, you reserve enough space for the package then you make multiple PATCH requests to import smaller pieces of the package. After importing all the pieces, you use a POST request to upload the file onto the server.

The IaaS API implements the TUS RFC protocol which provides a mechanism for resumable file uploads. By dividing a large package into smaller ZIP packages and importing the packages individually, you ensure that you will not exceed the server's file size limit with your upload.

For more information about the TUS RFC protocol, see https://github.com/tus/tus-resumable-upload-protocol/blob/main/protocol.md.

This procedure shows how to import your IPAM package using the integrations IPAM APIs. Then you complete the integration using the Automation Assembler UI or the integrations API.

Prerequisites

  • Verify that all general prerequisites and prerequisites for the Automation Assembler IaaS API have been satisfied. See Prerequisites for API Use Case Examples.
  • Verify that you know the size of the package that you want to upload. If the package is large, divide it into smaller packages. The following example divides the large package into smaller packages that are each 9000000 bytes in size. 
    split -b 9000000 <your_package>.zip <your_package>.zip_split
  • If using the API to complete the IPAM integration with a cloud account, verify that you have the following parameters for your cloud account:
    • privateKeyId used to create your cloud account.
    • privateKey used to create your cloud account.
    • hostName used to create your cloud account.
    • faasProviderEndpointID is your cloud account ID.

Procedure

  1. Reserve space for the package with Upload-Length equal to the size of the package in bytes. 
    curl -X POST \
  "$url/iaas/api/integrations-ipam/package-import?apiVersion=$api_version" \
  -H "Authorization: Bearer $access_token" \
  -H "Upload-Length: <package_size_in_bytes>" \
  -H "Tus-Resumable: 1.0.0" | jq "."
    Examine the response header to get the location for the package.
    Note: You must complete the package import process before the location reservation expires in approximately two hours.
  2. Assign a variable for the location ID. 
    location_id = '<package_location>'
  3. Import the first small package with Upload-Offset equal to zero. 
    curl -X PATCH \
  "$url/iaas/api/integrations-ipam/package-import/$location_id/?apiVersion=$api_version" \
  -H "Authorization: Bearer $access_token" \
  -H "Tus-Resumable: 1.0.0" \
  -H "Content-Type: application/offset+octet-stream" \
  -H "Upload-Offset: 0" | jq "."
    A successful response returns 204 No Content and includes an upload offset number. Use that number in the PATCH request for the next package.
  4. Import the next small package.
    • You must import the small packages in a sequential order.
    • Upload-Offset is the offset value from the response header of the previous PATCH request.
    curl -X PATCH \
  "$url/iaas/api/integrations-ipam/package-import/$location_id/?apiVersion=$api_version" \
  -H "Authorization: Bearer $access_token" \
  -H "Tus-Resumable: 1.0.0" \ 
  -H "Content-Type: application/offset+octet-stream" \
  -H "Upload-Offset: <upload_offset_from_previous_response>" | jq "."
    Verify that the successful response returns 204 No Content and a larger upload offset number. Continue making PATCH requests with the upload offset numbers from the previous response until all the smaller packages have been imported.
    Note: If you do not know the current upload offset number, make a HEAD request with the location ID. 
    curl -X HEAD \
  "$url/iaas/api/integrations-ipam/package-import/$location_id/?apiVersion=$api_version" \
  -H "Authorization: Bearer $access_token" \
  -H "Tus-Resumable: 1.0.0" | jq "."

    Use the upload offset number in the response for the next PATCH request.

  5. After all the small packages have been imported, upload the file.
    The input body includes:
    • bundleId for the location ID.
    • "option": "OVERWRITE" to overwrite any existing package. 
    curl -X POST \
  "$url/iaas/api/integrations-ipam/package-import?apiVersion=$api_version" \
  -H "Authorization: Bearer $access_token" \
  -H "Content-Type: application/json" \
  -H "Tus-Resumable: 1.0.0" \
  -d '{
    "bundleId":"$location_id",
    "option" : "OVERWRITE"
    } 
| jq "."
    A successful response includes the Provider ID, Provider name, and Provider version. To complete an IPAM integration, you can use the Automation Assembler UI or the integrations endpoint in the IaaS API.
  6. To complete an integration using the Automation Assembler UI, select Infrastructure > Integrations > Add integration > IPAM. On the New Integration page that appears, select Manage IPAM Providers and choose the package with the Provider name and Provider version from the API response.
  7. (Optional) To complete an integration using the API:
    1. Assign a variable for the provider ID.
      provider_id = '<provider_id_from_package_upload>'
    2. Create a new IPAM integration. 
      curl -X POST \
  "$url/iaas/api/integrations?apiVersion=$api_version" \
  -H "Authorization: Bearer $access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationProperties": {     
      "providerId" : "'$provider_id'",
      "faasProviderEndpointId": "<your_provider_endpoint_ID>",
      "privateKeyId": "<your_privateKeyId>",
      "privateKey": "<your_privateKey>",
      "hostName": "<your_hostName>",
      "dcId": "onprem"
    },
    "customProperties": {"isExternal": "true"},
    "integrationType": "ipam",
    "associatedCloudAccountIds": [],
    "associatedMobilityCloudAccountIds": {},
    "privateKey": "<your_privateKey>",
    "privateKeyId": "<your_privateKeyId>"
  } | jq "."
      The response includes a self link to track the request.
    3. Assign the selfLink variable. 
      selfLink_id='<example_selfLink_alphanumeric_string>'
    4. Use the selfLink variable to track the request. 
      curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token" "$url/iaas/api/request-tracker/$selfLink_id?apiVersion=$api_version" | jq "."

      The integration is created with the response includes "status": "FINISHED".

Example: Import an IPAM Package

This example shows how to import an Infoblox IPAM package with a total size of 73342782 bytes. To import incrementally using smaller packages, you divide the larger package into smaller packages. This example assumes that you have divded the package into multiple smaller packages each 9000000 bytes in size.

After importing the IPAM package, you create an integration with a cloud account using the the Automation Assembler UI or the integrations endpoint in the IaaS API. This example shows how to integrate the uploaded IPAM package with a cloud account that has the following parameters:

  • faasProviderEndpointId: "f46337e9-e0c2-4ada-9244-766a8e54da48"
  • hostName: "infoblox.sof-mbu.eng.mycompany.com"
  • privateKey: "Password!23"
  • privateKeyId: "[email protected]"

Assign variables.

Note: If your organization uses an API service that is hosted outside of the United States, your URL variable must include a country abbreviation. See Regional Endpoints for VMware Aria Automation APIs. 
$ url='https://api.mgmt.cloud.vmware.com'
$ api_version='2021-07-15'

Reserve space for the package.

$ curl -X POST \
  "$url/iaas/api/integrations-ipam/package-import?apiVersion=$api_version" \
  -H "Authorization: Bearer $access_token" \
  -H "Upload-Length: 73342782" \
  -H "Tus-Resumable: 1.0.0" | jq "."

Examine the response to get the location ID.

status: 201
body: empty
headers: {location:/iaas/api/integrations-ipam/package-import/8a81db06-f27f-4ccb-a7c5-960c35107ed6, ...}

Assign the location ID variable.

$ location_id='8a81db06-f27f-4ccb-a7c5-960c35107ed6'

Import the first package with a content length of 9000000 bytes and a zero upload offset value.

$ curl -X PATCH \
  "$url/iaas/api/integrations-ipam/package-import/$location_id/?apiVersion=$api_version" \
  -H "Authorization: Bearer $access_token" \
  -H "Content-Length: 9000000" \
  -H "Tus-Resumable: 1.0.0" \
  -H "Content-Type: application/offset+octet-stream" \
  -H "Upload-Offset: 0" | jq "."

Examine the header in the response to get the upload offset value.

status: 204
body: empty
headers: {upload-offset:9000000, ...}

Import the next package.

$ curl -X PATCH \
  "$url/iaas/api/integrations-ipam/package-import/$location_id/?apiVersion=$api_version" \
  -H "Authorization: Bearer $access_token" \
  -H "Content-Length: 9000000" \
  -H "Tus-Resumable: 1.0.0" \
  -H "Content-Type: "application/offset+octet-stream" \
  -H "Upload-Offset: 9000000" | jq "."

Examine the header in the response again to get the next upload offset value.

status: 204
body: empty
headers: {upload-offset:18000000, ...}

Import the next package.

$ curl -X PATCH \
  "$url/iaas/api/integrations-ipam/package-import/$location_id/?apiVersion=$api_version" \
  -H "Authorization: Bearer $access_token" \
  -H "Content-Length: 9000000" \
  -H "Tus-Resumable: 1.0.0" \
  -H "Content-Type: "application/offset+octet-stream" \
  -H "Upload-Offset: 18000000" | jq "."

Repeat the process to get the upload offset value from the header response and use that value to import the next package.

After importing the final small package, upload the complete package.

$ curl -X POST \
  "$url/iaas/api/integrations-ipam/package-import?apiVersion=$api_version" \
  -H "Authorization: Bearer $access_token" \
  -H "Tus-Resumable: 1.0.0" \
  -d '{
    "bundleId":"$location_id",
    "option" : "OVERWRITE"
    } 
| jq "."

A successful response includes the provider ID, provider name, and the provider version 

{
  "providerId": "86801580-9042-49b6-879d-5a7361d33519",
  "providerName": "Infoblox", 
  "providerVersion": "1.6"
  "logoIcon":"iVBORw...",
...

To create an IPAM integration using the Automation Assembler UI, select Infrastructure > Integrations > Add integration > IPAM. On the New Integration page that appears, select Manage IPAM Providers and choose the package with the Provider name Infoblox and Provider version 1.6.

To create an IPAM integration using the API, assign the provider ID variable.

$ provider_id = "86801580-9042-49b6-879d-5a7361d33519"

Create the integration.

$ curl -X POST \
  "$url/iaas/api/integrations?apiVersion=$api_version" \
  -H "Authorization: Bearer $access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationProperties": {     
      "providerId" : "'$provider_id'",
      "faasProviderEndpointId": "f46337e9-e0c2-4ada-9244-766a8e54da48",
      "privateKeyId": "[email protected]",
      "privateKey": "Password!23",
      "hostName": "infoblox.sof-mbu.eng.mycompany.com",
      "dcId": "onprem"
    },
    "customProperties": {"isExternal": "true"},
    "integrationType": "ipam",
    "associatedCloudAccountIds": [],
    "associatedMobilityCloudAccountIds": {},
    "privateKey": "Password!23",
    "privateKeyId": "[email protected]"
  } | jq "."

Examine the response.

{     
"progress": 0,     
"status": "INPROGRESS",     
"name": "Integration creation/update",     
"id": "117ff057-9e26-4f0c-ae7b-eb9fcc1c15cc",     
"selfLink": "/iaas/api/request-tracker/117ff057-9e26-4f0c-ae7b-eb9fcc1c15cc" 
}

Assign the selfLink variable.

$ selfLink_id='117ff057-9e26-4f0c-ae7b-eb9fcc1c15cc'

Use the selfLink for tracking.

$ curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token" "$url/iaas/api/request-tracker/$selfLink_id?apiVersion=$api_version" | jq "."

The integration is complete when the response includes "status": "FINISHED".

{     
"progress": 100,     
"status": "FINISHED",     
"resources": [
     "/iaas/api/integrations/9df2b0a8-2ce6-4465-bf39-04290965da9e"     ],
     "name": "Integration creation/update",
     "id": "117ff057-9e26-4f0c-ae7b-eb9fcc1c15cc",     
     "selfLink": "/iaas/api/request-tracker/117ff057-9e26-4f0c-ae7b-eb9fcc1c15cc" 
}