💻 [runtimeterror $]

2021-02-22 ~ 2022-07-25

Integrating {php}IPAM with vRealize Automation 8

In a previous post [1], I described some of the steps I took to stand up a homelab including vRealize Automation (vRA) on an Intel NUC 9. One of my initial goals for that lab was to use it for developing and testing a way for vRA to leverage phpIPAM [2] for static IP assignments. The homelab worked brilliantly for that purpose, and those extra internal networks were a big help when it came to testing. I was able to deploy and configure a new VM to host the phpIPAM instance, install the VMware vRealize Third-Party IPAM SDK [3] on my Chromebook's Linux environment [4], develop and build the integration component, import it to my vRA environment, and verify that deployments got addressed accordingly.

[1] previous post

[2] phpIPAM

[3] VMware vRealize Third-Party IPAM SDK

[4] Chromebook's Linux environment

The resulting integration is available on Github here [5]. This was actually the second integration I'd worked on, having fumbled my way through a Solarwinds integration [6] earlier last year. VMware's documentation [7] on how to build these things is pretty good, but I struggled to find practical information on how a novice like me could actually go about developing the integration. So maybe these notes will be helpful to anyone seeking to write an integration for a different third-party IP Address Management solution.

[5] here

[6] Solarwinds integration

[7] VMware's documentation

If you'd just like to import a working phpIPAM integration into your environment without learning how the sausage is made, you can grab my latest compiled package here [8]. You'll probably still want to look through Steps 0-2 to make sure your IPAM instance is set up similarly to mine.

[8] here

Step 0: phpIPAM installation and base configuration

Before even worrying about the SDK, I needed to get a phpIPAM instance ready [9]. I started with a small (1vCPU/1GB RAM/16GB HDD) VM attached to my "Home" network (`192.168.1.0/24`). I installed Ubuntu 20.04.1 LTS, and then used this guide [10] to install phpIPAM.

[9] get a phpIPAM instance ready

[10] this guide

Once phpIPAM was running and accessible via the web interface, I then used `openssl` to generate a self-signed certificate to be used for the SSL API connection:

I edited the apache config file to bind that new certificate on port 443, and to redirect requests on port 80 to port 443:

After restarting apache, I verified that hitting `http://ipam.lab.bowdre.net` redirected me to `https://ipam.lab.bowdre.net`, and that the connection was secured with the shiny new certificate.

Remember how I've got a "Home" network as well as several internal networks [11] which only exist inside the lab environment? I dropped the phpIPAM instance on the Home network to make it easy to connect to, but it doesn't know how to talk to the internal networks where vRA will actually be deploying the VMs. So I added a static route to let it know that traffic to `172.16.0.0/16` would have to go through the Vyos router at `192.168.1.100`.

[11] several internal networks

This is Ubuntu, so I edited `/etc/netplan/99-netcfg-vmware.yaml` to add the `routes` section at the bottom:

I then ran `sudo netplan apply` so the change would take immediate effect and confirmed the route was working by pinging the vCenter's interface on the `172.16.10.0/24` network:

Now would also be a good time to go ahead and enable cron jobs so that phpIPAM will automatically scan its defined subnets for changes in IP availability and device status. phpIPAM includes a pair of scripts in `INSTALL_DIR/functions/scripts/`: one for discovering new hosts, and the other for checking the status of previously discovered hosts. So I ran `sudo crontab -e` to edit root's crontab and pasted in these two lines to call both scripts every 15 minutes:

Step 1: Configuring phpIPAM API access

Okay, let's now move on to the phpIPAM web-based UI to continue the setup. After logging in at `https://ipam.lab.bowdre.net/`, I clicked on the red **Administration** menu at the right side and selected **phpIPAM Settings**. Under the **Site Settings** section, I enabled the *Prettify links* option, and under the **Feature Settings** section I toggled on the *API* component. I then hit *Save* at the bottom of the page to apply the changes.

Next, I went to the **Users** item on the left-hand menu to create a new user account which will be used by vRA. I named it `vra`, set a password for the account, and made it a member of the `Operators` group, but didn't grant any special module access.

Image: Creating vRA service account in phpIPAM

Image: Creating vRA service account in phpIPAM

The last step in configuring API access is to create an API key. This is done by clicking the **API** item on that left side menu and then selecting *Create API key*. I gave it the app ID `vra`, granted Read/Write permissions, and set the *App Security* option to "SSL with User token".

Image: Generating the API key

Once we get things going, our API calls will authenticate with the username and password to get a token and bind that to the app ID.

Step 2: Configuring phpIPAM subnets

Our fancy new IPAM solution is ready to go - except for the whole bit about managing IPs. We need to tell it about the network segments we'd like it to manage. phpIPAM uses "Sections" to group subnets together, so we start by creating a new Section at **Administration > IP related management > Sections**. I named my new section `Lab`, and pretty much left all the default options. Be sure that the `Operators` group has read/write access to this section and the subnets we're going to create inside it!

Image: Creating a section to hold the subnets

We should also go ahead and create a Nameserver set so that phpIPAM will be able to tell its clients (vRA) what server(s) to use for DNS. Do this at **Administration > IP related management > Nameservers**. I created a new entry called `Lab` and pointed it at my internal DNS server, `192.168.1.5`.

Image: Designating the nameserver

Okay, we're finally ready to start entering our subnets at **Administration > IP related management > Subnets**. For each one, I entered the Subnet in CIDR format, gave it a useful description, and associated it with my `Lab` section. I expanded the *VLAN* dropdown and used the *Add new VLAN* option to enter the corresponding VLAN information, and also selected the Nameserver I had just created.

Image: Entering the first subnet

I also enabled the options ~~*Mark as pool*~~, *Check hosts status*, *Discover new hosts*, and *Resolve DNS names*.

Image: Subnet options

<-- note -->

Since releasing this integration, I've learned that phpIPAM intends for the `isPool` field to identify networks where the entire range (including the subnet and broadcast addresses) are available for assignment. As a result, I no longer recommend using that field. Instead, consider creating a custom field [12] for tagging networks for vRA availability.

<-- /note -->

[12] creating a custom field

I then used the *Scan subnets for new hosts* button to run a discovery scan against the new subnet.

Image: Scanning for new hosts

The scan only found a single host, `172.16.20.1`, which is the subnet's gateway address hosted by the Vyos router. I used the pencil icon to edit the IP and mark it as the gateway:

Image: Identifying the gateway

phpIPAM now knows the network address, mask, gateway, VLAN, and DNS configuration for this subnet - all things that will be useful for clients seeking an address. I then repeated these steps for the remaining subnets.

Image: More subnets!

Now for the *real* fun!

Step 3: Testing the API

Before moving on to developing the integration, it would be good to first get a little bit familiar with the phpIPAM API - and, in the process, validate that everything is set up correctly. First I read through the API documentation [13] and some example API calls [14] to get a feel for it. I then started by firing up a `python3` interpreter and defining a few variables as well as importing the `requests` module for interacting with the REST API:

Based on reading the API docs, I'll need to use the username and password for initial authentication which will provide me with a token to use for subsequent calls. So I'll construct the URI used for auth, submit a `POST` to authenticate, verify that the authentication was successful (`status_code == 200`), and take a look at the response to confirm that I got a token. (For testing, I'm calling `requests` with `verify=False`; we'll be able to use certificate verification when these calls are made from vRA.)

Sweet! There's our token! Let's save it to `token` to make it easier to work with:

Let's see if we can use our new token against the `subnets` controller to get a list of subnets known to phpIPAM:

Nice! Let's make it a bit more friendly:

We're in business!

[13] API documentation

[14] example API calls

Now that I know how to talk to phpIPAM via its RESP API, it's time to figure out how to get vRA to speak that language.

Step 4: Getting started with the vRA Third-Party IPAM SDK

I downloaded the SDK from here [15]. It's got a pretty good README [16] which describes the requirements (Java 8+, Maven 3, Python3, Docker, internet access) as well as how to build the package. I also consulted this white paper [17] which describes the inputs provided by vRA and the outputs expected from the IPAM integration.

[15] here

[16] README

[17] this white paper

The README tells you to extract the .zip and make a simple modification to the `pom.xml` file to "brand" the integration:

You can then kick off the build with `mvn package -PcollectDependencies -Duser.id=${UID}`, which will (eventually) spit out `./target/phpIPAM.zip`. You can then import the package to vRA [18] and test it against the `httpbin.org` hostname to validate that the build process works correctly.

[18] import the package to vRA

You'll notice that the form includes fields for Username, Password, and Hostname; we'll also need to specify the API app ID. This can be done by editing `./src/main/resources/endpoint-schema.json`. I added an `apiAppId` field:

<-- note -->

Check out the source on GitHub [19] to see how I adjusted the schema to support custom field input.

<-- /note -->

[19] source on GitHub

We've now got the framework in place so let's move on to the first operation we'll need to write. Each operation has its own subfolder under `./src/main/python/`, and each contains (among other things) a `requirements.txt` file which will tell Maven what modules need to be imported and a `source.py` file which is where the magic happens.

Step 5: 'Validate Endpoint' action

We already basically wrote this earlier with the manual tests against the phpIPAM API. This operation basically just needs to receive the endpoint details and credentials from vRA, test the connection against the API, and let vRA know whether or not it was able to authenticate successfully. So let's open `./src/main/python/validate_endpoint/source.py` and get to work.

It's always a good idea to start by reviewing the example payload section so that we'll know what data we have to work with:

The `do_validate_endpoint` function has a handy comment letting us know that's where we'll drop in our code:

The example code gives us a nice start at how we'll get our inputs from vRA. So let's expand that a bit:

As before, we'll construct the "base" URI by inserting the `hostname` and `apiAppId`, and we'll combine the `username` and `password` into our `auth` variable:

I realized that I'd be needing to do the same authentication steps for each one of these operations, so I created a new `auth_session()` function to do the heavy lifting. Other operations will also need to return the authorization token but for this run we really just need to know whether the authentication was successful, which we can do by checking `req.status_code`.

And we'll call that function from `do_validate_endpoint()`:

You can view the full code here [20].

[20] here

After completing each operation, run `mvn package -PcollectDependencies -Duser.id=${UID}` to build again, and then import the package to vRA again. This time, you'll see the new "API App ID" field on the form:

Image: Validating the new IPAM endpoint

Confirm that everything worked correctly by hopping over to the **Extensibility** tab, selecting **Action Runs** on the left, and changing the **User Runs** filter to say *Integration Runs*.

Image: Extensibility action runs

Select the newest `phpIPAM_ValidateEndpoint` action and make sure it has a happy green *Completed* status. You can also review the Inputs to make sure they look like what you expected:

And we can see that the Outputs reflect our successful result:

That's one operation in the bank!

Step 6: 'Get IP Ranges' action

So vRA can authenticate against phpIPAM; next, let's actually query to get a list of available IP ranges. This happens in `./src/main/python/get_ip_ranges/source.py`. We'll start by pulling over our `auth_session()` function and flesh it out a bit more to return the authorization token:

We'll then modify `do_get_ip_ranges()` with our needed variables, and then call `auth_session()` to get the necessary token:

We can then query for the list of subnets, just like we did earlier:

Request list of subnets

subnet_uri = f'{uri}/subnets/'

if enableFilter == "true":

queryFilter = f'filter_by={filterField}&filter_value={filterValue}'

logging.info(f"Searching for subnets matching filter: {queryFilter}")

else:

queryFilter = ''

logging.info(f"Searching for all known subnets")

ipRanges = []

subnets = requests.get(f'{subnet_uri}?{queryFilter}', headers=token, verify=cert)

subnets = subnets.json()['data']

ipRange['id'] = str(subnet['id'])

ipRange['description'] = str(subnet['description'])

ipRange['subnetPrefixLength'] = str(subnet['mask'])

ipRange['name'] = f"{str(subnet['subnet'])}/{str(subnet['mask'])}"

network = ipaddress.ip_network(str(subnet['subnet']) + '/' + str(subnet['mask']))

ipRange['ipVersion'] = 'IPv' + str(network.version)

ipRange['startIPAddress'] = str(network[1])

ipRange['endIPAddress'] = str(network[-2])

try:

ipRange['dnsServerAddresses'] = [server.strip() for server in str(subnet['nameservers']['namesrv1']).split(';')]

except:

ipRange['dnsServerAddresses'] = []

gw_req = requests.get(f"{subnet_uri}/{subnet['id']}/addresses/?filter_by=is_gateway&filter_value=1", headers=token, verify=cert)

if gw_req.status_code == 200:

gateway = gw_req.json()['data'][0]['ip']

ipRange['gatewayAddress'] = gateway

ipRanges.append(ipRange)

for subnet in subnets:

ipRange = {}

ipRange['id'] = str(subnet['id'])

ipRange['name'] = f"{str(subnet['subnet'])}/{str(subnet['mask'])}"

ipRange['description'] = str(subnet['description'])

logging.info(f"Found subnet: {ipRange['name']} - {ipRange['description']}.")

network = ipaddress.ip_network(str(subnet['subnet']) + '/' + str(subnet['mask']))

ipRange['ipVersion'] = 'IPv' + str(network.version)

ipRange['startIPAddress'] = str(network[1])

ipRange['endIPAddress'] = str(network[-2])

ipRange['subnetPrefixLength'] = str(subnet['mask'])

return empty set if no nameservers are defined in IPAM

try:

ipRange['dnsServerAddresses'] = [server.strip() for server in str(subnet['nameservers']['namesrv1']).split(';')]

except:

ipRange['dnsServerAddresses'] = []

try to get the address marked as the gateway in IPAM

gw_req = requests.get(f"{subnet_uri}/{subnet['id']}/addresses/?filter_by=is_gateway&filter_value=1", headers=token, verify=cert)

if gw_req.status_code == 200:

gateway = gw_req.json()['data'][0]['ip']

ipRange['gatewayAddress'] = gateway

logging.debug(ipRange)

ipRanges.append(ipRange)

Return results to vRA

result = {

"ipRanges" : ipRanges

}

return result

[2021-02-21 23:14:04,026] [INFO] - Querying for auth credentials

[2021-02-21 23:14:04,051] [INFO] - Credentials obtained successfully!

[2021-02-21 23:14:04,089] [INFO] - Found subnet: 172.16.10.0/24 - 1610-Management.

[2021-02-21 23:14:04,101] [INFO] - Found subnet: 172.16.20.0/24 - 1620-Servers-1.

[2021-02-21 23:14:04,114] [INFO] - Found subnet: 172.16.30.0/24 - 1630-Servers-2.

[2021-02-21 23:14:04,126] [INFO] - Found subnet: 172.16.40.0/24 - 1640-Servers-3.

[2021-02-21 23:14:04,138] [INFO] - Found subnet: 172.16.50.0/24 - 1650-Servers-4.

[2021-02-21 23:14:04,149] [INFO] - Found subnet: 172.16.60.0/24 - 1660-Servers-5.

def auth_session(uri, auth, cert):

auth_uri = f'{uri}/user/'

req = requests.post(auth_uri, auth=auth, verify=cert)

if req.status_code != 200:

raise requests.exceptions.RequestException('Authentication Failure!')

token = {"token": req.json()['data']['token']}

return token

def do_allocate_ip(self, auth_credentials, cert):

Build variables

username = auth_credentials["privateKeyId"]

password = auth_credentials["privateKey"]

hostname = self.inputs["endpoint"]["endpointProperties"]["hostName"]

apiAppId = self.inputs["endpoint"]["endpointProperties"]["apiAppId"]

uri = f'https://{hostname}/api/{apiAppId}/'

auth = (username, password)

Auth to API

token = auth_session(uri, auth, cert)

bundle = {

'uri': uri,

'token': token,

'cert': cert

}

allocation_result = []

try:

resource = self.inputs["resourceInfo"]

for allocation in self.inputs["ipAllocations"]:

allocation_result.append(allocate(resource, allocation, self.context, self.inputs["endpoint"], bundle))

except Exception as e:

try:

rollback(allocation_result, bundle)

except Exception as rollback_e:

logging.error(f"Error during rollback of allocation result {str(allocation_result)}")

logging.error(rollback_e)

raise e

def allocate(resource, allocation, context, endpoint, bundle):

last_error = None

for range_id in allocation["ipRangeIds"]:

logging.info(f"Allocating from range {range_id}")

try:

return allocate_in_range(range_id, resource, allocation, context, endpoint, bundle)

except Exception as e:

last_error = e

logging.error(f"Failed to allocate from range {range_id}: {str(e)}")

logging.error("No more ranges. Raising last error")

raise last_error

def allocate_in_range(range_id, resource, allocation, context, endpoint, bundle):

if int(allocation['size']) ==1:

vmName = resource['name']

owner = resource['owner']

uri = bundle['uri']

token = bundle['token']

cert = bundle['cert']

else:

TODO: implement allocation of continuous block of IPs

pass

raise Exception("Not implemented")

payload = {

'hostname': vmName,

'description': f'Reserved by vRA for {owner} at {datetime.now()}'

}

allocate_uri = f'{uri}/addresses/first_free/{str(range_id)}/'

allocate_req = requests.post(allocate_uri, data=payload, headers=token, verify=cert)

allocate_req = allocate_req.json()

if allocate_req['success']:

version = ipaddress.ip_address(allocate_req['data']).version

result = {

"ipAllocationId": allocation['id'],

"ipRangeId": range_id,

"ipVersion": "IPv" + str(version),

"ipAddresses": [allocate_req['data']]

}

logging.info(f"Successfully reserved {str(result['ipAddresses'])} for {vmName}.")

else:

raise Exception("Unable to allocate IP!")

return result

def rollback(allocation_result, bundle):

uri = bundle['uri']

token = bundle['token']

cert = bundle['cert']

for allocation in reversed(allocation_result):

logging.info(f"Rolling back allocation {str(allocation)}")

ipAddresses = allocation.get("ipAddresses", None)

for ipAddress in ipAddresses:

rollback_uri = f'{uri}/addresses/{allocation.get("id")}/'

requests.delete(rollback_uri, headers=token, verify=cert)

return

[2021-02-22 01:31:41,729] [INFO] - Querying for auth credentials

[2021-02-22 01:31:41,757] [INFO] - Credentials obtained successfully!

[2021-02-22 01:31:41,773] [INFO] - Allocating from range 12

[2021-02-22 01:31:41,790] [INFO] - Successfully reserved ['172.16.40.2'] for BOW-VLTST-XXX41.

def auth_session(uri, auth, cert):

auth_uri = f'{uri}/user/'

req = requests.post(auth_uri, auth=auth, verify=cert)

if req.status_code != 200:

raise requests.exceptions.RequestException('Authentication Failure!')

token = {"token": req.json()['data']['token']}

return token

def do_deallocate_ip(self, auth_credentials, cert):

Build variables

username = auth_credentials["privateKeyId"]

password = auth_credentials["privateKey"]

hostname = self.inputs["endpoint"]["endpointProperties"]["hostName"]

apiAppId = self.inputs["endpoint"]["endpointProperties"]["apiAppId"]

uri = f'https://{hostname}/api/{apiAppId}/'

auth = (username, password)

Auth to API

token = auth_session(uri, auth, cert)

bundle = {

'uri': uri,

'token': token,

'cert': cert

}

deallocation_result = []

for deallocation in self.inputs["ipDeallocations"]:

deallocation_result.append(deallocate(self.inputs["resourceInfo"], deallocation, bundle))

assert len(deallocation_result) > 0

return {

"ipDeallocations": deallocation_result

}

def deallocate(resource, deallocation, bundle):

uri = bundle['uri']

token = bundle['token']

cert = bundle['cert']

ip_range_id = deallocation["ipRangeId"]

ip = deallocation["ipAddress"]

logging.info(f"Deallocating ip {ip} from range {ip_range_id}")

deallocate_uri = f'{uri}/addresses/{ip}/{ip_range_id}/'

requests.delete(deallocate_uri, headers=token, verify=cert)

return {

"ipDeallocationId": deallocation["id"],

"message": "Success"

}

[2021-02-22 01:36:29,438] [INFO] - Querying for auth credentials

[2021-02-22 01:36:29,461] [INFO] - Credentials obtained successfully!

[2021-02-22 01:36:29,476] [INFO] - Deallocating ip 172.16.40.3 from range 12

{

"ipDeallocations": [

{

"message": "Success",

"ipDeallocationId": "/resources/network-interfaces/8e149a2c-d7aa-4e48-b6c6-153ed288aef3"

}

]

}