airship/spyglass-plugin-xls
Code Issues Proposed changes

Docs update for Spyglass Excel Plugin

Browse Source 
Removed all tugboat refernces, added getting started guide to
explain installation and steps to run, and reformated so that
all the informantion was not in the index file.

Change-Id: I20234c1c7565794d81d25565fddb2879df460d9b
This commit is contained in:
Ryan Schroder 2019-12-16 10:08:40 -06:00
parent a4c09b699f
commit f9df9d1886
4 changed files with 247 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
README.rst
View File

@ -1,10 +1,26 @@
..
Copyright 2019 AT&T Intellectual Property.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Spyglass Excel Plugin
---------------------
Tugboat is a Spyglass plugin to generate airship-seaworthy site manifest files
from an excel based engineering spec. The plugin is configured with an Excel
sheet and its corresponding excel specification as inputs. Spyglass uses this
plugin to construct an intermediary yaml which is processed further using J2
templates to generate site manifests.
The Spyglass Excel Plugin is used to generate airship-seaworthy site
manifest files from an excel based engineering spec. The plugin is
configured with an Excel sheet and its corresponding excel specification as
inputs. Spyglass uses this plugin to construct an intermediary yaml which is
processed further using J2 templates to generate site manifests.
Spyglass: https://opendev.org/airship/spyglass

141
doc/source/excel_specification.rst Normal file
View File

@ -0,0 +1,141 @@
..
Copyright 2019 AT&T Intellectual Property.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
===================
Excel Specification
===================
Excel Spec is like an index to the Excel sheet to look for the data to be
collected by the tool. The excel_spec.yaml file provides a sample structure for
an excel specification based off the SiteDesignSpec_v0.1.xlsx sheet. (Both can
be found in the examples folder)
Below is the definition for each key in the Excel spec
+ **ipmi**
* type - How the data is stored (series/container/point)
* sheet_name - Name of the sheet from where IPMI information is to be read
(File name, excluding the file extension, when using a CSV file)
* iter
+ index-type - How data is indexed (row/col)
+ start - Row/Col number where ipmi data begins
+ end - Row/Col number where ipmi data ends
* data
+ hostname - location of the hostname (row/col/[r, c])
+ ipmi_address - location of the ipmi address (row/col/[r, c])
+ ipmi_gateway - location of the ipmi gateway (row/col/[r, c])
+ host_profile - location of the host profile (row/col/[r, c])
+ **private_vlan**
* type - How the data is stored (series/container/point)
* sheet_name - Name of the sheet from where private vlan information is to
be read (File name, excluding the file extension, when using a CSV file)
* no_sanitize - Names of values that should not be sanitized
* iter
+ index-type - How data is indexed (row/col)
+ start - Row/Col number where private vlan data begins
+ end - Row/Col number where private vlan data ends
* data
+ net_type - location of the net type (row/col/[r, c])
+ vlan - location of the vlan (row/col/[r, c])
+ **private_net**
* type - How the data is stored (series/container/point)
* sheet_name - Name of the sheet from where private net information is to
be read (File name, excluding the file extension, when using a CSV file)
* iter
+ index-type - How data is indexed (row/col)
+ start - Row/Col where private vlan data begins
+ end - Row/Col where private vlan data ends
* data
+ vlan - location of the vlan (row/col/[r, c])
+ ip - location of the ip (row/col/[r, c])
+ **public**
* type - How the data is stored (series/container/point)
* sheet_name - Name of the sheet from where public information is to be
read (File name, excluding the file extension, when using a CSV file)
* data
+ oam
* type - How the data is stored (series/container/point)
* data
+ vlan - location of the vlan (row/col/[r, c])
+ ip - location of the ip (row/col/[r, c])
+ ingress
* type - How the data is stored (series/container/point)
* data
+ ip - location of the ip (row/col/[r, c])
+ oob
* type - How the data is stored (series/container/point)
* iter
+ index-type - How data is indexed (row/col)
+ start - Row/Col where private vlan data begins
+ end - Row/Col where private vlan data ends
* data
+ ip - location of the ip (row/col/[r, c])
+ **site_info**
* type - How the data is stored (series/container/point)
* sheet_name - Name of the sheet from where site information is to be read
(File name, excluding the file extension, when using a CSV file)
* sanitize - If data should be sanitised (boolean)
* data
+ domain - location of the domain (row/col/[r, c])
+ subdomain - location of the subdomain (row/col/[r, c])
+ global_group - location of the global group (row/col/[r, c])
+ ldap - location of the ldap (row/col/[r, c])
+ ntp - location of the ntp (row/col/[r, c])
+ dns - location of the dns (row/col/[r, c])
+ **location**
* type - How the data is stored (series/container/point)
* sheet_name - Name of the sheet from where location information is to be
read (File name, excluding the file extension, when using a CSV file)
* sanitize - If data should be sanitised (boolean)
* data
+ sitename - location of the sitename (row/col/[r, c])
+ corridor - location of the corridor (row/col/[r, c])
+ state - location of the state (row/col/[r, c])
+ country - location of the country (row/col/[r, c])
+ clli - location of the clli (row/col/[r, c])

74
doc/source/getting_started.rst Normal file
View File

@ -0,0 +1,74 @@
..
Copyright 2019 AT&T Intellectual Property.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
===============
Getting Started
===============
This document explains the steps to installing and setting up the Spyglass
Excel plugin.
1.) Clone the Spyglass Excel plugin::
git clone https://opendev.org/airship/spyglass-plugin-xls.git
2.) Clone Spyglass::
git clone https://opendev.org/airship/spyglass.git
3.) Install required packages in Spyglass directory::
pip3 install pipenv && pipenv install
4.) Launch the pipenv from your spyglass directory::
pipenv shell
5.) Install Spyglass and the Spyglass Excel plugin into the pipenv::
pip3 install . && pip3 install ../spyglass-plugin-xls/.
6.) You can now run Spyglass commands from the pipenv.
Examples
--------
1. Required Input (Refer to 'spyglass_plugin_xls/examples' folder to get these
inputs)
a) Excel File: SiteDesignSpec_v0.1.xlsx
b) Excel Spec: excel_spec_upstream.yaml
c) Site Config: 'spyglass/examples/site_config.yaml'
d) Template_dir: 'spyglass/examples/templates'
e) Site name: airship-seaworthy
2. Spyglass CLI Command using an Excel File:
.. code-block:: bash
spyglass excel documents -i -x ../spyglass-plugin-xls/spyglass_plugin_xls/examples/SiteDesignSpec_v0.1.xlsx \
-e ../spyglass-plugin-xls/spyglass_plugin_xls/examples/excel_spec.yaml \
-c ../spyglass-plugin-xls/spyglass_plugin_xls/examples/site_config.yaml \
-s airship-seaworthy -t spyglass/examples/templates/
3. Spyglass CLI Command using a CSV File:
.. code-block:: bash
spyglass excel documents -i -x ../spyglass-plugin-xls/spyglass_plugin_xls/examples/Site-Information.csv \
-e ../spyglass-plugin-xls/spyglass_plugin_xls/examples/excel_spec.yaml \
-c ../spyglass-plugin-xls/spyglass_plugin_xls/examples/site_config.yaml \
-s airship-seaworthy -t spyglass/examples/templates/

111
doc/source/index.rst
View File

@ -14,109 +14,20 @@
License for the specific language governing permissions and limitations
under the License.
.. _tugboatinfo:
=====================
Spyglass Excel Plugin
=====================
===================
Spyglass XLS Plugin
===================
What is the Spyglass XLS Plugin?
--------------------------------
The Spyglass XLS plugin is used to generate airship-seaworthy site manifest
files from an excel based engineering spec. The plugin is configured with an
Overview
--------
The Spyglass Excel plugin is used to generate airship-seaworthy site manifest
files from an Excel based engineering spec. The plugin is configured with an
Excel sheet or a CSV file and its corresponding excel specification as inputs.
Spyglass uses this plugin to construct an intermediary yaml which is processed
further using Jinja2 templates to generate site manifests.
Excel Specification
-------------------
Excel Spec is like an index to the Excel sheet to look for the data to be
collected by the tool. Excel Spec Sample specifies all the details that
need to be filled by the Deployment Engineer.
.. toctree::
:maxdepth: 2
Below is the definition for each key in the Excel spec
* ipmi_sheet_name - name of the sheet from where IPMI and host profile
information is to be read (File name, excluding the file extension, when
using a CSV file)
* start_row - row number from where the IPMI and host profile information
starts
* end_row - row number from where the IPMI and host profile information ends
* hostname_col - column number where the hostnames are to be read from
* ipmi_address_col - column number from where the ipmi addresses are to be read
* host_profile_col - column number from where the host profiles are to be read
* ipmi_gateway_col - column number from where the ipmi gateways are to be read
* private_ip_sheet - name of the sheet which has the private IP information
* net_type_col - column number from where the network type is to be read
* vlan_col - column number from where the network vlan is to be read
* vlan_start_row - row number from where the vlan information starts
* vlan_end_row - row number from where the vlan information ends
* net_start_row - row number from where the network information starts
* net_end_row - row number from where the network information ends
* net_col - column number where the IP ranges for network is to be read
* net_vlan_col - column number where the vlan information is present in the
pod wise network section
* public_ip_sheet - name of the sheet which has the public IP information
* oam_vlan_col - column number from where the OAM vlan information is to be
read from
* oam_ip_row - row number from where the OAM network information is to be read
from
* oam_ip_col - column number from where the OAM network information is to be
read from
* oob_net_row - row number which has the OOB network subnet ranges
* oob_net_start_col - column number from where the OOB network ranges start
* oob_net_end_col - column number from where the OOB network ranges end
* ingress_ip_row - row number from where the Ingress network information is to
be read from
* dns_ntp_ldap_sheet - name of the sheet which has the DNS, NTP and LDAP
information
* login_domain_row - row number which has the ldap login domain
* ldap_col - column number which has the all ldap related information
* global_group - row number which has the ldap group information
* ldap_search_url_row - row number which has the ldap url
* ntp_row - row number which has the ntp information
* ntp_col - column number which has the ntp information
* dns_row - row number which has the dns information
* dns_col - column number which has the dns information
* domain_row - row number which has the domain information
* domain_col - column number which has the domain information
* location_sheet - name of the sheet which has the location information
* column - column number which has all the information
* corridor_row - row number which has the corridor information
* site_name_row - row number which has the site name
* state_name_row - row number which has the state name
* country_name_row - row number which has the country name
* clli_name_row - row number which has CLLI information
Example: Spyglass XLS Plugin Usage
----------------------------------
1. Required Input (Refer to 'spyglass_plugin_xls/examples' folder to get these
inputs)
a) Excel File: SiteDesignSpec_v0.1.xlsx
b) Excel Spec: excel_spec_upstream.yaml
c) Site Config: site_config.yaml
d) Template_dir: 'spyglass/examples/templates'
e) Site name: airship-seaworthy
2. Spyglass CLI Command using an Excel File:
.. code-block:: bash
spyglass excel documents -i \
-x ../spyglass-plugin-xls/spyglass_plugin_xls/examples/SiteDesignSpec_v0.1.xlsx \
-e ../spyglass-plugin-xls/spyglass_plugin_xls/examples/excel_spec.yaml \
-c ../spyglass-plugin-xls/spyglass_plugin_xls/examples/site_config.yaml \
-s airship-seaworthy -t spyglass/examples/templates/
3. Spyglass CLI Command using a CSV File:
.. code-block:: bash
spyglass excel documents -i \
-x ../spyglass-plugin-xls/spyglass_plugin_xls/examples/Site-Information.csv \
-e ../spyglass-plugin-xls/spyglass_plugin_xls/examples/excel_spec.yaml \
-c ../spyglass-plugin-xls/spyglass_plugin_xls/examples/site_config.yaml \
-s airship-seaworthy -t spyglass/examples/templates/
getting_started
excel_specification