docs: ✨ Add new example script to generate Preconfig YAML via Jinja template

Author: zachcamara-hpe

docs/source/examples/generate_preconfig.rst

@@ -18,6 +18,20 @@ partially or fully deployed in a Zero Touch Provisioning (ZTP) model
 where the appliance configuration is staged on Orchestrator prior to the
 appliance being approved into the SDWAN environment.
 
+Before running the code, make sure that the Python package ``jinja2`` is
+installed in your environment in addition to ``pyedgeconnect``.
+
+These are referenced in the ``requirements.txt`` file in the preconfig
+example directory
+
+.. code-block:: python
+
+    pip install -r requirements.txt
+    # OR
+    pip install pyedgeconnect
+    pip install jinja2
+
+
 EdgeConnect YAML Jinja Template
 ===============================
 
@@ -175,9 +189,21 @@ template correspond to the headers in the CSV file. If additional
 variables are added to the Jinja template, make sure to add appropriate
 columns in the CSV file.
 
-When leveraging default values and/or calculated values from source data
-you can limit the scope of how many unique values need to be provided
-in the CSV file.
+.. important::
+
+    The included CSV file has headers for all variables referenced in
+    the included Jinja template, however, due to default values and/or
+    other conditional logic, it may not be necessary to have columns
+    for every variable to generate a valid preconfig.
+
+Only a few example values are included in the CSV file in the
+repository as a starting point as valid values will vary from each
+Orchestrator environment, and many variables have default values that
+will be included via the Jinja template.
+
+Always reference the Orchestrator page ``Preconfigure Appliances`` with
+the built-in ``new`` preconfig to see acceptable values for specific
+preconfig options.
 
 Orchestrator API calls
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -219,4 +245,4 @@ To remove the preconfigs generated, the same runtime argument is used of
 This will retrieve all configured preconfigs on Orchestrator, find
 all preconfigs with a matching name as those in the CSV file, then
 prompt the user to confirm that those preconfigs should be removed from
-Orchestrator.
+Orchestrator.

examples/generate_preconfig/preconfig.csv

@@ -0,0 +1,2 @@
+softwareVersion,hostname,group,site,networkRole,region,address,address2,city,state,zipCode,country,latitude,longitude,name,email,phoneNumber,templateGroups,businessIntentOverlays,wan_interface_1_max_outbound_bw,wan_interface_2_max_outbound_bw,wan_interface_1_max_inbound_bw,wan_interface_2_max_inbound_bw,deploymentMode,shapeInboundTraffic,outboundMaxBandwidth,lan_interface_1_name,lan_interface_1_desc,lan_interface_1_ipmask,lan_interface_1_nexthop,lan_interface_1_segment,lan_interface_1_zone,lan_interface_2_name,lan_interface_2_desc,lan_interface_2_ipmask,lan_interface_2_nexthop,lan_interface_2_segment,lan_interface_2_zone,wan_interface_1_name,wan_interface_1_desc,wan_interface_1_label,wan_interface_1_ipmask,wan_interface_1_nexthop,wan_interface_1_firewall_mode,wan_interface_1_behind_nat,wan_interface_1_zone,wan_interface_2_name,wan_interface_2_desc,wan_interface_2_label,wan_interface_2_ipmask,wan_interface_2_nexthop,wan_interface_2_firewall_mode,wan_interface_2_behind_nat,wan_interface_2_zone,useSharedSubnetInfo,advertiseLocalLanSubnets,advertiseLocalWanSubnets,localMetric,localCommunities,redistOspfToSubnetShare,ospfRedistMetric,ospfRedistTag,filterRoutesWithLocalASN,redistToSDwanFabricRouteMap,useDefaultAccount,license_bandwidth,license_boost,bgp_asn,routerId,bgp_peer1_ip,bgp_peer1_asn,bgp_peer1_peer_type,bgp_peer1_inboundRouteMap,bgp_peer1_outboundRouteMap,bgp_peer1_keepAlive,bgp_peer1_holdTime,bgp_peer1_sourceIpInterface,bgp_peer1_asPrependCount,loopback_interfaceId,loopback_ipAddressMask,loopback_zone
+,TEST-EDGECONNECT,,,,,,,,,,,,,,,,Default Template Group,"RealTime, CriticalApps, BulkApps, DefaultOverlay",,,,,,,,lan0,,192.0.2.1/24,,,,,,,,,,wan0,,INET1,,,statefulSNAT,auto,,wan1,,INET2,,,statefulSNAT,auto,,,,,,,,,,,,,,100000,,,,,,,,,,,,,,

examples/generate_preconfig/preconfig.py

@@ -0,0 +1,224 @@
+import argparse
+import csv
+import datetime
+import getpass
+import os
+
+from jinja2 import Environment, FileSystemLoader
+from pyedgeconnect import Orchestrator
+
+# Parse runtime arguments
+parser = argparse.ArgumentParser()
+parser.add_argument(
+    "-c",
+    "--csv",
+    help="Specify source csv file for preconfigs",
+    type=str,
+    required=True,
+)
+parser.add_argument(
+    "-u",
+    "--upload",
+    help="Upload created valid preconfigs to Orchestrator",
+    type=bool,
+    default=False,
+)
+parser.add_argument(
+    "-aa",
+    "--autoapply",
+    help="Mark preconfigs for auto-approve",
+    type=bool,
+    default=False,
+)
+parser.add_argument(
+    "-j",
+    "--jinja",
+    help="specify source jinja2 template",
+    type=str,
+    default="ec_preconfig_template.jinja2",
+)
+parser.add_argument(
+    "-o",
+    "--orch",
+    help="specify Orchestrator URL",
+    type=str,
+)
+args = parser.parse_args()
+
+# Set Orchestrator FQDN/IP via arguments, environment variable,
+# or user input
+if vars(args)["orch"] is not None:
+    orch_url = vars(args)["orch"]
+elif os.getenv("ORCH_URL") is not None:
+    orch_url = os.getenv("ORCH_URL")
+else:
+    orch_url = input("Orchstrator IP or FQDN: ")
+
+# Set Orchestrator API Key via environment variable or user input
+if os.getenv("ORCH_API_KEY") is not None:
+    orch_api_key = os.getenv("ORCH_API_KEY")
+else:
+    orch_api_key_input = input("Orchstrator API Key (enter to skip): ")
+    if len(orch_api_key_input) == 0:
+        orch_api_key = None
+        # Set user and password if present in environment variable
+        orch_user = os.getenv("ORCH_USER")
+        orch_pw = os.getenv("ORCH_PASSWORD")
+    else:
+        orch_api_key = orch_api_key_input
+
+# Instantiate Orchestrator with ``log_console`` enabled for
+# printing log messages to terminal
+orch = Orchestrator(
+    orch_url,
+    api_key=orch_api_key,
+    log_console=True,
+    verify_ssl=False,
+)
+
+# If not using API key, login to Orchestrator with username/password
+if orch_api_key is None:
+    # If username/password not in environment variables, prompt user
+    if orch_user is None:
+        orch_user = input("Enter Orchestrator username: ")
+        orch_pw = getpass.getpass("Enter Orchestrator password: ")
+    # Check if multi-factor authentication required
+    mfa_prompt = input("Are you using MFA for this user (y/n)?: ")
+    if mfa_prompt == "y":
+        orch.send_mfa(orch_user, orch_pw, temp_code=False)
+        token = input("Enter MFA token: ")
+    else:
+        token = ""
+    # Login to Orchestrator
+    confirm_auth = orch.login(orch_user, orch_pw, mfacode=token)
+    # Check that user/pass authentication works before proceeding
+    if confirm_auth:
+        pass
+    else:
+        print("Authentication to Orchestrator Failed")
+        exit()
+# If API key specified, check that key is valid before proceeding
+else:
+    confirm_auth = orch.get_orchestrator_hello()
+    if confirm_auth != "There was an internal server error.":
+        pass
+    else:
+        print("Authentication to Orchestrator Failed")
+        exit()
+
+# Specify CSV file for generating preconfigs
+# This is a mandatory runtime argument
+if vars(args)["csv"] is not None:
+    csv_filename = vars(args)["csv"]
+else:
+    print("Source CSV file not specified, exiting")
+    exit()
+
+# Setting if configs should be uploaded to Orchestrator, argument
+# defaults to False if not specified
+upload_to_orch = vars(args)["upload"]
+
+# Setting if discovered appliance with matching serial number or tag
+# will be automatically approved and deployed with corresponding
+# preconfig. Argument defaults to False if not specified
+auto_apply = vars(args)["autoapply"]
+
+# Specify alternate Jinja2 template file for generating preconfig
+# in the templates directory. Otherwise use default template.
+ec_template_file = vars(args)["jinja"]
+
+
+# Retrieve Jinja2 template for generating EdgeConnect Preconfig YAML
+# Setting ``trim_blocks`` and ``lstrip_blocks`` reduces excessive
+# whitepsace from the jinja template conditionals etc.
+env = Environment(
+    loader=FileSystemLoader("templates"),
+    trim_blocks=True,
+    lstrip_blocks=True,
+)
+ec_template = env.get_template(ec_template_file)
+
+# Local directory for configuration outputs
+output_directory = "preconfig_outputs/"
+if not os.path.exists(output_directory):
+    os.makedirs(output_directory)
+
+# Open CSV file with configuration data
+with open(csv_filename, encoding="utf-8-sig") as csvfile:
+    csv_dict = csv.DictReader(csvfile)
+
+    # Set initial row number for row identification of data
+    # First row is headers
+    row_number = 2
+
+    # Generate Edge Connect YAML preconfig for each row in data
+    for row in csv_dict:
+
+        # Render CSV values through the Jinja template
+        yaml_preconfig = ec_template.render(data=row)
+
+        # Set value for serial number if provided
+        appliance_serial = row.get("serial_number")
+        if appliance_serial is None:
+            appliance_serial = ""
+        else:
+            pass
+
+        # Validate preconfig via Orchestrator
+        validate = orch.validate_preconfig(
+            hostname=row["hostname"],
+            yaml_preconfig=yaml_preconfig,
+            auto_apply=auto_apply,
+        )
+
+        # If the validate function passes on Orchestrator write
+        # preconfig to local file and check if uploading to Orchestrator
+        if validate.status_code == 200:
+
+            # Write local YAML file
+            yaml_filename = "{}_preconfig.yml".format(row["hostname"])
+            with open(output_directory + yaml_filename, "w") as preconfig_file:
+                write_data = preconfig_file.write(yaml_preconfig)
+
+            # If upload option was chosen, upload preconfig to
+            # Orchestrator with selected auto-apply settings
+            if upload_to_orch is True:
+
+                # In this example the appliance hostname from the CSV
+                # data (row["hostname"]) is used both for the name of
+                # the preconfig to appear in Orchestrator, as well as
+                # the tag on the preconfig that could be used to match
+                # against a discovered appliance
+                # Additionally a comment is added with the current
+                # date
+                orch.create_preconfig(
+                    hostname=row["hostname"],
+                    yaml_preconfig=yaml_preconfig,
+                    auto_apply=auto_apply,
+                    tag=row["hostname"],
+                    comment="Created/Uploaded @ {}".format(
+                        datetime.date.today().strftime("%d %B %Y")
+                    ),
+                )
+                print("Posted EC Preconfig {}".format(row["hostname"]))
+            else:
+                pass
+        else:
+            print(
+                "Preconfig for {} failed validation | error: {}".format(
+                    row["hostname"], validate.text
+                )
+            )
+            # Write local YAML file of failed config for reference
+            yaml_filename = "{}_preconfig-FAILED.yml".format(row["hostname"])
+            with open(output_directory + yaml_filename, "w") as preconfig_file:
+                write_data = preconfig_file.write(yaml_preconfig)
+
+        # Increment row number when iterating to next row in CSV
+        row_number += 1
+
+# if not using API key, logout from Orchestrator
+if orch_api_key is None:
+    orch.logout()
+else:
+    pass