As a cloud administrator, you can use the network IP range API to allocate the IP addresses that you want to reserve and make them unavailable for deployment by VMware Aria Automation.

To allocate IP addresses, you submit a request with either:
  • A list of specific IP addresses.
  • The number of IP addresses.
You can also provide an optional description.
Note: The following restrictions apply to the request:
  • No more than 100 IP addresses can be allocated in a single call.
  • If listing specific IP addresses, the addresses must all be of the same type. Mixing IPv4 and IPv6 addresses is not supported.

Prerequisites

  • Verify that all general prerequisites and prerequisites for the Automation Assembler Infrastructure as a Service (IaaS) service have been satisfied. See Prerequisites for API Use Case Examples.
  • Verify that you have the ID of the network IP range that includes the IP addresses that you want to reserve. See Query for IP Addresses.
  • If you plan to specify the IP addresses from the network IP range, verify that you know the IPv4 or IPv6 addresses. See Query for IP Addresses.
  • If you are a cloud administrator and you plan to specify the number of IP addresses from the network IP range, verify that the number is less than or equal to the number of available IP addresses in the range.

Procedure

  1. Assign the variable for the network IP range ID. 
    ip_range_id='<your_network_ip_range_id>'
  2. Allocate the IP addresses by providing a list of addresses.
    The following request example allocates two IP addresses.
    • Specify either IPv4 or IPv6 addresses.
    • To release additional IP addresses, provide additional addresses in the payload.
    curl --location --request POST \
  $url/iaas/api/network-ip-ranges/$ip_range_id/ip-addresses/allocate?apiVersion=$api_version \
  -H "Authorization: Bearer $access_token" \
  -H 'Content-Type: application/json' \
  -d '{
     "description":"<your_optional_description>",
     "ipAddresses":["<ipv_address_1>", "<ipv_address_2>"]
}'
    Examine the response for the self link to track the request.
  3. (Optional) If you do not list IP addresses, provide the number of IP addresses to allocate. 
    curl --location --request POST \
  $url/iaas/api/network-ip-ranges/$ip_range_id/ip-addresses/allocate?apiVersion=$api_version \
  -H "Authorization: Bearer $access_token" \
  -H 'Content-Type: application/json' \
  -d '{
     "description":"<your_optional_description",
     "numberOfIps": "<number_of_IPs>"
}'
    Examine the response for the self link to track the request.
  4. Assign the selfLink variable. 
    selfLink_id='example-selfLink-alphanumeric-string'
  5. 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 IPs are allocated when the response includes "status": "FINISHED" and provides a list of allocated resources.
    Note: If you specified the number of IP addresses to allocate, you query for the details of each resource in the response to get the allocated IP address associated with the resource. 
    curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token" "$url/iaas/api/network-ip-ranges/$ip_range_id/ip-addresses/<ip_address_id>?apiVersion=$api_version"  | jq "."

Example: Allocate IP addresses within an IP range

Using the network IP range with the IP addresses that you want to reserve, specify the IP addresses to allocate.
  • Two IPv4 IP addresses used in this example are: ["196.192.2.19", "196.192.2.20"]
  • Two IPv6 IP addresses used in this example are: ["fe45:10:118:136:fcd8:d68d:9701:8975","fe45:10:118:136:fcd8:d68d:9701:8985"]

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'
$ ip_range_id='703a02df-3b6d-4ad7-b146-582b398055f2'

Allocate IPv4 addresses by providing a list. 

curl --location --request POST \
  $url/iaas/api/network-ip-ranges/$ip_range_id/ip-addresses/allocate?apiVersion=$api_version \
  -H "Authorization: Bearer $access_token" \
  -H 'Content-Type: application/json' \
  -d '{
     "description":"Allocate ipv4 addresses for QA test machines",
     "ipAddresses":["196.192.2.19", "196.192.2.20"]
}'

Or allocate IPv6 addresses by providing a list.

curl --location --request POST \
  $url/iaas/api/network-ip-ranges/$ip_range_id/ip-addresses/allocate?apiVersion=$api_version \
  -H "Authorization: Bearer $access_token" \
  -H 'Content-Type: application/json' \
  -d '{
     "description":"Allocate ipv6 addresses for QA test machines",
     "ipAddresses":["fe45:10:118:136:fcd8:d68d:9701:8975","fe45:10:118:136:fcd8:d68d:9701:8985"]
}'

Or specify the number of IP addresses to allocate, such as four.

curl --location --request POST \
  $url/iaas/api/network-ip-ranges/$ip_range_id/ip-addresses/allocate?apiVersion=$api_version \
  -H "Authorization: Bearer $access_token" \
  -H 'Content-Type: application/json' \
  -d '{
     "description":"Allocate four IP addresses for QA test machines",
     "numberOfIps": "4"
}'

The response provides the selfLink variable for tracking.

{
    "progress": 1,
    "status": "INPROGRESS",
    "name": "IP Address Allocation Task",
    "id": "ab726e31-ed8bfdfb-83d9-4964-b719-8b395c87d2c9",
    "selfLink": "/iaas/api/request-tracker/ab726e31-ed8bfdfb-83d9-4964-b719-8b395c87d2c9"
}

Assign the selfLink variable.

selfLink_id= 'ab726e31-e909-4bcc-87ef-5139294eb26a'

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 "."

When the request is complete, the response includes "status": "FINISHED".

  • This is an example of the response when two IPv4 or IPv6 addresses are specified and allocated. You know the IP addresses because you provided them in the request. 
    {
    "progress": 100,
    "status": "FINISHED",
    "resources": [
        "/iaas/api/network-ip-ranges/703a02df-3b6d-4ad7-b146-582b398055f2/ip-addresses/6212ac8b-a885-4416-bf0d-ebb88628bef1",
        "/iaas/api/network-ip-ranges/703a02df-3b6d-4ad7-b146-582b398055f2/ip-addresses/9b65104d-debd-4830-8296-3cb87509d293"
    ],
    "name": "IP Address Allocation Task",
    "id": "ab726e31-e909-4bcc-87ef-5139294eb26a",
    "selfLink": "/iaas/api/request-tracker/ab726e31-e909-4bcc-87ef-5139294eb26a"
}
  • This is an example of the response when four IP addresses are requested and allocated.
    {
    "progress": 100,
    "status": "FINISHED",
    "resources": [
        "/iaas/api/network-ip-ranges/703a02df-3b6d-4ad7-b146-582b398055f2/ip-addresses/a4cceea7-3a94-439b-99fa-420774e61eba",
        "/iaas/api/network-ip-ranges/703a02df-3b6d-4ad7-b146-582b398055f2/ip-addresses/4c492669-5ec2-4465-992b-c9c252edf052",
        "/iaas/api/network-ip-ranges/703a02df-3b6d-4ad7-b146-582b398055f2/ip-addresses/0ce9ee20-1a40-460d-80df-fb1791fbd42a",
        "/iaas/api/network-ip-ranges/703a02df-3b6d-4ad7-b146-582b398055f2/ip-addresses/d7d876b6-92b1-4530-a305-d586c8474f11"
    ],
    "name": "IP Address Allocation Task",
    "id": "ab726e31-e909-4bcc-87ef-5139294eb26a",
    "selfLink": "/iaas/api/request-tracker/ab726e31-e909-4bcc-87ef-5139294eb26a"
}

    To get an IP address, query for the details of an allocated resource. The following example queries for the details of the resource with IP address ID a4cceea7-3a94-439b-99fa-420774e61eba.

    curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token" "$url/iaas/api/network-ip-ranges/$ip_range_id/ip-addresses/a4cceea7-3a94-439b-99fa-420774e61eba?apiVersion=$api_version"  | jq "."

    The response provides details about the resource including the allocated IP address and IP version. " ipAllocationType": "USER" indicates that an Automation Assembler administrator manually reserved the IP address.

    {
            "ipAddress": "196.192.2.20",
            "ipAddressDecimalValue": 168561941,
            "ipVersion": "IPv4",
            "ipAddressStatus": "ALLOCATED",
            "ipAllocationType": "USER",
            "id": "439f9c9b-2b2f-484d-8867-2d7b541ddeec",
            "createdAt": "2023-02-22",
            "updatedAt": "2023-02-22",
            "orgId": "8040fbde-5ff0-41f3-a8a1-9e25a3311be2",
            "_links": {
                "network-ip-range": {
                    "href": "/iaas/api/network-ip-ranges/703a02df-3b6d-4ad7-b146-582b398055f2"
                },
                "self": {
                    "href": "/iaas/api/network-ip-ranges/703a02df-3b6d-4ad7-b146-582b398055f2/ip-addresses/439f9c9b-2b2f-484d-8867-2d7b541ddeec"
                },
                "connected-resource": {
                    "href": "/iaas/api/machines/81633fba-e86b-4bfa-a06f-3c4f7a754568/network-interfaces/1c26b194-2862-4d7e-be9c-9881d6cdb871"
                }
            }
        }
    ]
}

What to do next

If you no longer need allocated IP addresses, you can release them. See Release IP Addresses.