Merge pull request #599 from nautobot/feat-citrix_integration

Add Citrix ADM Integration

README.md

@@ -27,6 +27,8 @@ The Nautobot SSoT app builds atop the [DiffSync](https://github.com/networktocod
 This Nautobot application framework includes the following integrations:
 
 - Cisco ACI
+- Bootstrap
+- Citrix ADM
 - Arista CloudVision
 - Device42
 - Cisco DNA Center

changes/599.added

@@ -0,0 +1 @@
+Added Citrix ADM integration.

changes/599.fixed

@@ -0,0 +1 @@
+Fixed Bootstrap signals that are using create_or_update_custom_field() to pass apps. This was done to correct bug causing Nautobot to crash during startup.

changes/599.housekeeping

@@ -0,0 +1 @@
+Consolidated repeat function, parse_hostname_for_role(), from DNA Center and Citrix integrations as SSoT utility function.

development/creds.example.env

@@ -31,6 +31,9 @@ NAUTOBOT_ARISTACV_CVP_TOKEN="changeme"
 
 NAUTOBOT_SSOT_DEVICE42_PASSWORD="changeme"
 
+NAUTOBOT_SSOT_CITRIX_ADM_USERNAME="admin"
+NAUTOBOT_SSOT_CITRIX_ADM_PASSWORD="changeme"
+
 NAUTOBOT_SSOT_INFOBLOX_PASSWORD="changeme"
 
 # ACI Credentials.  Append friendly name to the end to identify each APIC. 

development/development.env

@@ -84,6 +84,9 @@ NAUTOBOT_DNAC_SSOT_DNA_CENTER_IMPORT_MERAKIS="False"
 NAUTOBOT_DNAC_SSOT_DNA_CENTER_UPDATE_LOCATIONS="True"
 NAUTOBOT_DNAC_SSOT_DNA_CENTER_SHOW_FAILURES="True"
 
+NAUTOBOT_SSOT_ENABLE_CITRIX_ADM="False"
+NAUTOBOT_SSOT_CITRIX_ADM_UPDATE_SITES="True"
+
 NAUTOBOT_SSOT_ENABLE_INFOBLOX="False"
 NAUTOBOT_SSOT_INFOBLOX_DEFAULT_STATUS="Active"
 NAUTOBOT_SSOT_INFOBLOX_ENABLE_SYNC_TO_INFOBLOX="True"

development/nautobot_config.py

@@ -219,9 +219,11 @@
             "vrf": True,
             "prefix": True,
         },
+        "citrix_adm_update_sites": is_truthy(os.getenv("NAUTOBOT_SSOT_CITRIX_ADM_UPDATE_SITES", "true")),
         "enable_aci": is_truthy(os.getenv("NAUTOBOT_SSOT_ENABLE_ACI")),
         "enable_aristacv": is_truthy(os.getenv("NAUTOBOT_SSOT_ENABLE_ARISTACV")),
         "enable_bootstrap": is_truthy(os.getenv("NAUTOBOT_SSOT_ENABLE_BOOTSTRAP", "false")),
+        "enable_citrix_adm": is_truthy(os.getenv("NAUTOBOT_SSOT_ENABLE_CITRIX_ADM")),
         "enable_device42": is_truthy(os.getenv("NAUTOBOT_SSOT_ENABLE_DEVICE42")),
         "enable_dna_center": is_truthy(os.getenv("NAUTOBOT_SSOT_ENABLE_DNA_CENTER")),
         "enable_infoblox": is_truthy(os.getenv("NAUTOBOT_SSOT_ENABLE_INFOBLOX")),

docs/admin/integrations/citrix_adm_setup.md

@@ -0,0 +1,52 @@
+# Citrix ADM Integration Setup
+
+This guide will walk you through the steps to set up Citrix ADM integration with the `nautobot_ssot` app.
+
+## Prerequisites
+
+Before configuring the integration, please ensure, that the `nautobot-ssot` app was [installed with the Citrix ADM integration extra dependencies](../install.md#install-guide).
+
+```shell
+pip install nautobot-ssot[citrix-adm]
+```
+
+## Configuration
+
+Access to your Citrix ADM instance is defined using the [ExternalIntegration](https://docs.nautobot.com/projects/core/en/stable/user-guide/platform-functionality/externalintegration/) model which allows you to utilize this integration with multiple instances concurrently. Please bear in mind that it will synchronize all data 1:1 with the specified instance to match exactly, meaning it will delete data missing from an instance. Each ExternalIntegration must specify a SecretsGroup with Secrets that contain the Citrix ADM Username and Password to authenticate with. You can find Secrets and SecretsGroups available under the Secrets menu.
+
+![Citrix ADM Username](../../images/citrix_adm_username.png)
+
+![Citrix ADM Password](../../images/citrix_adm_password.png)
+
+![Citrix ADM SecretsGroup](../../images/citrix_adm_secretsgroup.png)
+
+The Secrets Group linked to the Citrix ADM ExternalIntegration must contain Secrets defined as per the below:
+
+| Access Type | Secret Type |
+| ----------- | ----------- |
+| HTTP(S)     | Username    |
+| HTTP(S)     | Password    |
+
+Once the SecretsGroup is created you'll need to create the ExternalIntegration. You'll find this under the Extensibility menu.
+
+![Citrix ADM ExternalIntegration](../../images/citrix_adm_externalintegration.png)
+
+> The only required portions are the Name, Remote URL, Verify SSL, and Secrets Group.
+
+When utilizing multiple SSoT integrations that contain differing Locations you might want to ensure that your existing Locations aren't updated by another integration. You can control whether these updates are made with the `citrix_adm_update_sites` setting in your `nautobot_config.py` file.
+
+| Configuration Variable                              | Type    | Usage                                                      | Default              |
+| --------------------------------------------------- | ------- | ---------------------------------------------------------- | -------------------- |
+| citrix_adm_update_sites                             | boolean | Whether to update loaded Datacenter Locations.             | True                 |
+
+Below is an example snippet from `nautobot_config.py` that demonstrates how to enable and configure the Citrix ADM integration:
+
+```python
+PLUGINS_CONFIG = {
+    "nautobot_ssot": {
+        "enable_citrix_adm": is_truthy(os.getenv("NAUTOBOT_SSOT_ENABLE_CITRIX_ADM", "true")),
+        "citrix_adm_update_sites": os.getenv("NAUTOBOT_SSOT_CITRIX_ADM_UPDATE_SITES", "true"),
+    }
+```
+
+Once the integration has been enabled you can find instructions on using it in the [Usage instructions](../../user/integrations/citrix_adm.md#usage).

docs/admin/integrations/index.md

@@ -4,6 +4,7 @@ This Nautobot app supports the following integrations:
 
 - [Cisco ACI](./aci_setup.md)
 - [Bootstrap](./bootstrap_setup.md)
+- [Citrix ADM](./citrix_adm_setup.md)
 - [Arista CloudVision](./aristacv_setup.md)
 - [Device42](./device42_setup.md)
 - [Cisco DNA Center](./dna_center_setup.md)

docs/user/integrations/citrix_adm.md

@@ -0,0 +1,61 @@
+# Citrix ADM SSoT Integration
+
+The Citrix ADM SSoT integration is built as part of the [Nautobot Single Source of Truth (SSoT)](https://github.com/nautobot/nautobot-app-ssot) app. The SSoT app enables Nautobot to be the aggregation point for data coming from multiple systems of record (SoR).
+
+From Citrix ADM into Nautobot, it synchronizes the following objects:
+
+| Citrix ADM              | Nautobot                     |
+| ----------------------- | ---------------------------- |
+| Datacenter              | Location*                    |
+| Devices                 | Devices                      |
+| Hardwares               | DeviceTypes                  |
+| OSVersions              | SoftwareVersions             |
+| Ports                   | Interfaces                   |
+| Prefixes                | Prefixes                     |
+| IP Addresses            | IP Addresses                 |
+
+## Usage
+
+Once the app is installed and configured, you will be able to perform an inventory ingestion from an individual or multiple Citrix ADM instances into Nautobot. From the Nautobot SSoT Dashboard view (`/plugins/ssot/`), Citrix ADM will show as a Data Source.
+
+![Dashboard View](../../images/citrix_adm_dashboard.png)
+
+From the Dashboard, you can also view more information about the App by clicking on the `Citrix ADM to Nautobot` link and see the Detail view. This view will show the mappings of Citrix ADM objects to Nautobot objects, the sync history, and other configuration details for the App:
+
+![Detail View](../../images/citrix_adm_detail-view.png)
+
+In order to utilize this integration you must first enable the Job. You can find the available installed Jobs under Jobs -> Jobs:
+
+![Job List](../../images/citrix_adm_job_list.png)
+
+To enable the Job you must click on the orange pencil icon to the right of the `Citrix ADM to Nautobot` Job. You will be presented with the settings for the Job as shown below:
+
+![Job Settings](../../images/citrix_adm_job_settings.png)
+
+You'll need to check the `Enabled` checkbox and then the `Update` button at the bottom of the page. You will then see that the play button next to the Job changes to blue and becomes functional, linking to the Job form.
+
+![Enabled Job](../../images/citrix_adm_enabled_job.png)
+
+Once the Job is enabled, you'll need to manually create a few objects in Nautobot to use with the Job. First, you'll need to create the Secrets, SecretsGroup, and ExternalIntegration as detailed in the [Citrix ADM Configuration](../../admin/integrations/citrix_adm_setup.md#configuration) instructions.
+
+> You can utilize multiple Citrix ADM Controllers with this integration as long as you specify a unique Tenant per Controller. The failure to use differing Tenants will have the Devices, Prefixes, and IPAddresses potentially removed if they are non-existent on the additional Controller. Locations should remain unaffected.
+
+With those configured, you will then need to define a LocationType to use for the imported Networks. With those created, you can run the Job to start the synchronization:
+
+![Job Form](../../images/citrix_adm_job_form.png)
+
+If you wish to just test the synchronization but not have any data created in Nautobot you'll want to select the `Dryrun` toggle. Clicking the `Debug` toggle will enable more verbose logging to inform you of what is occuring behind the scenes. After those toggles there are also dropdowns that allow you to specify the Citrix ADM instance(s) to synchronize with and to define the LocationType to use for the imported Datacenters from those instances. In addition, there are also some optional settings on the Job form:
+
+- Should the LocationType that you specify for the imported Networks require a parent Location to be assigned, you can define this parent one of two ways:
+
+1. The Parent Location field allows you to define a singular Location that will be assigned as the parent for all imported Datacenter Locations.
+
+2. The Location Mapping field allows you to define a dictionary of Location mappings. This feature is intended for specifying parent Locations for the Datacenter Locations in Citrix ADM. This is useful if this information is missing from Citrix ADM but required for Nautobot or to allow you to change the information as it's imported to match information from another System of Record. The expected pattern for this field is `{"<Location Name>": {"parent": "<Parent location Name>"}}`.
+
+In addition, the ability to assign Roles to your imported Devices as provided with the Hostname Mapping field. This field allows you to specify a list of tuples containing a regular expression pattern to match against Device hostnames and the Role to assign if matched. Ex: [(".*INT-LB.*", "Internal Load-Balancer")]
+
+- Finally there is an option to specify a Tenant to be assigned to the imported Devices, Prefixes, and IPAddresses. This is handy for cases where you have multiple Citrix ADM instances that are used by differing business units.
+
+Running this Job will redirect you to a `Nautobot Job Result` view.
+
+Once the Job has finished you can click on the `SSoT Sync Details` button at the top right of the Job Result page to see detailed information about the data that was synchronized from Citrix ADM and the outcome of the sync Job.

docs/user/integrations/index.md

@@ -3,8 +3,9 @@
 This Nautobot app supports the following integrations:
 
 - [Cisco ACI](./aci.md)
-- [Arista CloudVision](./aristacv.md)
 - [Bootstrap](./bootstrap.md)
+- [Arista CloudVision](./aristacv.md)
+- [Citrix ADM](./citrix_adm.md)
 - [Device42](./device42.md)
 - [Cisco DNA Center](./dna_center.md)
 - [Infoblox](./infoblox.md)

mkdocs.yml

@@ -109,8 +109,9 @@ nav:
       - Integrations:
           - "user/integrations/index.md"
           - Cisco ACI: "user/integrations/aci.md"
-          - Arista CloudVision: "user/integrations/aristacv.md"
           - Bootstrap: "user/integrations/bootstrap.md"
+          - Citrix ADM: "user/integrations/citrix_adm.md"
+          - Arista CloudVision: "user/integrations/aristacv.md"
           - Device42: "user/integrations/device42.md"
           - DNA Center: "user/integrations/dna_center.md"
           - Infoblox: "user/integrations/infoblox.md"
@@ -127,8 +128,9 @@ nav:
       - Integrations Installation:
           - "admin/integrations/index.md"
           - Cisco ACI: "admin/integrations/aci_setup.md"
-          - Arista CloudVision: "admin/integrations/aristacv_setup.md"
+          - Citrix ADM: "admin/integrations/citrix_adm_setup.md"
           - Bootstrap: "admin/integrations/bootstrap_setup.md"
+          - Arista CloudVision: "admin/integrations/aristacv_setup.md"
           - Device42: "admin/integrations/device42_setup.md"
           - DNA Center: "admin/integrations/dna_center_setup.md"
           - Infoblox: "admin/integrations/infoblox_setup.md"

nautobot_ssot/__init__.py

@@ -18,6 +18,7 @@
     "nautobot_ssot_aci",
     "nautobot_ssot_aristacv",
     "nautobot_ssot_bootstrap",
+    "nautobot_ssot_citrix_adm",
     "nautobot_ssot_device42",
     "nautobot_ssot_dna_center",
     "nautobot_ssot_infoblox",
@@ -83,6 +84,7 @@ class NautobotSSOTAppConfig(NautobotAppConfig):
         "aristacv_role_mappings": {},
         "aristacv_site_mappings": {},
         "aristacv_verify": True,
+        "citrix_adm_update_sites": True,
         "device42_host": "",
         "device42_username": "",
         "device42_password": "",
@@ -102,6 +104,7 @@ class NautobotSSOTAppConfig(NautobotAppConfig):
         "enable_aristacv": False,
         "enable_device42": False,
         "enable_dna_center": False,
+        "enable_citrix_adm": False,
         "enable_infoblox": False,
         "enable_ipfabric": False,
         "enable_servicenow": False,

nautobot_ssot/integrations/bootstrap/signals.py

@@ -95,11 +95,13 @@ def nautobot_database_ready_callback(sender, *, apps, **kwargs):  # pylint: disa
             print(f"Unable to find ValidatedSoftwareLCM model from Device Lifecycle Management App. {err}")
 
     sync_custom_field, _ = create_or_update_custom_field(
+        apps,
         key="last_synced_from_sor",
         field_type=CustomFieldTypeChoices.TYPE_DATE,
         label="Last sync from System of Record",
     )
     sor_custom_field, _ = create_or_update_custom_field(
+        apps,
         key="system_of_record",
         field_type=CustomFieldTypeChoices.TYPE_TEXT,
         label="System of Record",

nautobot_ssot/integrations/citrix_adm/__init__.py

@@ -0,0 +1 @@
+"""Base module for Citrix ADM integration."""

nautobot_ssot/integrations/citrix_adm/constants.py

@@ -0,0 +1,3 @@
+"""Constants for use within Nautobot SSoT for Citrix ADM."""
+
+DEVICETYPE_MAP = {"nsvpx": "NetScaler ADC VPX"}

nautobot_ssot/integrations/citrix_adm/diffsync/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapter classes for loading DiffSyncModels with data from Citrix ADM or Nautobot."""