Merge pull request #8 from mpoore/dev

0.1.1

Author: mpoore

README.md

@@ -1 +1,41 @@
-# phpipam-vcf-automation
+# phpIPAM integration for VMware VCF Automation 8.x
+
+This integration allows VMware VCF Automation 8.x to use [phpIPAM](https://phpipam.net) for assigning static IP addresses to provisioned virtual machines and on-demand networks.
+
+## About VMware VCF Automation
+
+VMware VCF Automation (formerly known as VMware Aria Automation and vRealize Automation) is VMware’s enterprise-grade platform for automating the deployment, configuration, and lifecycle management of cloud and on-premises infrastructure. It enables organizations to deliver infrastructure and application services consistently and at scale, leveraging policy-based governance and self-service capabilities.
+
+A feature of VCF Automation is its integration with IP Address Management (IPAM) solutions, such as phpIPAM or Infoblox, allowing automated allocation, tracking, and management of IP addresses during the provisioning of virtual networks and workloads. This ensures IP consistency, avoids conflicts, and streamlines network automation workflows within VMware Cloud Foundation (VCF) environments.
+
+## About phpIPAM
+
+[phpIPAM](https://phpipam.net/) is an open-source IP address management (IPAM) solution designed to help organizations efficiently manage and track their IPv4 and IPv6 address space. Built with PHP, MySQL, and jQuery, it provides a modern and user-friendly web interface for managing subnets, IP addresses, VLANs, VRFs, and related network resources.
+
+phpIPAM is lightweight, easy to deploy, and integrates well with network automation workflows, making it ideal for both small labs and large-scale enterprise environments.
+
+- [phpIPAM documentation](https://phpipam.net/documents/all-documents/)
+- [phpIPAM REST API documentation](https://phpipam.net/api/api_documentation/)
+
+## Documentation
+Documentation for this integration and its use in conjunction with VCF Automation and phpIPAM is available in the docs folder. The documentation is not intended to provide detailed guidance for either VCF Automation or phpIPAM beyond the scope of this integration.
+
+The following documentation pages are available:
+- [Installation](docs/install.md) - How to download and install this integration.
+- [Prerequisites](docs/prerequisites.md) - Preparing phpIPAM to use this integration.
+- [Basic Configuration](docs/configure-basic.md) - Creating a basic connection for VCF Automation to phpIPAM using this integration.
+- [Filter Configuration](docs/configure-filter.md) - Using the filtering functionality to target specific subnets in phpIPAM.
+- [DNS Configuration](docs/configure-dns.md) - Populating DNS related fields in VCF Automation using fields in phpIPAM.
+- [On-Demand Networks](docs/configure-ondemand.md) - Using VCF Automation's on-demand networks capabilities with NSX and phpIPAM.
+- [Troubleshooting](docs/troubleshooting.md) - Some common problem areas and how to investigate them.
+
+## Feedback and Issues
+
+Whilst reasonable efforts have been made to test this integration, problems may still occur. The integration's author offers no warranty for its use. That said, if you do encounter a bug or have an idea for a change or improvement, please feel free to open an [Issue](https://github.com/mpoore/phpipam-vcf-automation/issues) on this repository.
+
+Please include as much information as possible in any created issues, for example:
+- The version of phpIPAM used
+- The version of VCF Automation used
+- The version of this integration used
+- Details of the problem being seen
+- Any relevant log messages from the action runs in VCF Automation (see the [Troubleshooting](docs/troubleshooting.md) documentation page for how to view these)

docs/configure-basic.md

@@ -0,0 +1,47 @@
+# Basic Configuration
+
+A basic, minimal configuration of the phpIPAM integration with VMware VCF Automation is completed as follows and assumes that the provider has already been imported:
+
+1. Login to VCF Automation as a user with administrative privileges to the Assembler component.
+
+2. Navigate to **Infrastructure** > **Integrations**.
+
+3. Click the button to **ADD INTEGRATION**.
+
+![Click the button to ADD INTEGRATION](img/install_addintegration.png)
+
+4. From the list of possible integrations, pick **IPAM**.
+
+![Select the IPAM integration](img/install_addintegration_ipam.png)
+
+5. Enter a unique name for the *New Integration*. Optionally, a description can be entered.
+
+Select the **phpIPAM** integration from the list of available providers.
+
+![Select the IPAM integration and enter a name](img/configure_select_provider.png)
+
+6. The available fields for the integration are displayed along with their default values. The required fields are marked with a red asterisk. They are:
+
+- phpIPAM Hostname
+- phpIPAM API App ID
+- phpIPAM API App Code
+
+![The default options for the provider](img/configure_provider_blank.png)
+
+7. Enter the FQDN of the phpIPAM instance, the App ID, and App Code into the relevant fields.
+
+![The minimum configuration for the provider](img/configure_provider_min.png)
+
+8. Click the **VALIDATE** button to check the connection from VCF Automation to the phpIPAM instance.
+
+The SSL certificate used by phpIPAM may not be trusted. If that is the case, a prompt will be displayed asking for the discovered certificate to be accepted. Click the **ACCEPT** button.
+
+![Accept the untrusted certificate if prompted](img/configure_untrusted_cert.png)
+
+9. If the connection is successful, a green message box is displayed and the **ADD** button will be enabled. Click **ADD** to complete the configuration.
+
+![Click the ADD button to complete the configuration](img/configure_credentials_validated.png)
+
+10. The IPAM integration has now been configured and data collection will occur automatically.
+
+![Configuration is complete](img/configure_integration_added.png)

src/main/resources/dependencies.collected.flag renamed to docs/configure-dns.md

@@ -0,0 +1,59 @@
+# Filter Configuration
+
+Basic configuration of the phpIPAM integration establishes a connection from VMware VCF Automation to phpIPAM and allows VCF Automation to collect information about subnets configured in phpIPAM.
+
+These subnets can be associated with infrastructure networks in *Network Profiles* within VCF Automation and allow it to allocate IP addresses from phpIPAM to provisioned virtual machines. These addresses are released in phpIPAM when the virtual machines are deprovisioned.
+
+By default, the integration will collect data about all defined subnets in phpIPAM that have the IP requests option enabled. The example subnet below has this option turned on and will be available for use to allocate IP addresses from.
+
+Note: Filter configuration affects both subnets collected for virtual machine provisioning *and* subnets collected for on-demand networks.
+
+![An example phpIPAM subnet with 'IP requests' enabled](img/phpipam_example_subnet.png)
+
+If there are a large number of subnets managed by phpIPAM, or there are a limited number of subnets that should be exposed to VCF Automation, then a filter can be set to restrict which subnets are discovered.
+
+## Configuring the Filter
+
+To enable the subnet filtering functionality, the integration's configuration must be changed. This can either be accomplished during it's initial configuration or at a later point. If editing the configuration however, the API App Code will be required to validate the connection and save the configuration changes.
+
+Enabling the filter requires checking the checkbox marked **Enable subnet filter?**.
+
+![Checking the 'Enable subnet filter?' checkbox enables the filter](img/configure_filter1.png)
+
+This then exposes two mandtory fields and one optional field. A default filter configuration is set but can be changed. The effect of the filter is to limit the scope of subnets that are discovered for use by VCF Automation. In the example above, the effect would be to limit discovery to subnets that meet the following two conditions:
+
+1. "IP Requests" is enabled. (This is the default option that the integration always uses and can't be configured.)
+2. "Mark as Pool" is enabled.
+
+The example subnet below in phpIPAM would meet those criteria.
+
+![An example subnet in phpIPAM that meets the default filter criteria](img/configure_filter2.png)
+
+## Selecting a Filter Field
+
+The default filter field, `isPool`, is a built-in field in phpIPAM. The full list of fields available for subnets can be found in phpIPAM's API documentation.
+
+Another option is to use a custom field. Custom fields are defined in phpIPAM against particular types of objects, for example subnets, to extend the data held about each instance of an object.
+
+An example of a custom field might be `tenant`, which is configured in phpIPAM below:
+
+![An example custom field (tenant) that can be filtered on](img/configure_filter3.png)
+
+To filter using this field, its name must be prepended by `custom_` when adding it to the integration's configuration. Filtering can therefore be conducted against any field, built-in or custom, for a subnet.
+
+## Filter Matching
+
+Filter matching is optional, but allows more sophisticated filters to be created. As well as not being set, there are three filter matching options:
+
+| Option       | Behaviour                                        |
+| ------------ | ------------------------------------------------ |
+| none / blank | (Default) The same as FULL, below.               |
+| FULL         | Looks for an exact value match.                  |
+| PARTIAL      | Matches substrings or partial values.            |
+| REGEX        | Treats the filter value as a regular expression. |
+
+Exhaustive testing of the filter functionality has not be conducted and depends on the capabilities exposed by phpIPAM.
+
+## Saving Changes
+
+To save any changes made to the integration's configuration, the API App Code must be re-entered and the connection validated before the changes can be saved.