To create an IPAM .zip package for use with your specific provider, download and use the external IPAM SDK vra-third-party-ipam-sdk as described in the following process.

The related procedure for creating ABX actions in Automation Assembler is described in the following product documentation topics:

Prerequisites

To use the external IPAM SDK, you must install and configure the following software. You can use a higher version of each, provided that the version is backward compatible.
  • Java 8.
  • Maven 3. Used for packaging the IPAM zip.
  • Python 3. The IPAM plug-in is based on Python.
  • Docker. Used to collect the Python dependency libraries needed by the IPAM plug-in.
  • Internet access. The IPAM SDK relies on Maven Central, Docker HUB & PIP during packaging time. Internet access is not required at runtime.

Step 1: Download the IPAM Integration SDK

Download the most recent VMware Aria Automation Third-Party IPAM SDK from the VMware Developer site: A README file with needed instructions is supplied with the IPAM SDK download. The README file content is summarized in the following steps.

Step 2: Package the scripts

Maven and Docker are used during build time to package the Python scripts into an IPAM .zip distribution. Maven enables the building of the IPAM package to be platform independent. This allows integrators to develop their IPAM integration solution under any Java-enabled operating system. Docker is used during build time to start up a Photon OS container. All 3rd party libraries that the IPAM plugin depends on are downloaded during build time, using PIP, from within the Photon operating system Docker container. This guarantees that all Python library binaries are compiled correctly for the Photon operating system, which is the operating system of the Running Environment that executes the IPAM Python actions.

  1. Open the pom.xml, which resides in the root directory, and modify the following properties:
    <provider.name>SampleIPAM</provider.name> <provider.description>Sample
IPAM integration for vRA</provider.description>
<provider.version>0.1</provider.version>
    Replace the property values with the name, description, and version of your choice. The provider.name is used as a display name in VMware Aria Automation when you deploy the plugin zip, along with the description and version.
  2. Update the logo.png file with the logo icon of your company.

    VMware Aria Automation uses the logo.png file located in the ./src/main/resources folder when displaying the IPAM endpoints that you create by using this package.

  3. (Optional) Change the IPAM Integration endpoint custom form.

    Do this by modifying the endpoint-schema.json file in the ./src/main/resources folder. This .json file contains the custom form definition that renders the IPAM provider's specific fields during IPAM endpoint registration. You can change the form, but the file must contain entries for the privateKey and privateKeyId fields.

    Note: The registration.yaml file also resides in the ./src/main/resources folder. It contains meta information about the contents of the package. Do not change anything in the registration.yaml file.

  4. From the root directory, run the following command: 
    run mvn package -PcollectDependencies

    This produces a SampleIPAM-with-dependencies.zip file under the ./target folder. The zip file is ready to be deployed into VMware Aria Automation.

    The first time that you run this command, it can take several minutes to complete packaging the IPAM zip file. The first time the script runs, it attempts to collect any required third party Python libraries, such as requests and pyopenssh.

    Subsequent runs of the mvn package command do not trigger another collection of third party libraries. To re-trigger the collection of these dependencies, you must provide the -PcollectDependencies option in the command line.

The SampleIPAM-with-dependencies.zip IPAM package is now ready to use.

You can test the IPAM package by uploading it in VMware Aria Automation and create an IPAM integration. Check that expected actions are triggered and are executing successfully. For example, create a new IPAM endpoint and choose the package you uploaded in the Provider dropdown, enter an arbitrary username and password, enter httpbin.org as a Hostname and click Validate. You see the Validate Endpoint action is triggered in the Extensibility tab. It must complete successfully.

Step 3: Get familiar with the IPAM operations and their skeleton implementations

After checking that the packaging of the sample IPAM scripts works, you can start exploring the code. In the ./src/main/python folder, there is a separate directory for each IPAM-specific operation that the plug-in supports.

Operation name Description Script Required
Allocate IP Allocates the next available IP for a VM. ./src/main/python/allocate_ip/source.py Yes
Deallocate IP Deallocates an already allocated IP. ./src/main/python/deallocate_ip/source.py Yes
Get IP Ranges Data collects IP ranges and networks from the IPAM provider. ./src/main/python/get_ip_ranges/source.py Yes
Update Record Updates the created host record. Could be used to update MAC address of VM after it has been provisioned. ./src/main/python/update_record/source.py No
Validate Endpoint Validates that the IPAM endpoint credentials are valid and that a connection to the external IPAM system can be established successfully ./src/main/python/validate_endpoint/source.py Yes
Allocate IP Range Creates network inside some of the specified IP blocks. ./src/main/python/allocate_ip_range/source.py No
Deallocate IP Range Deletes an already allocated network. ./src/main/python/deallocate_ip_range/source.py No
Get IP Blocks Data collects IP blocks ./src/main/python/get_ip_blocks/source.py No

The ./src/main/python/**/source.py scripts contain the Python source code that would be used by VMware Aria Automation to perform the respective IPAM operation.

Each script defines a def handler(context, inputs): function that is the entry point into the IPAM operation.

The VMware Aria Automation IPAM framework calls the respective operation's handler function, passing request specific inputs in the form of a Python dictionary. The request also includes a context object that can be used to securely connect to VMware Aria Automation and call its services.

Step 4: Implement the IPAM operations

You can implement the def handler(context, inputs): function of each IPAM operation's source.py script but you must adhere to the contract defined in the Baseline contract between Automation Assembler IPAM service and external IPAM providers section of this document.

Implementing the operations from scratch is not advised. Instead, use the vra_ipam_utils library located in ./src/main/python/commons/vra_ipam_utils.

This library contains utility functions and classes to help with your def handler(context, inputs): implementation.

The source.py code uses the vra_ipam_utils library, so you can refer to it as reference: 
def handler(context, inputs):
    ipam = IPAM(context, inputs)
    IPAM.do_validate_endpoint = do_validate_endpoint
    return ipam.validate_endpoint()
def do_validate_endpoint(self, auth_credentials, cert):
    # Your implemention goes here
    ...

To implement an operation, add your specific logic in the places indicated by the comments in the corresponding source.py file.

Tip: Build the package, upload it in VMware Aria Automation, and test it after implementing each operation.
Implement the IPAM operations sequentially in the following order:
  1. Validate Endpoint
  2. Get IP Ranges
  3. Get IP Blocks (Optional)
  4. Allocate IP
  5. Allocate IP Range (Optional)
  6. Deallocate IP
  7. Deallocate IP Range (Optional)
  8. Update Record (Optional)
You can execute REST calls against in VMware Aria Automation from within the Python scripts by using the context object in your handler: 
context.request(link='/iaas/api/machines', operation='GET', body='')

The context is configured to handle request authentication, authorization, and proxy needs.

The GetIPRanges and GetIPBlocks actions can only be run by a provisioning service user. All other actions can be run by the user who deployed the cloud template or catalog item.

Requests that are run by the context object are initiated on behalf of the user who started the action event in VMware Aria Automation. When using '/iaas/api/machines' calls, there are two options available:
  1. Option 1. The provisioning user starts an enumeration action such as GetIPRanges or GetIPBlocks.
  2. Option 2. The user that initiated the provisioning request (for example, the administrator or Automation Service Broker user or the Automation Assembler user who deployed the cloud template or catalog item) starts a validate, allocate, deallocate, or update action.

User rights information for the action request appears in the context.request within the Started by (or triggeredBy) field. API requests are validated based on user rights. For example, an action request run by an Automation Service Broker user who lacks admin rights fails because the API requires the user to have admin rights. But the provisioning user, or admin user, who has admin rights can successfully run the action request because they have the required admin rights.

Step 5: Define third party libraries (if needed)

To use third party Python libraries in the source.py scripts, define them in the requirements.txt file located next to each IPAM operation's source.py script.

The plug-in build script downloads the dependency libraries that are defined in the requirements.txt file and package them in the correct format within the IPAM .zip file.

Always re-run the mvn package -PcollectDependencies command every time you add or remove a new dependency from the requirements.txt file.

The requirements.txt format is defined at https://pip.readthedocs.io/en/1.1/requirements.html.

Step 6: Change specific properties in the pom.xml file (if needed)

There are several optional operations.
A. Implement the optional Update Record operation

You can implement the Update Record operation. This operation is used by the IPAM service to notify the external IPAM system that a VM has been successfully provisioned. It is also used to propagate the VM's MAC address to the IPAM system.

Support of this optional operation is controlled by the following property in the pom.xml file: 
<provider.supportsUpdateRecord>true</provider.supportsUpdateRecord>
Changing this value to false excludes update operation from the IPAM .zip package.
Note: If you change the setting from false to true, you must re-run the mvn package - PcollectDependencies command to collect the required dependencies.
B. Implement the optional Get IP Blocks, Allocate IP Range, and Deallocate IP Range operations

These three operations are part of the extended IPAM plugin specification for VMware Aria Automation. They enable the plug-in to support provisioning of on-demand networks from VMware Aria Automation.

When a VMware Aria Automation user requests provisioning for an on-demand network, a CIDR for that network is allocated from the plug-in along, along with other network settings such as default gateway.

Support for these operations is controlled by the following property in the pom.xml file: 
<provider.supportsOnDemandNetworks>false</provider.supportsOnDemandNetworks>
Changing the setting to true forces the build to include the get_ip_blocks, allocate_ip_range, and deallocate_ip_range operations inside the IPAM zip package.
Note: If you change the setting from false to true, you must re-run the mvn package - PcollectDependencies command to collect the required dependencies.
C. Support address spaces
External IPAM networks and ranges can be organized into logical groups with overlapping address spaces, serving a single routing domain. By default, the sample IPAM .zip that this SDK produces is configured to not support address spaces. If your IPAM system supports address spaces, you can enable support for address spaces by changing the following property in the pom.xml file: 
<provider.supportsAddressSpaces>true</provider.supportsAddressSpaces>

Step 7: Build the package with the implemented IPAM

It is a good idea to deploy the package to VMware Aria Automation and test the operations after implementing each IPAM operation. Build the package by running mvn package or mvn package - PcollectDependencies. After you implement and test all the operations, the IPAM package is ready to be distributed and used.

Troubleshooting

The following list contains the most common errors that might occur during build time:
  1. The mvn package build fails with the following message: 
    [ERROR] Plugin org.apache.maven.plugins:maven-resources-plugin:3.1.0 or
one of its dependencies could not be resolved: Failed to read artifact
descriptor for org.apache.maven.plugins:maven-resourcesplugin:jar:3.1.0: Could not transfer artifact
org.apache.maven.plugins:maven-resources-plugin:pom:3.1.0 from/to
central (https://repo.maven.apache.org/maven2): repo.maven.apache.org:
Unknown host repo.maven.apache.org -> [Help 1]

    Resolution: The connection to Maven Central may have timed out or failed. Retry after a couple of minutes. If the issue persists, check your internet connection.

  2. The mvn package -PcollectDependencies build fail with the following message:
    [ERROR] DOCKER> Unable to pull 'vmware/photon2:20180424' : error
pulling image configuration: Get
https://production.cloudflare.docker.com/registryv2/docker/registry/v2/blobs/sha256/12/1204ad97f071063bea855f351348e15e9
cc03610cbfc8df46ab96b42d7cafa9f/data?verify=1578042999-
Nu9yKJgKQcuFU0Y9hAQe%2BKEOKGo%3D: dial tcp: lookup
production.cloudflare.docker.com on XXX:53: read udp XXX:57798->XXX:53:
i/o timeout

    Resolution: The connection to the Docker Registry may have timed out or failed. Retry after a couple of minutes. If the issue persists, check your internet connection.

  3. The mvn package -PcollectDependencies build on Windows fails with the following message: 
    [ERROR] Failed to execute goal io.fabric8:docker-mavenplugin:0.31.0:start (start-container) on project sample-ipam: I/O
Error: Unable to create container for [ipam-dependency-collector:latest] : Drive has not been shared (Internal Server Error:
500)

    Resolution: The build script uses Docker to collect the Python dependencies that are needed by the plug-in. For Docker to operate correctly, it needs access to the Windows drive that the build script resides in. For information, see Configure shared volume on Docker for Windows.

  4. The mvn package -PcollectDependencies build fails with the following message:
    [INFO] --- docker-maven-plugin:0.31.0:start (start-container) @ sampleipam --- [ERROR] DOCKER> Error occurred during container startup,
shutting down... [ERROR] DOCKER> I/O Error [Unable to create container
for [ipam-dependency-collector:latest] : {"message":"Conflict. The
container name "/ipam-dependency-collector-1" is already in use by
container
"2bfb215381514cd6496ecd5d0103da0a4d94034c5691b25bdf27b16bd2236022". You
have to remove (or rename) that container to be able to reuse that
name."} (Conflict: 409)]
    Resolution: Run the run docker ps -a command. The output must be similar to the following: 
    | CONTAINER ID | IMAGE | COMMAND | CREATED | STATUS | PORTS | NAMES | -
----------- | ----- | ------- | ------- | ------ | ----- | ---- | |
2bfb21538151 | d886e9bba96e | "/bin/sh -c 'yes | c…" | 3 minutes ago |
Exited (0) 3 minutes ago | | ipam-dependency-collector-1
    Locate the container named ipam-dependency-collector-* and remove it be using the run docker rm -f 2bfb21538151 command.
  5. The mvn package -PcollectDependencies build fails with the following message:
    [INFO] --- docker-maven-plugin:0.31.0:build (build-image) @ sample-ipam
--- [INFO] Building tar: ...\sample-abx-integration\target\docker\ipamdependency-collector\latest\tmp\docker-build.tar [INFO] DOCKER> [ipamdependency-collector:latest]: Created docker-build.tar in 214
milliseconds [ERROR] DOCKER> Unable to build image [ipam-dependencycollector:latest] : "The command '/bin/sh -c tdnf install -y python3-
3.6.5-1.ph2 python3-pip-3.6.5-1.ph2 shadow && pip3 install --upgrade
pip setuptools && pip3 install certifi' returned a non-zero code: 127" 
["The command '/bin/sh -c tdnf install -y python3-3.6.5-1.ph2 python3-
pip-3.6.5-1.ph2 shadow && pip3 install --upgrade pip setuptools && pip3
install certifi' returned a non-zero code: 127" ]

    Resolution: The tdnf Photon OS package manager may have failed to install Python3 due to connectivity errors. Retry after a couple of minutes. If the issue persists, check your internet connection.